Variant availability (beta)
Is this variant on preorder for a buyer in this country? One resolved answer per variant: the offer that applies, its stock condition and its schedule.
BetaAPI v2 is in public beta: endpoints, fields and behaviour can change before general availability. See the changelog
Last updated
Beta. The response may gain keys and status values; ignore what you do not recognise.
Answers, for up to 100 Shopify variants and one buyer country, which preorder offer applies and whether its limit is reached. You pass the country and never deal with Shopify Markets, offer scopes or metafields. Add include[]=offer_details for the offer’s limit and shipping text in the same call.
GET /api/v2/external/preorders/product_variants/availability?country=DE&shopify_variant_ids[]=44556677&shopify_variant_ids[]=44556678Request
Section titled “Request”| Parameter | Required | Notes |
|---|---|---|
country |
yes | ISO 3166-1 alpha-2 (DE, us). The buyer’s country: use the same value you pass to the Storefront API’s @inContext(country:). |
shopify_ |
yes | 1 to 100 Shopify variant ids, numeric or as gid://shopify/ProductVariant/…. Also accepted as one comma-separated value. |
| include[] | no | offer_details. Also accepted as one comma-separated value. Adds the offer’s limit and shipping text to preorder; without it the response is unchanged. Any other value is a 422. |
A GET costs 1 rate-limit point whatever the number of ids.
Response
Section titled “Response”{ "country": "DE", "product_variants": [ { "shopify_variant_id": "gid://shopify/ProductVariant/44556677", "status": "live", "stock_condition": "out_of_stock", "preorder": { "id": "6f1c0c0e-2f0a-4c57-9d0f-6a1d5a3a1b11", "schedule": { "start_date": null, "end_date": "2026-11-15T23:59:00+01:00" } } }, { "shopify_variant_id": "gid://shopify/ProductVariant/44556678", "status": "not_enrolled", "stock_condition": null, "preorder": null } ], "errors": []}One entry per distinct valid id, in the order you sent them. Every key is always present.
| Key | Type | Meaning |
|---|---|---|
shopify_ |
string | The variant gid. |
status |
string | live, sold_, scheduled, off, not_, not_. live means an offer applies to this variant in this country and its limit is not reached. It does not mean “in stock”: see stock_. |
stock_ |
string or null | out_, in_ or any_: the inventory condition under which the variant sells as a preorder, the offer’s inventory.. Only set while an offer applies (live or sold_). |
preorder |
object or null | The preorder offer the status refers to: the one that applies, or the scheduled or off one that explains the status. schedule. and schedule. are the offer’s schedule: set only while the offer has a schedule, ISO 8601 with the store’s timezone offset, null otherwise. null for not_ and not_. |
errors |
array | One entry per malformed id: { "shopify_. Malformed ids never fail the call. |
include[]=offer_details
Section titled “include[]=offer_details”Adds these keys to preorder, the offer the status refers to. They are the same keys, from the same code, as an entry of offers in GET /preorders/products, so the two endpoints agree, with one exception: shipping_text. GET /preorders/products lists the text stored on the variant, which is empty when the offer sets one text for all products and does not show a batch’s text. Here you get the text as the storefront resolves it.
| Key | Type | Meaning |
|---|---|---|
shipping_ |
string or null | The shipping text the buyer sees: the offer’s text with its date or day count filled in, the variant’s own text on a per-product offer, or the current batch’s text. null when there is none. |
max_ |
integer or null | The variant’s own limit on this offer. null when none is set. |
quantity_ |
integer or null | The limit that applies. On a batch offer, the total of the batches. null when unlimited. |
preorder_ |
integer | Units sold on this offer for the variant. |
quantity_ |
boolean | true when preorder_ has reached the limit. |
units_ |
integer or null | Units left before the limit: null when unlimited, 0 once quantity_, else quantity_. |
{ "shopify_variant_id": "gid://shopify/ProductVariant/44556677", "status": "live", "stock_condition": "out_of_stock", "preorder": { "id": "6f1c0c0e-2f0a-4c57-9d0f-6a1d5a3a1b11", "schedule": { "start_date": null, "end_date": null }, "shipping_text": "Ships 01 Dec 2026", "max_count": 10, "quantity_limit": 10, "preorder_count": 3, "quantity_limit_reached": false, "units_left": 7 }}status
Section titled “status”status |
Meaning |
|---|---|
live |
An offer applies and its limit is not reached |
sold_ |
An offer applies but its limit is reached |
scheduled |
An offer is set to open later; see preorder. |
off |
The merchant has turned the offer off, or it is past its end date |
not_ |
The variant’s offers are restricted to other markets |
not_ |
The variant is on no offer, is unknown to STOQ, or was deleted in Shopify |
When several offers cover a variant in the country, the one that applies is chosen the way the storefront chooses it: an offer restricted to the buyer’s market outranks an unrestricted one. If the offer that applies is sold out, the result is sold_out even when another offer still has allowance; the storefront does not fall through to it either. An offer that is scheduled or off never blocks another offer. When no offer applies, status follows a fixed priority: scheduled, then off, then not_in_country, then not_enrolled. Only one status is ever returned.
Treat an unknown status value as not on preorder and ignore keys you do not recognise; both may be added without notice.
Purchasable right now
Section titled “Purchasable right now”STOQ does not hold live inventory, so status is half of the answer. Check the Storefront API for the same country:
stock_ |
Preorder while | Storefront check |
|---|---|---|
out_ |
the variant is out of stock and “Continue selling when out of stock” is on | availableForSale && currentlyNotInStock |
in_ |
the variant has stock | availableForSale && !currentlyNotInStock; quantityAvailable caps what is left |
any_ |
the variant can be bought at all | availableForSale |
Purchasable as a preorder = status: live and the check for stock_condition.
Limits
Section titled “Limits”Units are counted when the order is created, regardless of payment status, and restored when the order is cancelled. A limit is shared across every market an offer is restricted to; it is not enforced per market. Two offers on the same variant keep separate limits. sold_out is read from STOQ’s database, current as of the last processed order webhook; for an offer restricted to specific markets the count is cached for up to a minute, so status can differ from quantity_limit_reached for up to a minute there: offer_details counts the variant’s own units, the way the Products tab does.
Errors
Section titled “Errors”| Case | Status |
|---|---|
country missing or not a two-letter code |
422 |
No shopify_, or more than 100 |
422 |
An include value other than offer_ |
422 |
| A malformed id among valid ones | 200, listed in errors |
| Unknown or deleted variant | 200, status: "not_ |
Change detection
Section titled “Change detection”There are no webhooks for availability. Re-read this endpoint for the variants on screen, and on a timer for the variants you track. The Shopify Flow triggers “Preorder offer enabled” and “Preorder offer disabled” fire when an offer is switched on or off, including scheduled openings and closes.
Thanks for letting us know.
Still stuck? Ask Quinn or chat with support