Skip to content

Update an offer's variant

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

PATCH/preorders/offers/{id}/products/variants/{shopify_variant_id}

Costs 2 rate-limit points · Rate limits

Set one variant's Limit, Shipping and per-batch limits on a preorder offer, as the Products table edits them.

Deep partial: absent fields are unchanged. null clears shipping_text (the offer's text shows) and removes max_count. :shopify_variant_id is the variant's Shopify gid (a numeric id also works). market_overrides is no longer accepted; set per-market values on the offer instead.

Also searched asoverride variant settingsset shipping text for variantset max count for variantper-variant overrides

Path parameters

  • idstringRequired

    The offer's ID, from GET /preorders/offers.

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

Request body

  • shipping_textstring, nullable

    Shipping text for this variant only; null clears it so the offer's text shows.

  • max_countinteger, nullable

    Quantity limit for this variant, 1 or more; null removes it. Refused while the offer has batches on.

  • batch_limitsobject

    This variant's own quantity limit per batch, keyed by batch_id (from GET /preorders/offers/:id/batches). A batch left out is unchanged; null puts the variant back on the batch's quantity_limit; batch_limits: null clears every batch. Needs batches on and a quantity_limit on every batch. Values are whole numbers of 1 or more.

  • batch_ship_textsobject

    This variant's own ship text per batch, keyed by batch_id (from GET /preorders/offers/:id/batches), e.g. "Ships July 1" for one size while the batch ships June 10. A batch left out is unchanged; null or "" puts the variant back on the batch's shipping_text; batch_ship_texts: null clears every batch. Needs batches on.

Returns

  • idstring

    ID of this variant's place on the offer.

  • shopify_variant_idstring

    The variant, as gid://shopify/ProductVariant/<id>.

  • productobject

    The variant's product.

    Show 3 child attributesHide child attributes
    • shopify_product_idstring

      The product, as gid://shopify/Product/<id>.

    • titlestring

      Product title.

    • statusnull

      Product status in Shopify, such as active, draft, archived or unlisted. Null when not stored yet; include_statuses=true reads it from Shopify.

  • titlestring

    Variant name: product and variant title together, or the product title alone for a product's only variant.

  • variant_titlestring

    Variant title. Null for a product's only variant (Shopify's "Default Title").

  • skustring

    Variant SKU. Null when it has none.

  • discardedboolean

    true when the variant has been deleted from the catalog.

  • shipping_textstring, nullable

    This variant's own shipping text. Null when it has none and the offer's text shows.

  • max_countinteger, nullable

    This variant's own quantity limit. Null when it has none. Kept but not enforced while the offer has batches on.

  • quantity_limitinteger, nullable

    The quantity limit that applies: max_count, or the batches' total on a batch offer. Null when unlimited. Read-only.

  • preorder_countinteger

    Units preordered that count toward the quantity limit.

  • quantity_limit_reachedboolean

    true when preorder_count has reached quantity_limit, or the batch limit on a batch offer.

  • current_batch_idnull

    Batch the variant is selling in now. Null when the offer has batches off or the variant is in no batch.

  • created_atstring

    When the variant was added to the offer, ISO 8601 in UTC.

  • batch_limitsobject

    This variant's own quantity limit per batch, keyed by batch ID. Batches left out use the batch's quantity_limit.

  • batch_ship_textsobject

    This variant's own ship text per batch, keyed by batch ID. Batches left out use the batch's shipping_text.

  • batch_progressnull

    Units sold and the limit per batch, and the batch on sale now. Null when the offer has batches off.

Errors

404
not_found

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

409
conflict

The request is well formed, but the resource's current state does not allow it.

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_params

One or more fields failed the action's schema.

422
validation_failed

The request failed validation.

502
shopify_error

A Shopify call the operation needs failed after the operation had started.

503
upstream_unavailable

A service the answer depends on did not respond in time.

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.

PATCH/preorders/offers/{id}/products/variants/{shopify_variant_id}
curl -X PATCH "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/products/variants/{shopify_variant_id}" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping_text": "Ships early September",
    "max_count": 75
  }'
Response
{
  "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": "Ships early September",
  "max_count": 75,
  "quantity_limit": 75,
  "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
}