Skip to content

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[]=44556678
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_variant_ids[] 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.

{
"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_variant_id string The variant gid.
status string live, sold_out, scheduled, off, not_in_country, not_enrolled. 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_condition.
stock_condition string or null out_of_stock, in_stock or any_stock_level: the inventory condition under which the variant sells as a preorder, the offer’s inventory.stock_condition. Only set while an offer applies (live or sold_out).
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.start_date and schedule.end_date 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_enrolled and not_in_country.
errors array One entry per malformed id: { "shopify_variant_id": "abc", "error": "not a Shopify variant id" }. Malformed ids never fail the call.

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_text 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_count integer or null The variant’s own limit on this offer. null when none is set.
quantity_limit integer or null The limit that applies. On a batch offer, the total of the batches. null when unlimited.
preorder_count integer Units sold on this offer for the variant.
quantity_limit_reached boolean true when preorder_count has reached the limit.
units_left integer or null Units left before the limit: null when unlimited, 0 once quantity_limit_reached, else quantity_limit - preorder_count.
{
"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 Meaning
live An offer applies and its limit is not reached
sold_out An offer applies but its limit is reached
scheduled An offer is set to open later; see preorder.schedule.start_date
off The merchant has turned the offer off, or it is past its end date
not_in_country The variant’s offers are restricted to other markets
not_enrolled 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.

STOQ does not hold live inventory, so status is half of the answer. Check the Storefront API for the same country:

stock_condition Preorder while Storefront check
out_of_stock the variant is out of stock and “Continue selling when out of stock” is on availableForSale && currentlyNotInStock
in_stock the variant has stock availableForSale && !currentlyNotInStock; quantityAvailable caps what is left
any_stock_level the variant can be bought at all availableForSale

Purchasable as a preorder = status: live and the check for stock_condition.

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.

Case Status
country missing or not a two-letter code 422
No shopify_variant_ids, or more than 100 422
An include value other than offer_details 422
A malformed id among valid ones 200, listed in errors
Unknown or deleted variant 200, status: "not_enrolled"

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.

Was this page helpful?

Still stuck? Ask Quinn or chat with support