> 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/watchlists/add-a-variant-to-a-watchlist.md).

# Add a variant to a watchlist

Adds a variant to a watchlist owned by the authenticated customer.

```json
{"openapi":"3.1.0","info":{"title":"Auction Plus Storefront API Documentation","version":"1.0.0"},"tags":[{"name":"Watchlists","description":"A watchlist is a named list of the authenticated customer's watched items. A variant can belong to multiple watchlists.\n\nAdding a variant to a watchlist also adds it to the customer's watched items. Removing a variant from a watchlist,\nor deleting the watchlist, only removes it from that named watchlist. To remove a variant from the customer's\nwatched items and all watchlists, send a delete request to the watched items endpoint.\n\nWatchlist item calls take an **externalVariantId** representing the Shopify variant ID."}],"servers":[{"url":"https://api.auctionplusapp.com/storefront/v1"}],"security":[{"http":[]},{"apiKey":[]}],"components":{"securitySchemes":{"http":{"type":"http","description":"Your storefront (public) token, sent as <code>Authorization: Bearer STOREFRONT_TOKEN</code>. Generate one in Auction Plus under Settings > API, in the <b>Storefront API</b> section, by clicking <b>Generate Public Token</b>. 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 <code>viewerFields</code> 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"},"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"},"Money":{"type":"object","properties":{"value":{"type":"integer"},"major":{"type":"string"},"display":{"type":"string"},"currency":{"type":"string"}},"required":["value","major","display","currency"],"title":"Money"},"AuctionItemResource":{"type":"object","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"},"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"},"PercentageBidIncrement":{"type":"object","properties":{"percentage":{"type":"number"}},"required":["percentage"],"title":"PercentageBidIncrement"},"TierBidIncrement":{"type":"object","properties":{"tier":{"type":"string"}},"required":["tier"],"title":"TierBidIncrement"},"ProductResource":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"products"},"attributes":{"type":"object","properties":{"externalId":{"type":["integer","null"]},"title":{"type":"string"},"vendor":{"type":["string","null"]},"type":{"type":["string","null"]},"photoUrl":{"type":["string","null"]},"handle":{"type":["string","null"]}}}},"required":["id","type"],"title":"ProductResource"}},"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":{"/watchlists/{id}/items":{"post":{"operationId":"addWatchlistItem","description":"Adds a variant to a watchlist owned by the authenticated customer.","summary":"Add a variant to a watchlist","tags":["Watchlists"],"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":"id","in":"path","required":true,"description":"The watchlist UID.","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"]}}}}}}}]},"included":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/VariantResource"},{"$ref":"#/components/schemas/AuctionItemResource"},{"$ref":"#/components/schemas/ProductResource"}]}}},"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"}}}}}}
```
