List an offer's variants
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/preorders/offers/{id}/products/variantsCosts 1 rate-limit point · Rate limits
List the variants on a preorder offer, as the offer's Products table shows them, paginated.
On an offer with batches on, each row has batch_progress (units sold and the limit enforced per batch, and the batch on sale now) and batch_limits (the variant's own per-batch limits). max_count is the variant's own limit, the one PATCH writes; quantity_limit is the read-only limit that applies (the batches' total on a batch offer, where max_count is kept but not enforced). search matches product title, variant title and SKU. sort is one of attached, title, title_asc, title_desc, created_asc, created_desc, added_asc, added_desc, sold_asc, sold_desc (default attached, the attach order; title is title_asc). product_status keeps products in active, draft, archived, unlisted (comma-separated); when a product's status can't be read from Shopify the filter is skipped and product_status_filter_skipped is true. limit_reached=true keeps variants at their quantity limit. product.status is the stored status; include_statuses=true reads the ones not stored yet from Shopify (products[].status when grouped). group_by=product returns products (shopify_product_id, title, image_url, variant_count, variants) instead of variants and pages by product, so a product's variants never split across pages: per_page counts products and meta has total_products and total_variants. exclude_discarded=true leaves out variants deleted from the catalog (discarded: true). include_inventory=true adds each row's live Shopify inventory_quantity, inventory_policy and product.tags. The filters inventory (zero_or_below | positive), inventory_policy (DENY | CONTINUE; lowercase is deprecated), product_tag and exclude_product_tag imply include_inventory and apply to each page after the read, so a page can hold fewer rows than per_page; keep paging while meta.page < meta.total_pages.
Also searched aslist variants on offervariants attached to offershow offer variantsattached variantsoffer variant listlist products on offersearch offer products
Path parameters
idstringRequiredThe offer's ID, from
GET /preorders/offers.
Query parameters
sortstringSort order. Default attached (the order variants were added); title is the same as title_asc.
One ofattachedtitletitle_asctitle_desccreated_asccreated_descadded_ascadded_descsold_ascsold_desclimit_reachedbooleantrue keeps only variants that have reached their quantity limit.
include_statusesbooleantrue reads product statuses not stored yet from Shopify. Default false.
Defaultfalsegroup_bystringproduct returns products with their variants and pages by product instead of by variant.
One ofproductexclude_discardedbooleantrue leaves out variants deleted from the catalog. Default false.
Defaultfalseinclude_inventorybooleantrue adds live Shopify inventory quantity, inventory policy and product tags to each row. Default false.
DefaultfalseinventorystringKeep only variants with live inventory at zero or below, or above zero. Implies include_inventory.
One ofzero_or_belowpositiveinventory_policystringKeep only variants with this Shopify inventory policy; lowercase values are deprecated. Implies include_inventory.
One ofDENYCONTINUEdenycontinuepageintegerPage number, starting at 1.
Default1per_pageintegerRows per page, 1 to 250. Default 50.
Default50searchstringMatches product title, variant title and SKU.
product_statusstringComma-separated product statuses to keep, from active, draft, archived and unlisted.
product_tagstringKeep only variants whose product has this tag, case-insensitive. Implies include_inventory.
exclude_product_tagstringLeave out variants whose product has this tag, case-insensitive. Implies include_inventory.
Returns
variantsarray of objectsVariants on this page. Absent with group_by=product.
Show 19 child attributesHide child attributes
idstringID of this variant's place on the offer.
shopify_variant_idstringThe variant, as gid://shopify/ProductVariant/<id>.
productobjectThe variant's product.
Show 4 child attributesHide child attributes
shopify_product_idstringThe product, as gid://shopify/Product/<id>.
titlestringProduct title.
statusstring, nullableProduct status in Shopify, such as active, draft, archived or unlisted. Null when not stored yet; include_statuses=true reads it from Shopify.
tagsarray of stringsThe product's tags, read live from Shopify. Only with include_inventory or an inventory filter.
titlestringVariant name: product and variant title together, or the product title alone for a product's only variant.
variant_titlestringVariant title. Null for a product's only variant (Shopify's "Default Title").
skustringVariant SKU. Null when it has none.
discardedbooleantrue when the variant has been deleted from the catalog.
shipping_textstringThis variant's own shipping text. Null when it has none and the offer's text shows.
max_countintegerThis variant's own quantity limit. Null when it has none. Kept but not enforced while the offer has batches on.
quantity_limitintegerThe quantity limit that applies: max_count, or the batches' total on a batch offer. Null when unlimited. Read-only.
preorder_countintegerUnits preordered that count toward the quantity limit.
quantity_limit_reachedbooleantrue when preorder_count has reached quantity_limit, or the batch limit on a batch offer.
current_batch_idnullBatch the variant is selling in now. Null when the offer has batches off or the variant is in no batch.
created_atstringWhen the variant was added to the offer, ISO 8601 in UTC.
batch_limitsobjectThis variant's own quantity limit per batch, keyed by batch ID. Batches left out use the batch's quantity_limit.
batch_ship_textsobjectThis variant's own ship text per batch, keyed by batch ID. Batches left out use the batch's shipping_text.
batch_progressnullUnits sold and the limit per batch, and the batch on sale now. Null when the offer has batches off.
inventory_quantityintegerLive Shopify inventory, counted over the locations in inventory_scope. Only with include_inventory or an inventory filter.
inventory_policystringShopify inventory policy: CONTINUE keeps selling when out of stock; DENY stops.
One ofCONTINUEDENY
metaobjectPagination for the list.
Show 6 child attributesHide child attributes
total_countintegerItems matching the filters, across all pages.
pageintegerPage returned, starting at 1.
per_pageintegerMost items per page.
total_pagesintegerPages available at this per_page; 0 when nothing matches.
total_productsintegerProducts matching the filters. Only with group_by=product.
total_variantsintegerVariants matching the filters. Only with group_by=product.
productsarray of objectsProducts on this page with their variants on the offer. Only with group_by=product.
Show 6 child attributesHide child attributes
shopify_product_idstringThe product, as gid://shopify/Product/<id>.
titlestringProduct title.
image_urlstringURL of the product's image. Null when it has none.
variant_countintegerVariants of this product on this page.
variantsarray of objectsThis product's variants on the offer, as rows of the Products table.
Show 19 child attributesHide child attributes
idstringID of this variant's place on the offer.
shopify_variant_idstringThe variant, as gid://shopify/ProductVariant/<id>.
productobjectThe variant's product.
Show 4 child attributesHide child attributes
shopify_product_idstringThe product, as gid://shopify/Product/<id>.
titlestringProduct title.
statusstring, nullableProduct status in Shopify, such as active, draft, archived or unlisted. Null when not stored yet; include_statuses=true reads it from Shopify.
tagsarray of anysThe product's tags, read live from Shopify. Only with include_inventory or an inventory filter.
titlestringVariant name: product and variant title together, or the product title alone for a product's only variant.
variant_titlestringVariant title. Null for a product's only variant (Shopify's "Default Title").
skustringVariant SKU. Null when it has none.
discardedbooleantrue when the variant has been deleted from the catalog.
shipping_textstringThis variant's own shipping text. Null when it has none and the offer's text shows.
max_countintegerThis variant's own quantity limit. Null when it has none. Kept but not enforced while the offer has batches on.
quantity_limitintegerThe quantity limit that applies: max_count, or the batches' total on a batch offer. Null when unlimited. Read-only.
preorder_countintegerUnits preordered that count toward the quantity limit.
quantity_limit_reachedbooleantrue when preorder_count has reached quantity_limit, or the batch limit on a batch offer.
current_batch_idnullBatch the variant is selling in now. Null when the offer has batches off or the variant is in no batch.
created_atstringWhen the variant was added to the offer, ISO 8601 in UTC.
batch_limitsobjectThis variant's own quantity limit per batch, keyed by batch ID. Batches left out use the batch's quantity_limit.
batch_ship_textsobjectThis variant's own ship text per batch, keyed by batch ID. Batches left out use the batch's shipping_text.
batch_progressnullUnits sold and the limit per batch, and the batch on sale now. Null when the offer has batches off.
inventory_quantityintegerLive Shopify inventory, counted over the locations in inventory_scope. Only with include_inventory or an inventory filter.
inventory_policystringShopify inventory policy: CONTINUE keeps selling when out of stock; DENY stops.
One ofCONTINUEDENY
statusstringProduct status in Shopify. Only with include_statuses=true.
inventory_includedbooleantrue when live Shopify inventory was read for this page; false when it could not be. Only with include_inventory or an inventory filter.
inventory_scopeobjectWhich Shopify locations inventory_quantity counts. Only when inventory_included is true.
Show 3 child attributesHide child attributes
locationsstringall_locations, filtered_locations (the shop's preorder location filter), or unknown.
One ofall_locationsfiltered_locationsunknownnotestringPlain-sentence note on what inventory_quantity counts.
location_countintegerLocations in the preorder location filter. Only with filtered_locations.
scannedintegerRows read before the inventory, policy and tag filters were applied to the page.
unreadableintegerOf those, rows whose live inventory could not be read, so they were left out.
filter_errorstringWhy the filters were not applied and the page is empty. Only when live inventory could not be read.
Errors
not_foundThe path is valid but nothing with that id exists in this store.
invalid_paramsOne or more fields failed the action's schema.
validation_failedThe request failed validation.
Any request can also fail with auth_invalid (401) or rate_limited (429).
Every error has the same shape: see Errors and the list of error codes.
curl "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/products/variants" \
-H "X-Auth-Token: $STOQ_API_KEY"const res = await fetch("https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/products/variants", {
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
},
});
const data = await res.json();import os
import requests
res = requests.get(
"https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/products/variants",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/products/variants")
req = Net::HTTP::Get.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"])
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)curl "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/products/variants?sort=attached&limit_reached=5&include_statuses=false" \
-H "X-Auth-Token: $STOQ_API_KEY"const res = await fetch("https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/products/variants?sort=attached&limit_reached=5&include_statuses=false", {
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
},
});
const data = await res.json();import os
import requests
res = requests.get(
"https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/products/variants?sort=attached&limit_reached=5&include_statuses=false",
headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
)
data = res.json()require "net/http"
require "json"
uri = URI("https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/products/variants?sort=attached&limit_reached=5&include_statuses=false")
req = Net::HTTP::Get.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"])
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body){
"variants": [
{
"id": "b1f0c6d2-3e4a-4c1b-9a77-2d5e8f1a6c30",
"shopify_variant_id": "gid://shopify/ProductVariant/44712349876501",
"product": {
"shopify_product_id": "gid://shopify/Product/8123456789013",
"title": "Trail Runner Sneaker",
"status": "active"
},
"title": "Trail Runner Sneaker",
"variant_title": "US 9 / Black",
"sku": "TRS-BLK-09",
"discarded": false,
"shipping_text": null,
"max_count": 50,
"quantity_limit": 50,
"preorder_count": 18,
"quantity_limit_reached": false,
"current_batch_id": null,
"created_at": "2026-06-25T10:42:10Z",
"batch_limits": {},
"batch_ship_texts": {},
"batch_progress": null
},
{
"id": "c94e2a17-5b6d-4f08-8e21-7a3c9d0b4f52",
"shopify_variant_id": "gid://shopify/ProductVariant/44712349909269",
"product": {
"shopify_product_id": "gid://shopify/Product/8123456789013",
"title": "Trail Runner Sneaker",
"status": "active"
},
"title": "Trail Runner Sneaker",
"variant_title": "US 10 / Black",
"sku": "TRS-BLK-10",
"discarded": false,
"shipping_text": null,
"max_count": 50,
"quantity_limit": 50,
"preorder_count": 50,
"quantity_limit_reached": true,
"current_batch_id": null,
"created_at": "2026-06-25T10:42:10Z",
"batch_limits": {},
"batch_ship_texts": {},
"batch_progress": null
}
],
"meta": {
"total_count": 12,
"page": 1,
"per_page": 50,
"total_pages": 1
}
}{
"errors": [
"Invalid API key"
],
"code": "auth_invalid",
"details": [
{
"code": "auth_invalid",
"message": "Invalid API key",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"Offer not found"
],
"code": "not_found",
"details": [
{
"code": "not_found",
"message": "Offer not found",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"name is required"
],
"code": "validation_failed",
"details": [
{
"code": "validation_failed",
"message": "name is required",
"path": null,
"value": null,
"expected": null
}
]
}{
"errors": [
"Rate limit exceeded"
],
"code": "rate_limited",
"details": [
{
"code": "rate_limited",
"message": "Rate limit exceeded",
"path": null,
"value": null,
"expected": null
}
]
}