> 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/list-watchlists.md).

# List watchlists

Returns the authenticated customer's watchlists, most recently created first.

```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":{"WatchlistResource":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","const":"watchlists"},"attributes":{"type":"object","properties":{"name":{"type":"string"},"createdAt":{"type":["string","null"],"format":"date-time"},"updatedAt":{"type":["string","null"],"format":"date-time"}}}},"required":["id","type"],"title":"WatchlistResource"}},"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":{"get":{"operationId":"listWatchlists","description":"Returns the authenticated customer's watchlists, most recently created first.","summary":"List watchlists","tags":["Watchlists"],"parameters":[{"name":"perPage","in":"query","description":"Results per page (1–100).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"fields[watchlists]","in":"query","description":"Available values are `name`, `createdAt`, `updatedAt`. You can include multiple values by separating them with a comma.","schema":{"type":"string"}},{"name":"sort","in":"query","description":"Sort by field. Prefix with `-` for descending order. Available values: `name`, `-name`, `createdAt`, `-createdAt`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated set of `WatchlistResource`","content":{"application/vnd.api+json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WatchlistResource"}},"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"}}}}}}
```
