Skip to content

Advance an offer's batches

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

POST/preorders/offers/{id}/products/advance_batches

Costs 2 rate-limit points · Rate limits

Move variants on a batch preorder offer to their next batch, as the Products table's 'Start next batch' does.

Batch offers only. shopify_variant_ids are Shopify variant gids; omit it for every variant that is in a batch. A variant on its last batch stops selling (inventory policy DENY). Ones not on the offer come back under not_attached.

Also searched asadvance batchstart next batchnext waveadvance variants to next batch

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

  • shopify_variant_idsarray of strings

    Variants to advance: Shopify variant gids. Omit for every variant that is in a batch.

Returns

  • advanced_countinteger

    Variants moved to their next batch.

  • variantsarray of objects

    Those variants after the move, as rows of the offer's Products table.

    Show 17 child attributesHide child attributes
    • 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

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

    • max_countinteger

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

    • quantity_limitinteger

      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_idstring

      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_progressobject

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

      Show 2 child attributesHide child attributes
      • current_batch_idstring

        Batch the variant is selling in now.

      • batchesarray of objects

        Every batch, in selling order.

        Show 5 child attributesHide child attributes
        • batch_idstring

          Batch ID.

        • positioninteger

          Place in the selling order, from 1.

        • quantity_limitinteger

          Limit enforced for this variant in the batch: its own batch_limits value, or the batch's.

        • default_quantity_limitinteger

          The batch's own quantity_limit.

        • countinteger

          Units of this variant sold in the batch.

  • not_attachedarray of anys

    Variants asked for that are not on the offer or not valid IDs, as sent.

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
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/advance_batches
curl -X POST "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/products/advance_batches" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shopify_variant_ids": [
      "gid://shopify/ProductVariant/44712349876501"
    ]
  }'
Response
{
  "advanced_count": 1,
  "variants": [
    {
      "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": null,
      "max_count": 10,
      "quantity_limit": 200,
      "preorder_count": 100,
      "quantity_limit_reached": false,
      "current_batch_id": "e3a1b9c4-7d20-4f5e-a8b6-1c9d0e2f3a45",
      "created_at": "2026-06-25T10:42:10Z",
      "batch_limits": {},
      "batch_ship_texts": {},
      "batch_progress": {
        "current_batch_id": "e3a1b9c4-7d20-4f5e-a8b6-1c9d0e2f3a45",
        "batches": [
          {
            "batch_id": "0a6f2d8e-41b7-4c39-9e05-6b8d3f1c2a77",
            "position": 1,
            "quantity_limit": 100,
            "default_quantity_limit": 100,
            "count": 100
          },
          {
            "batch_id": "e3a1b9c4-7d20-4f5e-a8b6-1c9d0e2f3a45",
            "position": 2,
            "quantity_limit": 100,
            "default_quantity_limit": 100,
            "count": 0
          }
        ]
      }
    }
  ],
  "not_attached": []
}