> For the complete documentation index, see [llms.txt](https://docs.auctionplusapp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.auctionplusapp.com/storefront-api/watched-items.md).
# Watched Items
A watched item is a product variant the authenticated customer is following.
The **automatic** attribute indicates the item was followed on the customer's behalf. Items are followed automatically when the customer places a bid.
Watch and unwatch calls take an **externalVariantId** representing the Shopify variant ID.
The 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`.
Include **variant.currentAuctionItem** to return the live auction item for each watched variant.
## List Watched Items
> Returns every variant the authenticated customer is watching, most recently updated first.
```json
{"openapi":"3.1.0","info":{"title":"Auction Plus Storefront API Documentation","version":"1.0.0"},"tags":[{"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."}],"servers":[{"url":"https://api.auctionplusapp.com/storefront/v1"}],"security":[{"http":[]},{"apiKey":[]}],"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":{"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":{"ValidationException":{"description":"Validation error","content":{"application/vnd.api+json":{"schema":{"type":"object","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"]}}}}}},"paths":{"/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–100).","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`, `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","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"}}}}}}
```
## Watch a Variant
> Adds a variant to the authenticated customer's watched items.
```json
{"openapi":"3.1.0","info":{"title":"Auction Plus Storefront API Documentation","version":"1.0.0"},"tags":[{"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."}],"servers":[{"url":"https://api.auctionplusapp.com/storefront/v1"}],"security":[{"http":[]},{"apiKey":[]}],"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":{"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":{"ValidationException":{"description":"Validation error","content":{"application/vnd.api+json":{"schema":{"type":"object","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"]}}}}}},"paths":{"/watched-items":{"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"}},{"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","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"]}}}},"404":{"description":"The requested resource was not found.","content":{"application/vnd.api+json":{"schema":{"type":"object","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"}}}}}}
```
## Unwatch a Variant
> Removes a variant from the authenticated customer's watched item lists.
```json
{"openapi":"3.1.0","info":{"title":"Auction Plus Storefront API Documentation","version":"1.0.0"},"tags":[{"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."}],"servers":[{"url":"https://api.auctionplusapp.com/storefront/v1"}],"security":[{"http":[]},{"apiKey":[]}],"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"}},"responses":{"ValidationException":{"description":"Validation error","content":{"application/vnd.api+json":{"schema":{"type":"object","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"]}}}}}},"paths":{"/watched-items":{"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","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"}}}}}}
```