Skip to content

Update batches

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

PATCH/preorders/offers/{id}/batches

Costs 2 rate-limit points · Rate limits

Update any subset of the batch settings on a preorder offer, including the batches themselves.

Deep partial: absent fields are unchanged; items[].label is read-only.

Also searched asedit batcheschange batch settingsmodify batchesenable batchesturn on batchessell in batchesrelease in wavesdisable batchesturn off batchesstop selling in batchesadd a batchremove a batchreorder batchesset batch limitsset batch ship datesadvance batches automaticallyauto advance batchesadvance batches manuallybatch widget stylechange batch widgetbatch progress display

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

  • release_strategystring

    sequential sells the batches one after another (needs at least two batches, a paid plan, and no market-specific offer); all_at_once turns batches off. Turning batches on uses one shipping timeline for every product and moves a Scheduled fulfillment status (shipping.delivery_timing exact_time) to Unfulfilled (asap), listed in also_changed, as the editor does.

    One of sequentialall_at_once
  • advance_schedulestring

    automatic moves to the next batch when one sells its quantity_limit (every batch then needs one); manual waits for the merchant.

    One of automaticmanual
  • label_formatstring

    Batch name; {{ n }} is replaced by the position. null uses "Batch {{ n }}".

  • status_textobject

    Words shown on the storefront for past, live and upcoming batches.

    Show 3 child attributesHide child attributes
    • paststring

      Word shown for a batch that has passed.

    • livestring

      Word shown for the batch on sale now.

    • upcomingstring

      Word shown for a batch still to come.

  • widgetobject

    Layout and content of the storefront batch widget.

    Show 4 child attributesHide child attributes
    • stylestring

      Storefront batch widget layout.

      One of roadmapstackedcompactsegmented
    • progressstring

      counts shows units sold of the limit; percent shows a percentage.

      One of countspercent
    • show_other_ship_datesboolean

      Show the other batches' ship dates on the storefront.

    • show_namesboolean

      Show batch names on the storefront.

  • itemsarray of anys

    The batches. A list replaces them: entries with an id keep that batch, entries without one are created, and batches left out are archived. An object keyed by batch id edits those batches (quantity_limit, shipping_text) and keeps the rest. Kept batches stay in their current order and new ones go at the end; positions end up 1..N. Each batch needs shipping_text; quantity_limit is all or none across batches.

Returns

  • release_strategystring

    sequential sells the batches one after another; all_at_once means batches are off.

    One of sequentialall_at_once
  • advance_schedulestring

    automatic moves to the next batch when one sells its quantity_limit; manual waits for the merchant.

    One of automaticmanual
  • label_formatstring

    Batch name format; {{ n }} is replaced by the position. Null uses "Batch {{ n }}".

  • status_textobject

    Words shown on the storefront for past, live and upcoming batches.

    Show 3 child attributesHide child attributes
    • paststring

      Word shown for a batch that has passed.

    • livestring

      Word shown for the batch on sale now.

    • upcomingstring

      Word shown for a batch still to come.

  • widgetobject

    Layout and content of the storefront batch widget.

    Show 4 child attributesHide child attributes
    • stylestring

      Batch widget layout: roadmap, stacked, compact or segmented.

    • progressstring

      counts shows units sold of the limit; percent shows a percentage.

      One of countspercent
    • show_other_ship_datesboolean

      Whether the other batches' ship dates show on the storefront.

    • show_namesboolean

      Whether batch names show on the storefront.

  • itemsarray of objects

    The batches, in selling order. Archived batches are left out.

    Show 5 child attributesHide child attributes
    • idstring

      Batch ID, used as the key in a variant's batch_limits and batch_ship_texts.

    • positioninteger

      Place in the selling order, from 1.

    • quantity_limitinteger

      Units the batch can sell. Null when unlimited.

    • shipping_textstring

      Ship text shown while this batch is on sale.

    • labelstring

      Batch name, from label_format with its position filled in.

  • also_changedarray of objects

    Settings this write changed on its own because they depend on what you changed (turning one option off can reset another). Absent when nothing else changed.

    Show 4 child attributesHide child attributes
    • settingstring

      The setting that changed, as the dashboard names it.

    • fromstring

      Its value before the write.

    • tostring

      Its value after the write.

    • reasonstring

      Why it changed.

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_params

One or more fields failed the action's schema.

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}/batches
curl -X PATCH "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/batches" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "release_strategy": "sequential",
    "items": {
      "6f1c9e2a-0d4b-4c1e-9a57-2f0e8d3b7c11": {
        "quantity_limit": 120
      }
    }
  }'
Response
{
  "release_strategy": "sequential",
  "advance_schedule": "automatic",
  "label_format": "Batch {{ n }}",
  "status_text": {
    "past": "Sold out",
    "live": "Live",
    "upcoming": "Coming soon"
  },
  "widget": {
    "style": "roadmap",
    "progress": "counts",
    "show_other_ship_dates": true,
    "show_names": false
  },
  "items": [
    {
      "id": "6f1c9e2a-0d4b-4c1e-9a57-2f0e8d3b7c11",
      "position": 1,
      "quantity_limit": 120,
      "shipping_text": "Ships in June",
      "label": "Batch 1"
    },
    {
      "id": "a3d8b5f0-7e21-4b9c-8f64-1c2d9e0a5b37",
      "position": 2,
      "quantity_limit": 200,
      "shipping_text": "Ships in July",
      "label": "Batch 2"
    }
  ]
}