{ "openapi": "3.1.0", "info": { "title": "Auction Plus Storefront API Documentation", "version": "1.0.0", "description": "The Auction Plus Storefront API powers the customer-facing experience on your Shopify storefront.\n\n## Rate Limiting\n\nUnlike the Admin API, which meters requests per authenticated shop, the Storefront API applies a rate limit per **buyer IP address**.\n\nWhen a request is made, it is added to the bucket. If the bucket is full, the API responds with a `429 Too Many Requests` status.\n\nBucket capacity and leak rate are subject to change. Read the current values from the response headers rather than hard-coding them.\n" }, "servers": [ { "url": "https://api.auctionplusapp.com/storefront/v1" } ], "tags": [ { "name": "Auction Items", "description": "An auction item represents a single listing in an auction. Each item has a **status** of `scheduled`, `active`, or `completed`.\n\nPrice attributes such as **startPrice**, **minimumBid**, **currentIncrement**, and **highBidAmount** are returned as a price object containing **value** (minor units), **major**, **display**, and **currency** fields.\n\nThe **bidIncrementStrategy** describes the increment type \u2014 `fixed_amount`, `percentage`, or `tier` \u2014 along with a **value** object containing the increment details.\n\nThe **automaticBidding** and **softClose** objects expose a single `enabled` boolean indicating whether each feature is active for the item.\n\nThe **reserveMet** boolean indicates whether the current high bid meets the auction's reserve, without exposing the reserve price itself. The **processed** attribute indicates whether the listing has been finalized, including assigning a winner. Listings are typically processed within a minute after the end time.\n\nPer-viewer fields (whether the authenticated customer has bid, is the high bidder, or is watching the item) are opt-in. Request fields by name with the `viewerFields` query parameter (e.g. `viewerFields=hasBid,isWatching`)." }, { "name": "Bids", "description": "A bid represents a single direct or max bid placed on an auction item. The list endpoint returns the public bid history for a listing.\n\nThe **amount** is returned as a price object containing **value** (minor units), **major**, **display**, and **currency** fields.\n\nThe **submittedAt** attribute represents when the bidder originally submitted the bid. For automatic bids, this is when the customer submitted the associated max bid. The **placedAt** attribute represents when the bid was placed into the system.\n\nInclude **customer** to return the bidder relationship for each bid. Bidder names are masked unless the shop has chosen to reveal bidders, or the bidder is the authenticated customer.\n\nPer-viewer fields are opt-in. Request fields by name with the `viewerFields` query parameter (e.g. `viewerFields=isOwner`)." }, { "name": "Variants", "description": "A variant is a Shopify product variant that Auction Plus tracks for a shop. The **externalId** attribute is the Shopify variant ID, and **displayName** combines the product and variant titles for display. The **price** attribute is returned as a price object containing **value** (minor units), **major**, **display**, and **currency** fields.\n\nVariants are looked up by Shopify variant ID through the required `filter[externalId]` parameter.\n\nInclude **currentAuctionItem** to return the variant's live auction item alongside it." }, { "name": "Watched Items", "description": "A watched item is a product variant the authenticated customer is following.\n\nThe **automatic** attribute indicates the item was followed on the customer's behalf. Items are followed automatically when the customer places a bid.\n\nWatch and unwatch calls take an **externalVariantId** representing the Shopify variant ID.\n\nThe list endpoint returns the customer's watched variants, most recently updated first, and excludes variants whose product is no longer available on the storefront. Filter with `filter[listingType]` to return only variants currently listed as an `auction` or only those listed as a regular `product`.\n\nInclude **variant.currentAuctionItem** to return the live auction item for each watched variant." } ], "security": [ { "http": [] }, { "apiKey": [] } ], "paths": { "/auction-items": { "get": { "operationId": "listAuctionItems", "description": "Returns a paginated list of auction items that are scheduled, active, or completed. Canceled and archived items are excluded.", "summary": "List auction items", "tags": [ "Auction Items" ], "parameters": [ { "name": "filter[status]", "in": "query", "schema": { "type": "string", "enum": [ "active", "scheduled", "completed" ] } }, { "name": "filter[viewerHasBid]", "in": "query", "description": "Limit results to auction items the authenticated customer has bid on.", "schema": { "type": "string", "enum": [ "true", "false", "1", "0" ] } }, { "name": "filter[eventId]", "in": "query", "schema": { "type": "string" } }, { "name": "viewerFields", "in": "query", "description": "Comma-separated per-viewer fields to return under `meta.viewer` on the resource and any included resources. Available values: `hasBid`, `isWatching`, `isHighBidder`, `isOwner`. Requires an authenticated customer.", "schema": { "type": [ "string", "null" ] } }, { "name": "perPage", "in": "query", "description": "Results per page (1\u2013100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "fields[auction-items]", "in": "query", "description": "Available values are `startPrice`, `bidIncrementStrategy`, `automaticBidding`, `softClose`, `totalBids`, `highBidAmount`, `minimumBid`, `currentIncrement`, `startsAt`, `endsAt`, `position`, `status`, `enableReserve`, `reserveMet`, `processed`, `createdAt`, `updatedAt`, `canceledAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[variants]", "in": "query", "description": "Available values are `externalId`, `displayName`, `title`, `price`, `photoUrl`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[products]", "in": "query", "description": "Available values are `externalId`, `title`, `vendor`, `type`, `photoUrl`, `handle`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[bids]", "in": "query", "description": "Available values are `amount`, `submittedAt`, `placedAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[max-bids]", "in": "query", "description": "Available values are `amount`, `createdAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[auction-winners]", "in": "query", "description": "Available values are `amount`, `notifiedAt`, `paymentDueAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "description": "Comma-separated list of related resources to include in the response. Available values: `variant`, `product`, `highBid`, `highBid.customer`, `viewerMaxBid`, `viewerWin`.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort by field. Prefix with `-` for descending order. Available values: `startsAt`, `-startsAt`, `endsAt`, `-endsAt`, `totalBids`, `-totalBids`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `AuctionItemResource`", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/AuctionItemResource" }, { "type": "object", "properties": { "relationships": { "type": "object", "properties": { "variant": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "variants" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "product": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "products" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "highBid": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bids" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "viewerMaxBid": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "max-bids" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "viewerWin": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auction-winners" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } } } } } } ] } }, "meta": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "lastPage": { "type": "integer", "minimum": 1 }, "perPage": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "currentPage", "from", "lastPage", "perPage", "to", "total" ] } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "The provided user does not have access to this resource.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "examples": [ { "errors": [ { "status": "401", "code": "unauthorized", "detail": "The provided user does not have access to this resource." } ] } ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "The HTTP status code applicable to this problem, expressed as a string." }, "code": { "type": "string", "description": "An application-specific error code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "id": { "type": "string", "description": "A unique identifier for this particular occurrence of the problem." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "source": { "type": "object", "description": "An object containing references to the source of the error.", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" }, "header": { "type": "string" } } }, "meta": { "type": "object", "description": "A meta object containing additional information about the error." } }, "required": [ "status", "code", "detail" ] } } }, "required": [ "errors" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/auction-items/search": { "get": { "operationId": "searchAuctionItems", "description": "Returns a paginated list of auction items that match the search query.", "summary": "Search auction items", "tags": [ "Auction Items" ], "parameters": [ { "name": "filter[status]", "in": "query", "schema": { "type": "string", "enum": [ "active", "scheduled", "completed" ] } }, { "name": "filter[viewerHasBid]", "in": "query", "description": "Limit results to auction items the authenticated customer has bid on.", "schema": { "type": "string", "enum": [ "true", "false", "1", "0" ] } }, { "name": "filter[eventId]", "in": "query", "schema": { "type": "string" } }, { "name": "viewerFields", "in": "query", "description": "Comma-separated per-viewer fields to return under `meta.viewer` on the resource and any included resources. Available values: `hasBid`, `isWatching`, `isHighBidder`, `isOwner`. Requires an authenticated customer.", "schema": { "type": [ "string", "null" ] } }, { "name": "perPage", "in": "query", "description": "Results per page (1\u2013100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "query", "in": "query", "required": true, "description": "The text to match against auction item titles.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "fields[auction-items]", "in": "query", "description": "Available values are `startPrice`, `bidIncrementStrategy`, `automaticBidding`, `softClose`, `totalBids`, `highBidAmount`, `minimumBid`, `currentIncrement`, `startsAt`, `endsAt`, `position`, `status`, `enableReserve`, `reserveMet`, `processed`, `createdAt`, `updatedAt`, `canceledAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[variants]", "in": "query", "description": "Available values are `externalId`, `displayName`, `title`, `price`, `photoUrl`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[products]", "in": "query", "description": "Available values are `externalId`, `title`, `vendor`, `type`, `photoUrl`, `handle`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[bids]", "in": "query", "description": "Available values are `amount`, `submittedAt`, `placedAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[max-bids]", "in": "query", "description": "Available values are `amount`, `createdAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[auction-winners]", "in": "query", "description": "Available values are `amount`, `notifiedAt`, `paymentDueAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "description": "Comma-separated list of related resources to include in the response. Available values: `variant`, `product`, `highBid`, `highBid.customer`, `viewerMaxBid`, `viewerWin`.", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "description": "Sort by field. Prefix with `-` for descending order. Available values: `startsAt`, `-startsAt`, `endsAt`, `-endsAt`, `totalBids`, `-totalBids`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `AuctionItemResource`", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/AuctionItemResource" }, { "type": "object", "properties": { "relationships": { "type": "object", "properties": { "variant": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "variants" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "product": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "products" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "highBid": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bids" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "viewerMaxBid": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "max-bids" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "viewerWin": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auction-winners" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } } } } } } ] } }, "meta": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "lastPage": { "type": "integer", "minimum": 1 }, "perPage": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "currentPage", "from", "lastPage", "perPage", "to", "total" ] } }, "required": [ "data", "meta" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/auction-items/{id}": { "get": { "operationId": "getAuctionItem", "description": "Retrieves the details for a single auction item.", "summary": "Retrieve an auction item", "tags": [ "Auction Items" ], "parameters": [ { "name": "viewerFields", "in": "query", "description": "Comma-separated per-viewer fields to return under `meta.viewer` on the resource and any included resources. Available values: `hasBid`, `isWatching`, `isHighBidder`, `isOwner`. Requires an authenticated customer.", "schema": { "type": [ "string", "null" ] } }, { "name": "fields[auction-items]", "in": "query", "description": "Available values are `startPrice`, `bidIncrementStrategy`, `automaticBidding`, `softClose`, `totalBids`, `highBidAmount`, `minimumBid`, `currentIncrement`, `startsAt`, `endsAt`, `position`, `status`, `enableReserve`, `reserveMet`, `processed`, `createdAt`, `updatedAt`, `canceledAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[variants]", "in": "query", "description": "Available values are `externalId`, `displayName`, `title`, `price`, `photoUrl`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[products]", "in": "query", "description": "Available values are `externalId`, `title`, `vendor`, `type`, `photoUrl`, `handle`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[bids]", "in": "query", "description": "Available values are `amount`, `submittedAt`, `placedAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[max-bids]", "in": "query", "description": "Available values are `amount`, `createdAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[auction-winners]", "in": "query", "description": "Available values are `amount`, `notifiedAt`, `paymentDueAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "The auction item UID.", "schema": { "type": "string" }, "example": "1c6af60by54hzdmgxy5ab4ypw0" }, { "name": "include", "in": "query", "description": "Comma-separated list of related resources to include in the response. Available values: `variant`, `product`, `highBid`, `highBid.customer`, `viewerMaxBid`, `viewerWin`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`AuctionItemResource`", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/AuctionItemResource" }, { "type": "object", "properties": { "relationships": { "type": "object", "properties": { "variant": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "variants" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "product": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "products" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "highBid": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bids" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "viewerMaxBid": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "max-bids" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "viewerWin": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auction-winners" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } } } } } } ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/auction-items/{id}/place-bid": { "post": { "operationId": "placeBid", "description": "Places a bid on an active auction item on behalf of the authenticated storefront customer.\n\nYou must provide either **maxAmount** for a maximum bid (automatic bidding), **amount** for a straight bid, or both.\n\n- **Straight bid** (`amount`): Places a single bid at the specified amount.\n- **Proxy bid** (`maxAmount`): Sets the maximum amount the system will automatically bid up to on behalf of the customer. The system places the minimum winning bid and automatically increments as competing bids are received, up to the maximum.\n- **Both** (`amount` + `maxAmount`): Places a straight bid at the specified amount and sets a proxy maximum for automatic bidding.\n\nThe response returns the updated **auction item** with a `meta.status` field indicating whether the customer is the `high_bidder` or was automatically `outbid` by proxy bidding.", "summary": "Place a bid", "tags": [ "Auction Items" ], "parameters": [ { "name": "fields[auction-items]", "in": "query", "description": "Available values are `startPrice`, `bidIncrementStrategy`, `automaticBidding`, `softClose`, `totalBids`, `highBidAmount`, `minimumBid`, `currentIncrement`, `startsAt`, `endsAt`, `position`, `status`, `enableReserve`, `reserveMet`, `processed`, `createdAt`, `updatedAt`, `canceledAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[variants]", "in": "query", "description": "Available values are `externalId`, `displayName`, `title`, `price`, `photoUrl`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[products]", "in": "query", "description": "Available values are `externalId`, `title`, `vendor`, `type`, `photoUrl`, `handle`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[bids]", "in": "query", "description": "Available values are `amount`, `submittedAt`, `placedAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[max-bids]", "in": "query", "description": "Available values are `amount`, `createdAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[auction-winners]", "in": "query", "description": "Available values are `amount`, `notifiedAt`, `paymentDueAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "The auction item UID.", "schema": { "type": "string" }, "example": "1c6af60by54hzdmgxy5ab4ypw0" }, { "name": "viewerFields", "in": "query", "description": "Comma-separated per-viewer fields to return under `meta.viewer` on the resource and any included resources. Available values: `hasBid`, `isWatching`, `isHighBidder`, `isOwner`. Requires an authenticated customer.", "schema": { "type": "string" }, "example": "hasBid,isWatching" }, { "name": "include", "in": "query", "description": "Comma-separated list of related resources to include in the response. Available values: `variant`, `product`, `highBid`, `highBid.customer`, `viewerMaxBid`, `viewerWin`.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": [ "number", "null" ], "description": "The bid amount in major currency units (e.g. 10.50).", "minimum": 0 }, "maxAmount": { "type": [ "number", "null" ], "description": "The maximum (proxy) bid in major currency units (e.g. 10.50).", "minimum": 0 } } } } } }, "responses": { "200": { "description": "`AuctionItemResource`", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/AuctionItemResource" }, { "type": "object", "properties": { "relationships": { "type": "object", "properties": { "variant": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "variants" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "product": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "products" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "highBid": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bids" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "viewerMaxBid": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "max-bids" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "viewerWin": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auction-winners" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } } } } } } ] }, "meta": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "outbid", "high_bidder" ] } }, "required": [ "status" ] } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "The provided user does not have access to this resource.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "examples": [ { "errors": [ { "status": "401", "code": "unauthorized", "detail": "The provided user does not have access to this resource." } ] } ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "The HTTP status code applicable to this problem, expressed as a string." }, "code": { "type": "string", "description": "An application-specific error code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "id": { "type": "string", "description": "A unique identifier for this particular occurrence of the problem." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "source": { "type": "object", "description": "An object containing references to the source of the error.", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" }, "header": { "type": "string" } } }, "meta": { "type": "object", "description": "A meta object containing additional information about the error." } }, "required": [ "status", "code", "detail" ] } } }, "required": [ "errors" ] } } } }, "422": { "description": "The bid could not be placed. Inspect `errors[0].code` for the specific reason:\n\n- `access_denied` \u2014 the customer is not permitted to bid (e.g. not approved for bidder registration).\n- `auction_ended` \u2014 the auction has already ended.\n- `amount_below_start_price` \u2014 the straight bid `amount` is below the auction's start price.\n- `amount_below_showing_bid` \u2014 the straight bid `amount` is at or below the current high bid plus the required increment. `meta.minimum_bid` shows the minimum acceptable value.\n- `max_amount_below_start_price` \u2014 the max bid `maxAmount` is below the auction's start price. `meta.minimum_bid` shows the start price.\n- `max_amount_below_showing_bid` \u2014 the max bid `maxAmount` is at or below the current high bid plus the required increment. `meta.minimum_bid` shows the minimum acceptable value.\n- `max_amount_below_current_bid` \u2014 the customer is already the high bidder and the new `maxAmount` is lower than their existing showing bid. `meta.minimum_bid` shows the existing bid amount.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "examples": [ { "errors": [ { "status": "422", "code": "validation_error", "detail": "The selected field is invalid.", "source": { "parameter": "field_name" }, "meta": { "rule": "required" } } ] }, { "errors": [ { "status": "422", "code": "access_denied", "detail": "The customer is not permitted to perform this action." } ] }, { "errors": [ { "status": "422", "code": "auction_ended", "detail": "This auction has ended and bids are no longer being accepted." } ] }, { "errors": [ { "status": "422", "code": "amount_below_start_price", "detail": "The amount must be greater than the start price." } ] }, { "errors": [ { "status": "422", "code": "amount_below_showing_bid", "detail": "The amount must be greater than the leading bid plus the bid increment.", "meta": { "minimum_bid": "55.00" } } ] }, { "errors": [ { "status": "422", "code": "max_amount_below_start_price", "detail": "The max bid amount must be greater than the start price.", "meta": { "minimum_bid": "1.00" } } ] }, { "errors": [ { "status": "422", "code": "max_amount_below_showing_bid", "detail": "The max bid amount must be greater than or equal to the showing bid plus the bid increment.", "meta": { "minimum_bid": "55.00" } } ] }, { "errors": [ { "status": "422", "code": "max_amount_below_current_bid", "detail": "The max bid amount must be greater than or equal to the current bid.", "meta": { "minimum_bid": "50.00" } } ] } ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "The HTTP status code applicable to this problem, expressed as a string." }, "code": { "type": "string", "description": "An application-specific error code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "id": { "type": "string", "description": "A unique identifier for this particular occurrence of the problem." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "source": { "type": "object", "description": "An object containing references to the source of the error.", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" }, "header": { "type": "string" } } }, "meta": { "type": "object", "description": "A meta object containing additional information about the error." } }, "required": [ "status", "code", "detail" ] } } }, "required": [ "errors" ] } } } }, "403": { "description": "The provided user does not have access to this resource.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "examples": [ { "errors": [ { "status": "403", "code": "access_denied", "detail": "The provided user does not have access to this resource." } ] } ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "The HTTP status code applicable to this problem, expressed as a string." }, "code": { "type": "string", "description": "An application-specific error code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "id": { "type": "string", "description": "A unique identifier for this particular occurrence of the problem." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "source": { "type": "object", "description": "An object containing references to the source of the error.", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" }, "header": { "type": "string" } } }, "meta": { "type": "object", "description": "A meta object containing additional information about the error." } }, "required": [ "status", "code", "detail" ] } } }, "required": [ "errors" ] } } } } } } }, "/auction-items/{id}/update-max-bid": { "post": { "operationId": "updateMaxBid", "description": "Updates the authenticated storefront customer's maximum (proxy) bid on an active auction item.\n\nThe customer must currently be the high bidder. The **maxAmount** cannot be lower than the customer's current showing bid.\n\nIf the auction item has a reserve price that has not yet been met and the **maxAmount** meets or exceeds it, the system will automatically place a bid at the reserve price.", "summary": "Update a max bid", "tags": [ "Auction Items" ], "parameters": [ { "name": "fields[auction-items]", "in": "query", "description": "Available values are `startPrice`, `bidIncrementStrategy`, `automaticBidding`, `softClose`, `totalBids`, `highBidAmount`, `minimumBid`, `currentIncrement`, `startsAt`, `endsAt`, `position`, `status`, `enableReserve`, `reserveMet`, `processed`, `createdAt`, `updatedAt`, `canceledAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[variants]", "in": "query", "description": "Available values are `externalId`, `displayName`, `title`, `price`, `photoUrl`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[products]", "in": "query", "description": "Available values are `externalId`, `title`, `vendor`, `type`, `photoUrl`, `handle`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[bids]", "in": "query", "description": "Available values are `amount`, `submittedAt`, `placedAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[max-bids]", "in": "query", "description": "Available values are `amount`, `createdAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[auction-winners]", "in": "query", "description": "Available values are `amount`, `notifiedAt`, `paymentDueAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "The auction item UID.", "schema": { "type": "string" }, "example": "1c6af60by54hzdmgxy5ab4ypw0" }, { "name": "viewerFields", "in": "query", "description": "Comma-separated per-viewer fields to return under `meta.viewer` on the resource and any included resources. Available values: `hasBid`, `isWatching`, `isHighBidder`, `isOwner`. Requires an authenticated customer.", "schema": { "type": "string" }, "example": "hasBid,isWatching" }, { "name": "include", "in": "query", "description": "Comma-separated list of related resources to include in the response. Available values: `variant`, `product`, `highBid`, `highBid.customer`, `viewerMaxBid`, `viewerWin`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "maxAmount": { "type": "number", "description": "The new maximum bid in major currency units (e.g. 10.50).", "minimum": 0 } }, "required": [ "maxAmount" ] } } } }, "responses": { "200": { "description": "`AuctionItemResource`", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/AuctionItemResource" }, { "type": "object", "properties": { "relationships": { "type": "object", "properties": { "variant": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "variants" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "product": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "products" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "highBid": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "bids" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "viewerMaxBid": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "max-bids" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "viewerWin": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auction-winners" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } } } } } } ] } }, "required": [ "data" ] } } } }, "401": { "description": "The provided user does not have access to this resource.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "examples": [ { "errors": [ { "status": "401", "code": "unauthorized", "detail": "The provided user does not have access to this resource." } ] } ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "The HTTP status code applicable to this problem, expressed as a string." }, "code": { "type": "string", "description": "An application-specific error code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "id": { "type": "string", "description": "A unique identifier for this particular occurrence of the problem." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "source": { "type": "object", "description": "An object containing references to the source of the error.", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" }, "header": { "type": "string" } } }, "meta": { "type": "object", "description": "A meta object containing additional information about the error." } }, "required": [ "status", "code", "detail" ] } } }, "required": [ "errors" ] } } } }, "422": { "description": "The max bid could not be updated. Inspect `errors[0].code` for details:\n\n- `max_bid_edit_permission_denied` \u2014 the customer is not the current high bidder on the auction item.\n- `auction_ended` \u2014 the auction has already ended.\n- `max_amount_below_current_bid` \u2014 the new `maxAmount` is lower than the showing bid. `meta.minimum_bid` contains the showing bid amount.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "examples": [ { "errors": [ { "status": "422", "code": "validation_error", "detail": "The selected field is invalid.", "source": { "parameter": "field_name" }, "meta": { "rule": "required" } } ] }, { "errors": [ { "status": "422", "code": "max_bid_edit_permission_denied", "detail": "The max bid cannot be updated." } ] }, { "errors": [ { "status": "422", "code": "auction_ended", "detail": "This auction has ended and bids are no longer being accepted." } ] }, { "errors": [ { "status": "422", "code": "max_amount_below_current_bid", "detail": "The max bid amount must be greater than or equal to the current bid.", "meta": { "minimum_bid": "50.00" } } ] } ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "The HTTP status code applicable to this problem, expressed as a string." }, "code": { "type": "string", "description": "An application-specific error code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "id": { "type": "string", "description": "A unique identifier for this particular occurrence of the problem." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "source": { "type": "object", "description": "An object containing references to the source of the error.", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" }, "header": { "type": "string" } } }, "meta": { "type": "object", "description": "A meta object containing additional information about the error." } }, "required": [ "status", "code", "detail" ] } } }, "required": [ "errors" ] } } } }, "403": { "description": "The provided user does not have access to this resource.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "examples": [ { "errors": [ { "status": "403", "code": "access_denied", "detail": "The provided user does not have access to this resource." } ] } ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "The HTTP status code applicable to this problem, expressed as a string." }, "code": { "type": "string", "description": "An application-specific error code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "id": { "type": "string", "description": "A unique identifier for this particular occurrence of the problem." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "source": { "type": "object", "description": "An object containing references to the source of the error.", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" }, "header": { "type": "string" } } }, "meta": { "type": "object", "description": "A meta object containing additional information about the error." } }, "required": [ "status", "code", "detail" ] } } }, "required": [ "errors" ] } } } } } } }, "/auction-items/{id}/bids": { "get": { "operationId": "listAuctionItemBids", "description": "Returns a paginated list of bids placed on a single auction item, ordered by amount from highest to lowest.", "summary": "List auction item bids", "tags": [ "Bids" ], "parameters": [ { "name": "viewerFields", "in": "query", "description": "Comma-separated per-viewer fields to return under `meta.viewer` on the resource and any included resources. Available values: `hasBid`, `isWatching`, `isHighBidder`, `isOwner`. Requires an authenticated customer.", "schema": { "type": [ "string", "null" ] } }, { "name": "perPage", "in": "query", "description": "Results per page (1\u2013100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "fields[bids]", "in": "query", "description": "Available values are `amount`, `submittedAt`, `placedAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "description": "The auction item UID.", "schema": { "type": "string" }, "example": "1c6af60by54hzdmgxy5ab4ypw0" }, { "name": "include", "in": "query", "description": "Comma-separated list of related resources to include in the response. Available values: `customer`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `BidResource`", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BidResource" } }, "meta": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "lastPage": { "type": "integer", "minimum": 1 }, "perPage": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "currentPage", "from", "lastPage", "perPage", "to", "total" ] } }, "required": [ "data", "meta" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/variants": { "get": { "operationId": "listVariants", "description": "Returns the active variants matching the required `filter[externalId]` filter.", "summary": "List variants", "tags": [ "Variants" ], "parameters": [ { "name": "filter[externalId]", "in": "query", "required": true, "description": "A comma-separated list of Shopify external variant IDs to fetch (maximum 50).", "schema": { "type": "string" } }, { "name": "viewerFields", "in": "query", "description": "Comma-separated per-viewer fields to return under `meta.viewer` on the resource and any included resources. Available values: `hasBid`, `isWatching`, `isHighBidder`, `isOwner`. Requires an authenticated customer.", "schema": { "type": [ "string", "null" ] } }, { "name": "perPage", "in": "query", "description": "Results per page (1\u2013100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "fields[variants]", "in": "query", "description": "Available values are `externalId`, `displayName`, `title`, `price`, `photoUrl`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[auction-items]", "in": "query", "description": "Available values are `startPrice`, `bidIncrementStrategy`, `automaticBidding`, `softClose`, `totalBids`, `highBidAmount`, `minimumBid`, `currentIncrement`, `startsAt`, `endsAt`, `position`, `status`, `enableReserve`, `reserveMet`, `processed`, `createdAt`, `updatedAt`, `canceledAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[products]", "in": "query", "description": "Available values are `externalId`, `title`, `vendor`, `type`, `photoUrl`, `handle`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[bids]", "in": "query", "description": "Available values are `amount`, `submittedAt`, `placedAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "description": "Comma-separated list of related resources to include in the response. Available values: `product`, `currentAuctionItem`, `currentAuctionItem.highBid`, `currentAuctionItem.highBid.customer`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `VariantResource`", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/VariantResource" }, { "type": "object", "properties": { "relationships": { "type": "object", "properties": { "currentAuctionItem": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "auction-items" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "product": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "products" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } } } } } } ] } }, "meta": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "lastPage": { "type": "integer", "minimum": 1 }, "perPage": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "currentPage", "from", "lastPage", "perPage", "to", "total" ] } }, "required": [ "data", "meta" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/watched-items": { "get": { "operationId": "listWatchedItems", "description": "Returns every variant the authenticated customer is watching, most recently updated first.", "summary": "List watched items", "tags": [ "Watched Items" ], "parameters": [ { "name": "filter[listingType]", "in": "query", "schema": { "type": "string", "enum": [ "auction", "product" ] } }, { "name": "viewerFields", "in": "query", "description": "Comma-separated per-viewer fields to return under `meta.viewer` on the resource and any included resources. Available values: `hasBid`, `isWatching`, `isHighBidder`, `isOwner`. Requires an authenticated customer.", "schema": { "type": [ "string", "null" ] } }, { "name": "perPage", "in": "query", "description": "Results per page (1\u2013100).", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "fields[watched-items]", "in": "query", "description": "Available values are `automatic`, `createdAt`, `updatedAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[variants]", "in": "query", "description": "Available values are `externalId`, `displayName`, `title`, `price`, `photoUrl`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[auction-items]", "in": "query", "description": "Available values are `startPrice`, `bidIncrementStrategy`, `automaticBidding`, `softClose`, `totalBids`, `highBidAmount`, `minimumBid`, `currentIncrement`, `startsAt`, `endsAt`, `position`, `status`, `enableReserve`, `reserveMet`, `processed`, `createdAt`, `updatedAt`, `canceledAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[products]", "in": "query", "description": "Available values are `externalId`, `title`, `vendor`, `type`, `photoUrl`, `handle`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[bids]", "in": "query", "description": "Available values are `amount`, `submittedAt`, `placedAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[max-bids]", "in": "query", "description": "Available values are `amount`, `createdAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[auction-winners]", "in": "query", "description": "Available values are `amount`, `notifiedAt`, `paymentDueAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "description": "Comma-separated list of related resources to include in the response. Available values: `variant`, `product`, `variant.currentAuctionItem`, `variant.currentAuctionItem.highBid`, `variant.currentAuctionItem.highBid.customer`, `variant.currentAuctionItem.viewerMaxBid`, `variant.currentAuctionItem.viewerWin`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `WatchedItemResource`", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/WatchedItemResource" }, { "type": "object", "properties": { "relationships": { "type": "object", "properties": { "variant": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "variants" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "product": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "products" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } } } } } } ] } }, "meta": { "type": "object", "properties": { "currentPage": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "lastPage": { "type": "integer", "minimum": 1 }, "perPage": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "currentPage", "from", "lastPage", "perPage", "to", "total" ] } }, "required": [ "data", "meta" ] } } } }, "401": { "description": "The provided user does not have access to this resource.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "examples": [ { "errors": [ { "status": "401", "code": "unauthorized", "detail": "The provided user does not have access to this resource." } ] } ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "The HTTP status code applicable to this problem, expressed as a string." }, "code": { "type": "string", "description": "An application-specific error code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "id": { "type": "string", "description": "A unique identifier for this particular occurrence of the problem." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "source": { "type": "object", "description": "An object containing references to the source of the error.", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" }, "header": { "type": "string" } } }, "meta": { "type": "object", "description": "A meta object containing additional information about the error." } }, "required": [ "status", "code", "detail" ] } } }, "required": [ "errors" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } }, "post": { "operationId": "watchItem", "description": "Adds a variant to the authenticated customer's watched items.", "summary": "Watch a variant", "tags": [ "Watched Items" ], "parameters": [ { "name": "fields[watched-items]", "in": "query", "description": "Available values are `automatic`, `createdAt`, `updatedAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[variants]", "in": "query", "description": "Available values are `externalId`, `displayName`, `title`, `price`, `photoUrl`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[auction-items]", "in": "query", "description": "Available values are `startPrice`, `bidIncrementStrategy`, `automaticBidding`, `softClose`, `totalBids`, `highBidAmount`, `minimumBid`, `currentIncrement`, `startsAt`, `endsAt`, `position`, `status`, `enableReserve`, `reserveMet`, `processed`, `createdAt`, `updatedAt`, `canceledAt`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "fields[products]", "in": "query", "description": "Available values are `externalId`, `title`, `vendor`, `type`, `photoUrl`, `handle`. You can include multiple values by separating them with a comma.", "schema": { "type": "string" } }, { "name": "viewerFields", "in": "query", "description": "Comma-separated per-viewer fields to return under `meta.viewer` on the resource and any included resources. Available values: `hasBid`, `isWatching`, `isHighBidder`. Requires an authenticated customer.", "schema": { "type": "string" }, "example": "hasBid,isWatching" }, { "name": "include", "in": "query", "description": "Comma-separated list of related resources to include in the response. Available values: `variant`, `product`, `variant.currentAuctionItem`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "externalVariantId": { "type": "integer", "description": "The Shopify external variant ID to watch." } }, "required": [ "externalVariantId" ] } } } }, "responses": { "201": { "description": "`WatchedItemResource`", "content": { "application/vnd.api+json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/WatchedItemResource" }, { "type": "object", "properties": { "relationships": { "type": "object", "properties": { "variant": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "variants" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } }, "product": { "type": "object", "properties": { "data": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "products" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] } } } } } } } ] } }, "required": [ "data" ] } } } }, "401": { "description": "The provided user does not have access to this resource.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "examples": [ { "errors": [ { "status": "401", "code": "unauthorized", "detail": "The provided user does not have access to this resource." } ] } ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "The HTTP status code applicable to this problem, expressed as a string." }, "code": { "type": "string", "description": "An application-specific error code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "id": { "type": "string", "description": "A unique identifier for this particular occurrence of the problem." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "source": { "type": "object", "description": "An object containing references to the source of the error.", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" }, "header": { "type": "string" } } }, "meta": { "type": "object", "description": "A meta object containing additional information about the error." } }, "required": [ "status", "code", "detail" ] } } }, "required": [ "errors" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "description": "The requested resource was not found.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "examples": [ { "errors": [ { "status": "404", "code": "resource_not_found", "detail": "The requested resource was not found." } ] } ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "The HTTP status code applicable to this problem, expressed as a string." }, "code": { "type": "string", "description": "An application-specific error code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "id": { "type": "string", "description": "A unique identifier for this particular occurrence of the problem." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "source": { "type": "object", "description": "An object containing references to the source of the error.", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" }, "header": { "type": "string" } } }, "meta": { "type": "object", "description": "A meta object containing additional information about the error." } }, "required": [ "status", "code", "detail" ] } } }, "required": [ "errors" ] } } } } } }, "delete": { "operationId": "unwatchItem", "description": "Removes a variant from the authenticated customer's watched item lists.", "summary": "Unwatch a variant", "tags": [ "Watched Items" ], "parameters": [ { "name": "externalVariantId", "in": "query", "required": true, "description": "The Shopify external variant ID to unwatch.", "schema": { "type": "integer" } } ], "responses": { "204": { "description": "No content" }, "401": { "description": "The provided user does not have access to this resource.", "content": { "application/vnd.api+json": { "schema": { "type": "object", "examples": [ { "errors": [ { "status": "401", "code": "unauthorized", "detail": "The provided user does not have access to this resource." } ] } ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "The HTTP status code applicable to this problem, expressed as a string." }, "code": { "type": "string", "description": "An application-specific error code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "id": { "type": "string", "description": "A unique identifier for this particular occurrence of the problem." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "source": { "type": "object", "description": "An object containing references to the source of the error.", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" }, "header": { "type": "string" } } }, "meta": { "type": "object", "description": "A meta object containing additional information about the error." } }, "required": [ "status", "code", "detail" ] } } }, "required": [ "errors" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "description": "Your storefront (public) token, sent as Authorization: Bearer STOREFRONT_TOKEN. Generate one in Auction Plus under Settings > API, in the Storefront API section, by clicking Generate Public Token. Required on every request.", "scheme": "bearer" }, "apiKey": { "type": "apiKey", "description": "A Shopify Customer Account API access token for the signed-in customer. Optional: send it to identify the customer for the request. Required for endpoints that act on behalf of a customer (placing bids, watching items) and the viewerFields parameter.", "in": "header", "name": "X-Shopify-Customer-Access-Token" } }, "schemas": { "AuctionItemResource": { "type": "object", "examples": [ { "id": "fjh1brqm6907b7d91nc5f1dj10", "type": "auction-items", "attributes": { "startPrice": { "value": 100, "major": "1.00", "display": "$1.00", "currency": "USD" }, "bidIncrementStrategy": { "strategy": "fixed_amount", "value": { "amount": { "value": 500, "major": "5.00", "display": "$5.00", "currency": "USD" } } }, "automaticBidding": { "enabled": true }, "softClose": { "enabled": false }, "totalBids": 1, "highBidAmount": { "value": 5000, "major": "50.00", "display": "$50.00", "currency": "USD" }, "minimumBid": { "value": 5500, "major": "55.00", "display": "$55.00", "currency": "USD" }, "currentIncrement": { "value": 500, "major": "5.00", "display": "$5.00", "currency": "USD" }, "startsAt": "2026-09-15T20:58:44.000000Z", "endsAt": "2026-09-15T21:58:44.000000Z", "position": null, "status": "active", "enableReserve": true, "reserveMet": true, "processed": false, "createdAt": "2026-09-15T20:58:44.000000Z", "updatedAt": "2026-09-15T20:58:44.000000Z", "canceledAt": null } } ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "auction-items" }, "attributes": { "type": "object", "properties": { "startPrice": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "bidIncrementStrategy": { "$ref": "#/components/schemas/BidIncrementStrategy" }, "automaticBidding": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "softClose": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ] }, "totalBids": { "type": "integer" }, "highBidAmount": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "minimumBid": { "$ref": "#/components/schemas/Money" }, "currentIncrement": { "$ref": "#/components/schemas/Money" }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "type": "string", "format": "date-time" }, "position": { "type": [ "integer", "null" ], "description": "Position within the auction event, or null if the item is not part of an event." }, "status": { "type": "string", "enum": [ "scheduled", "active", "completed" ] }, "enableReserve": { "type": "boolean" }, "reserveMet": { "type": "boolean" }, "processed": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "meta": { "type": "object", "properties": { "viewer": { "type": "object", "properties": { "hasBid": { "type": "boolean" }, "isWatching": { "type": "boolean" }, "isHighBidder": { "type": "boolean" } }, "required": [ "hasBid", "isWatching", "isHighBidder" ] } } } }, "required": [ "id", "type", "meta" ], "title": "AuctionItemResource" }, "BidIncrementStrategy": { "type": "object", "properties": { "strategy": { "type": "string" }, "value": { "anyOf": [ { "$ref": "#/components/schemas/FixedAmountBidIncrement" }, { "$ref": "#/components/schemas/PercentageBidIncrement" }, { "$ref": "#/components/schemas/TierBidIncrement" } ] } }, "required": [ "strategy", "value" ], "title": "BidIncrementStrategy" }, "BidResource": { "type": "object", "examples": [ { "id": "29packd21h09v48wb3x47pvf58", "type": "bids", "attributes": { "amount": { "value": 5000, "major": "50.00", "display": "$50.00", "currency": "USD" }, "submittedAt": "2026-09-15T20:53:43.000000Z", "placedAt": "2026-09-15T20:53:43.778389Z" } } ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "bids" }, "attributes": { "type": "object", "properties": { "amount": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "submittedAt": { "type": [ "string", "null" ], "format": "date-time" }, "placedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "meta": { "type": "object", "properties": { "viewer": { "type": "object", "properties": { "isOwner": { "type": "boolean" } }, "required": [ "isOwner" ] } } } }, "required": [ "id", "type", "meta" ], "title": "BidResource" }, "FixedAmountBidIncrement": { "type": "object", "properties": { "amount": { "type": "object", "properties": { "value": { "type": "integer" }, "major": { "type": "string" }, "display": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "value", "major", "display", "currency" ] } }, "required": [ "amount" ], "title": "FixedAmountBidIncrement" }, "Money": { "type": "object", "properties": { "value": { "type": "integer" }, "major": { "type": "string" }, "display": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "value", "major", "display", "currency" ], "title": "Money" }, "PercentageBidIncrement": { "type": "object", "properties": { "percentage": { "type": "number" } }, "required": [ "percentage" ], "title": "PercentageBidIncrement" }, "TierBidIncrement": { "type": "object", "properties": { "tier": { "type": "string" } }, "required": [ "tier" ], "title": "TierBidIncrement" }, "VariantResource": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "variants" }, "attributes": { "type": "object", "properties": { "externalId": { "type": [ "integer", "null" ] }, "displayName": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "price": { "anyOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ] }, "photoUrl": { "type": [ "string", "null" ] } } } }, "required": [ "id", "type" ], "title": "VariantResource" }, "WatchedItemResource": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "const": "watched-items" }, "attributes": { "type": "object", "properties": { "automatic": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } } } }, "required": [ "id", "type" ], "title": "WatchedItemResource" } }, "responses": { "AuthenticationException": { "description": "Unauthenticated", "content": { "application/vnd.api+json": { "schema": { "type": "object", "examples": [ { "errors": [ { "status": "401", "code": "unauthenticated", "detail": "Unauthenticated." } ] } ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "The HTTP status code applicable to this problem, expressed as a string." }, "code": { "type": "string", "description": "An application-specific error code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "id": { "type": "string", "description": "A unique identifier for this particular occurrence of the problem." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "source": { "type": "object", "description": "An object containing references to the source of the error.", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" }, "header": { "type": "string" } } }, "meta": { "type": "object", "description": "A meta object containing additional information about the error." } }, "required": [ "status", "code", "detail" ] } } }, "required": [ "errors" ] } } } }, "ValidationException": { "description": "Validation error", "content": { "application/vnd.api+json": { "schema": { "type": "object", "examples": [ { "errors": [ { "status": "422", "code": "validation_error", "detail": "The selected field is invalid.", "source": { "parameter": "field_name" }, "meta": { "rule": "required" } } ] } ], "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "description": "The HTTP status code applicable to this problem, expressed as a string." }, "code": { "type": "string", "description": "An application-specific error code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence of the problem." }, "id": { "type": "string", "description": "A unique identifier for this particular occurrence of the problem." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "source": { "type": "object", "description": "An object containing references to the source of the error.", "properties": { "pointer": { "type": "string" }, "parameter": { "type": "string" }, "header": { "type": "string" } } }, "meta": { "type": "object", "description": "A meta object containing additional information about the error." } }, "required": [ "status", "code", "detail" ] } } }, "required": [ "errors" ] } } } } } } }