Skip to content

Update products

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

PATCH/preorders/products

Costs 2 rate-limit points · Rate limits

Save rows of the store-wide Preorders > Products tab: link each variant to one offer or to none, and set its shipping text and quantity limit on the offers it is in.

variants is a list of up to 100 rows. A row's offer_id replaces every offer the variant is in with that one, and null takes it out of all of them, as the tab's 'Offer linked' select does; omit offer_id to leave the links. Offers that sell in selected markets only cannot be picked, and a variant in one is skipped (skipped_market_shopify_variant_ids); change those on the offer itself. offers sets this variant's shipping_text and max_count on offers it is in; shipping_text only on an offer whose shipping text is per variant, max_count (1 or more) only on an out-of-stock offer. null clears either one; a key left out is unchanged. max_count is the variant's own limit, the same field GET /preorders/products returns, so writing a read value back changes nothing. On an offer with batches on, limits are per batch: max_count (a value or null) returns 422 there, so set batch_limits on PATCH /preorders/offers/:id/products/variants/:shopify_variant_id instead. quantity_limit is read-only. inventory_policy (CONTINUE or DENY) also sets 'Continue selling' on the variants whose offer_id changed, as the save confirm's Turn on / Turn off does; omit it for 'Don't change'. Variants STOQ has not stored yet are read from Shopify. Finishes before the response.

Also searched aslink product to offermove variant to offerchange offer linkedunlink product from offerset shipping text for variantset quantity limit for variantsave products tab

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

  • variantsarray of objects

    Rows to save: [{shopify_variant_id, offer_id?, offers?: [{id, shipping_text?, max_count?}]}]. offer_id null takes the variant out of every offer. max_count is refused on an offer with batches on.

    Show 3 child attributesHide child attributes
    • shopify_variant_idstring

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

    • offer_idstring, nullable

      The one offer to link the variant to, replacing its other offers; null removes it from every offer.

    • offersarray of objects

      Per-offer values for this variant on offers it is in.

      Show 3 child attributesHide child attributes
      • idstring

        Offer ID.

      • shipping_textstring, nullable

        This variant's shipping text on that offer; null clears it.

      • max_countinteger, nullable

        This variant's quantity limit on that offer, 1 or more; null removes it.

  • inventory_policystring

    Also turn 'Continue selling' on (CONTINUE) or off (DENY) for the variants whose offer_id changed. Omit to leave it.

    One of CONTINUEDENY

Returns

  • variantsarray of objects
    Show 7 child attributesHide child attributes
    • idstring
      Example: e2c7a5f1-9d4b-4c68-b3a0-8e6f1d9c4b27
    • shopify_variant_idstring
      Example: gid://shopify/ProductVariant/47284734488632
    • productobject
      Show 3 child attributesHide child attributes
      • shopify_product_idstring
        Example: gid://shopify/Product/8784906035384
      • titlestring
        Example: Classic Sneaker
      • statusstring
        Example: active
    • variant_titlestring
      Example: Blue / Large
    • skustring
      Example: CS-BLU-L
    • 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, nullable
        Example: Ships in late August
      • max_countinteger, nullable
        Example: 60
      • quantity_limitinteger, nullable
        Example: 60
      • preorder_countinteger
        Example: 0
      • quantity_limit_reachedboolean
        Example: false
  • skipped_market_shopify_variant_idsarray of strings
  • inventory_policyobject
    Show 2 child attributesHide child attributes
    • policystring
      Example: CONTINUE
    • shopify_variant_idsarray of strings

Errors

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.

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/products
curl -X PATCH "https://app.stoqapp.com/api/v2/external/preorders/products" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "variants": [
      {
        "shopify_variant_id": "gid://shopify/ProductVariant/47284734488632",
        "offer_id": "73a74948-2b57-4cc3-971f-2b441828c977",
        "offers": [
          {
            "id": "73a74948-2b57-4cc3-971f-2b441828c977",
            "shipping_text": "Ships in late August",
            "max_count": 60
          }
        ]
      }
    ],
    "inventory_policy": "CONTINUE"
  }'
Response
{
  "variants": [
    {
      "id": "e2c7a5f1-9d4b-4c68-b3a0-8e6f1d9c4b27",
      "shopify_variant_id": "gid://shopify/ProductVariant/47284734488632",
      "product": {
        "shopify_product_id": "gid://shopify/Product/8784906035384",
        "title": "Classic Sneaker",
        "status": "active"
      },
      "variant_title": "Blue / Large",
      "sku": "CS-BLU-L",
      "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 late August",
          "max_count": 60,
          "quantity_limit": 60,
          "preorder_count": 0,
          "quantity_limit_reached": false
        }
      ]
    }
  ],
  "skipped_market_shopify_variant_ids": [],
  "inventory_policy": {
    "policy": "CONTINUE",
    "shopify_variant_ids": [
      "gid://shopify/ProductVariant/47284734488632"
    ]
  }
}