Recalculate a variant's count
API v2 is in public beta: endpoints and fields can change before general availability. See the changelog
/preorders/product_variants/{shopify_variant_id}/recalculate_preorder_countCosts 2 rate-limit points · Rate limits
Recompute preorder_count for a variant from active order line items, then push to Shopify.
Use it when a variant's preorder_count no longer matches its orders, so the storefront hits the limit too early or too late. For each offer the variant is in, STOQ adds up the units on its preorder orders, leaving out cancelled units and orders retired by POST .../reset_preorder_count, saves that count and writes the live offer's count to Shopify. Safe to repeat. Returns 202 with the variant as GET /preorders/product_variants/:shopify_variant_id shows it; 404 not_found when STOQ has no such variant. For many variants use POST /preorders/product_variants/bulk_recalculate_preorder_counts.
Also searched asrecalculate preorder count from ordersfix preorder countrebuild countrecompute preorder countfix variant count drift
Path parameters
shopify_variant_idstringRequiredThe variant, as gid://shopify/ProductVariant/<id> or the numeric ID.
Headers
Idempotency-KeystringA fresh unique key for every write (a new UUID, say); reuse it only to retry that write. Keys are remembered for 1 hour: the same key and the same request within that hour returns the first result, with
Idempotent-Replayed: true, without running again; the same key with a different method, path or body is refused (422idempotency_key_reused); a retry while the first is still running gets 409idempotency_key_in_progress. Keys are per store. Server errors and rate limits are not kept, so their retry runs.
Returns
variantobjectShow 9 child attributesHide child attributes
idstringExample:3f9a6c1e-8b2d-4e57-a0c4-6d1e9b7f2a85shopify_variant_idstringExample:gid://shopify/ProductVariant/47284734423096productobjectShow 3 child attributesHide child attributes
shopify_product_idstringExample:gid://shopify/Product/8784906035384titlestringExample:Classic SneakerstatusnullExample:active
variant_titlestringExample:Blue / MediumskustringExample:CS-BLU-Mimage_urlstringExample:https://cdn.shopify.com/s/files/1/0712/3456/7890/files/cl…offersarray of objectsShow 6 child attributesHide child attributes
idstringExample:73a74948-2b57-4cc3-971f-2b441828c977shipping_textstringExample:Ships in early Augustmax_countintegerExample:100quantity_limitintegerExample:100preorder_countintegerExample:38quantity_limit_reachedbooleanExample:false
preorder_units_soldintegerExample:41line_item_revenuestringExample:4510.00
offersarray of objectsShow 8 child attributesHide child attributes
idstringExample:73a74948-2b57-4cc3-971f-2b441828c977internal_namestringExample:summer-2026current_statusstringExample:liveinventoryobjectShow 1 child attributeHide child attributes
stock_conditionstringExample:out_of_stock
marketsobjectShow 1 child attributeHide child attributes
scopestringExample:all
shippingobjectShow 1 child attributeHide child attributes
timelineobjectShow 1 child attributeHide child attributes
scopestringExample:per_variant
widgetobjectShow 1 child attributeHide child attributes
disclaimerobjectShow 1 child attributeHide child attributes
disclaimer_textstringExample:Ships in August. You're charged today.
paymentsobjectShow 1 child attributeHide child attributes
options_offeredstringExample:full
Errors
not_foundThe path is valid but nothing with that id exists in this store.
idempotency_key_in_progressAn earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.
invalid_amountThe amount is not a positive decimal with at most 2 places.
missing_amountCollecting a partial payment needs an amount or the line items to collect for.
unknown_line_itemsSome of the line item ids are not on the order.
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 -X POST "https://app.stoqapp.com/api/v2/external/preorders/product_variants/{shopify_variant_id}/recalculate_preorder_count" \
-H "X-Auth-Token: $STOQ_API_KEY"const res = await fetch("https://app.stoqapp.com/api/v2/external/preorders/product_variants/{shopify_variant_id}/recalculate_preorder_count", {
method: "POST",
headers: {
"X-Auth-Token": process.env.STOQ_API_KEY,
},
});
const data = await res.json();import os
import requests
res = requests.post(
"https://app.stoqapp.com/api/v2/external/preorders/product_variants/{shopify_variant_id}/recalculate_preorder_count",
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/product_variants/{shopify_variant_id}/recalculate_preorder_count")
req = Net::HTTP::Post.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){
"variant": {
"id": "3f9a6c1e-8b2d-4e57-a0c4-6d1e9b7f2a85",
"shopify_variant_id": "gid://shopify/ProductVariant/47284734423096",
"product": {
"shopify_product_id": "gid://shopify/Product/8784906035384",
"title": "Classic Sneaker",
"status": "active"
},
"variant_title": "Blue / Medium",
"sku": "CS-BLU-M",
"image_url": "https://cdn.shopify.com/s/files/1/0712/3456/7890/files/classic-sneaker-blue.jpg",
"offers": [
{
"id": "73a74948-2b57-4cc3-971f-2b441828c977",
"shipping_text": "Ships in early August",
"max_count": 100,
"quantity_limit": 100,
"preorder_count": 38,
"quantity_limit_reached": false
}
],
"preorder_units_sold": 41,
"line_item_revenue": "4510.00"
},
"offers": [
{
"id": "73a74948-2b57-4cc3-971f-2b441828c977",
"internal_name": "summer-2026",
"current_status": "live",
"inventory": {
"stock_condition": "out_of_stock"
},
"markets": {
"scope": "all"
},
"shipping": {
"timeline": {
"scope": "per_variant"
}
},
"widget": {
"disclaimer": {
"disclaimer_text": "Ships in August. You're charged today."
}
},
"payments": {
"options_offered": "full"
}
}
]
}{
"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": [
"A request with this Idempotency-Key is still running"
],
"code": "idempotency_key_in_progress",
"details": [
{
"code": "idempotency_key_in_progress",
"message": "A request with this Idempotency-Key is still running",
"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
}
]
}