Skip to content

Recalculate a variant's count

API v2 is in public beta: endpoints and fields can change before general availability. See the changelog

POST/preorders/product_variants/{shopify_variant_id}/recalculate_preorder_count

Costs 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_idstringRequired

    The variant, as gid://shopify/ProductVariant/<id> or the numeric ID.

Headers

  • Idempotency-Keystring

    A 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 (422 idempotency_key_reused); a retry while the first is still running gets 409 idempotency_key_in_progress. Keys are per store. Server errors and rate limits are not kept, so their retry runs.

Returns

  • variantobject
    Show 9 child attributesHide child attributes
    • idstring
      Example: 3f9a6c1e-8b2d-4e57-a0c4-6d1e9b7f2a85
    • shopify_variant_idstring
      Example: gid://shopify/ProductVariant/47284734423096
    • productobject
      Show 3 child attributesHide child attributes
      • shopify_product_idstring
        Example: gid://shopify/Product/8784906035384
      • titlestring
        Example: Classic Sneaker
      • statusnull
        Example: active
    • variant_titlestring
      Example: Blue / Medium
    • skustring
      Example: CS-BLU-M
    • image_urlstring
      Example: https://cdn.shopify.com/s/files/1/0712/3456/7890/files/cl…
    • offersarray of objects
      Show 6 child attributesHide child attributes
      • idstring
        Example: 73a74948-2b57-4cc3-971f-2b441828c977
      • shipping_textstring
        Example: Ships in early August
      • max_countinteger
        Example: 100
      • quantity_limitinteger
        Example: 100
      • preorder_countinteger
        Example: 38
      • quantity_limit_reachedboolean
        Example: false
    • preorder_units_soldinteger
      Example: 41
    • line_item_revenuestring
      Example: 4510.00
  • offersarray of objects
    Show 8 child attributesHide child attributes
    • idstring
      Example: 73a74948-2b57-4cc3-971f-2b441828c977
    • internal_namestring
      Example: summer-2026
    • current_statusstring
      Example: live
    • inventoryobject
      Show 1 child attributeHide child attributes
      • stock_conditionstring
        Example: out_of_stock
    • marketsobject
      Show 1 child attributeHide child attributes
      • scopestring
        Example: all
    • shippingobject
      Show 1 child attributeHide child attributes
      • timelineobject
        Show 1 child attributeHide child attributes
        • scopestring
          Example: per_variant
    • widgetobject
      Show 1 child attributeHide child attributes
      • disclaimerobject
        Show 1 child attributeHide child attributes
        • disclaimer_textstring
          Example: Ships in August. You're charged today.
    • paymentsobject
      Show 1 child attributeHide child attributes
      • options_offeredstring
        Example: full

Errors

404
not_found

The path is valid but nothing with that id exists in this store.

409
idempotency_key_in_progress

An earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.

422
invalid_amount

The amount is not a positive decimal with at most 2 places.

422
missing_amount

Collecting a partial payment needs an amount or the line items to collect for.

422
unknown_line_items

Some of the line item ids are not on the order.

422
validation_failed

The 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.

POST/preorders/product_variants/{shopify_variant_id}/recalculate_preorder_count
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"
Response
{
  "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"
      }
    }
  ]
}