Poll the checkout queue
Requests to the REST Admin API's Checkout resource that exceed the throttle limit return a 429 too many requests status code and an empty JSON body with the following:
- Response header
X-Checkout-Queueset totrue - Response header
X-Checkout-Queue-Tokenset to the queue token value _checkout_queue_tokencookie set to the queue token value
When a client receives this response, it needs to send requests to the polling endpoint to move ahead in the queue. Typically, a shop's polling endpoint is <shop_domain>/queue/poll.
Polling is typically performed using client-side JavaScript, but could also be implemented in a custom application.
The polling endpoint supports only GraphQL queries. Clients can perform a single operation, poll.
The poll query includes a token argument, which is the same Base64-encoded queue token string that was received in the X-Checkout-Queue-Token when the request was queued. It should be passed as a variable in the GraphQL request to take advantage of GraphQL caching.
All poll queries need to select the token field and should update to the latest token contained in the response on subsequent poll queries.
The poll query accepts the following fields:
| Name | Description | Example |
|---|---|---|
| token | The queue token. The latest response value should be reused on the next poll and, in the case of a PollComplete result, when replaying the request. |
9mPYzKuJY6FCktnR0qo9DItK5LP |
| pollAfter | An ISO-8601 encoded UTC DateTime string. This string indicates the time after which clients should make their next poll request. Any poll requests sent before this time will be ignored. Use this value to schedule the next poll request. | "2015-10-21T09:47:50-04:00" |
| queueEtaSeconds | The estimated time in seconds that the client will remain in the queue. | 120 |
| productVariantAvailability | An array that indicates product variant availability. Each element in the array contains a variant ID and Boolean value indicating whether the product is available or out of stock. | [{"id": "gid://shopify/ProductVariantMerchandise/1", "available": true}, {"id": "gid://shopify/ProductVariantMerchandise/3", "available": false},] |
The poll response will be of type PollResult, indicating whether the client should continue polling (PollContinue) or has exited the queue phase (PollComplete). The token field is the only field included on both types.
If the poll response is PollContinue, then the client should use the token received in the previous poll response to perform another poll request at time pollAfter.
If the poll response is PollComplete, then the client should replay the originally-queued request, and provide the token along with the request.
To provide the token in the replayed request, pass the queue token as the value of the request header X-Checkout-Queue-Token, or as the _checkout_queue_token cookie if the calling client is on the same domain as the merchant.