Update batches

PATCH

/preorders/offers/{id}/batches

curl --request PATCH \
  --url https://app.stoqapp.com/api/v2/external/preorders/offers/example/batches \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: <X-Auth-Token>' \
  --data '{ "release_strategy": "sequential", "items": { "6f1c9e2a-0d4b-4c1e-9a57-2f0e8d3b7c11": { "quantity_limit": 120 } } }'

• Production

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

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

Authorizations

• ApiKeyAuth

Parameters

Path Parameters

id

required

string

Request Body^required

Media typeapplication/json

object

release_strategy

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.

string

Allowed values: sequential all_at_once

advance_schedule

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

string

Allowed values: automatic manual

label_format

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

string

status_text

object

past

Word shown for a batch that has passed.

string

live

Word shown for the batch on sale now.

string

upcoming

Word shown for a batch still to come.

string

widget

object

style

Storefront batch widget layout.

string

Allowed values: roadmap stacked compact segmented

progress

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

string

Allowed values: counts percent

show_other_ship_dates

Show the other batches’ ship dates on the storefront.

boolean

show_names

Show batch names on the storefront.

boolean

items

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.

array

Example

{
  "release_strategy": "sequential",
  "items": {
    "6f1c9e2a-0d4b-4c1e-9a57-2f0e8d3b7c11": {
      "quantity_limit": 120
    }
  }
}

Responses

200

Success — example response shown.

Media typeapplication/json

object

Example

{
  "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"
    }
  ]
}

202

Saved. Returns the updated section, with also_changed for cascades.

Media typeapplication/json

object

Example ^generated

{}

401

Missing or invalid X-Auth-Token.

Media typeapplication/json

Error envelope returned by every failed request.

object

errors

required

Array<string>

Example

{
  "errors": [
    "Unauthorized"
  ]
}

404

The resource does not exist for this shop, or the action path is not registered.

Media typeapplication/json

Error envelope returned by every failed request.

object

errors

required

Array<string>

Example

{
  "errors": [
    "Offer not found"
  ]
}

422

Invalid fields, keyed by canonical section paths. Nothing was saved.

Media typeapplication/json

object

errors

required

object

key

additional properties

Array<string>

Example ^generated

{
  "errors": {
    "additionalProperty": [
      "example"
    ]
  }
}

429

Rate limited — cost-weighted per token (read 1, write 2; 360 points / 60s). Check Retry-After.

Media typeapplication/json

Error envelope returned by every failed request.

object

errors

required

Array<string>

Example

{
  "errors": [
    "Rate limit exceeded"
  ]
}