Skip to content

Bulk update variants

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

POST/preorders/offers/{id}/products/variants/bulk_update_settings

Costs 2 rate-limit points · Rate limits

Set the same shipping text, max preorder count or per-batch limits on many variants of a preorder offer.

shopify_variant_ids is required (1 to 250 variant gids attached to the offer). The other fields follow PATCH /preorders/offers/:id/products/variants/:shopify_variant_id: absent is unchanged, null clears. Variants not attached to the offer are skipped and returned in skipped_shopify_variant_ids; the call fails with 422 if none are attached.

Path parameters

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 these variants; null clears it so the offer's text shows.

  • max_countinteger, nullable

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

  • shopify_variant_idsarray of strings

    The attached variants to change: gid://shopify/ProductVariant/<id>, 1 to 250.

  • 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

  • updated_countinteger

    Variants on the offer whose settings were changed.

  • skipped_shopify_variant_idsarray of strings

    Variants asked for that are not on the offer, as sent. They are left alone.

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
job_in_progress

An earlier bulk change on the same resource is still running.

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
quantity_limit_reached

Every targeted variant has reached its preorder quantity limit, so STOQ keeps it from selling.

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/offers/{id}/products/variants/bulk_update_settings
curl -X POST "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/products/variants/bulk_update_settings" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shopify_variant_ids": [
      "gid://shopify/ProductVariant/44712349876501",
      "gid://shopify/ProductVariant/44712349909269"
    ],
    "shipping_text": "Ships early September",
    "max_count": 100
  }'
Response
{
  "updated_count": 2,
  "skipped_shopify_variant_ids": []
}