Update a batch on an offer

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

idstringRequired

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
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
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
Example: sequential
advance_schedulestring
Example: automatic
label_formatstring
Example: Batch {{ n }}
status_textobject
Show 3 child attributesHide child attributes
- paststring
  Example: Sold out
- livestring
  Example: Live
- upcomingstring
  Example: Coming soon
widgetobject
Show 4 child attributesHide child attributes
- stylestring
  Example: roadmap
- progressstring
  Example: counts
- show_other_ship_datesboolean
  Example: true
- show_namesboolean
  Example: false
itemsarray of objects
Show 5 child attributesHide child attributes
- idstring
  Example: 6f1c9e2a-0d4b-4c1e-9a57-2f0e8d3b7c11
- positioninteger
  Example: 1
- quantity_limitinteger
  Example: 120
- shipping_textstring
  Example: Ships in June
- labelstring
  Example: Batch 1

Errors

401

Missing or invalid X-Auth-Token.

404

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

409

An earlier request with the same Idempotency-Key is still running. Wait, then resend the same request with the same key.

422

Invalid fields: one details entry per field error, its path the canonical section path. Nothing was saved.

429

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

Every error has the same shape: see Errors.

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
      }
    }
  }'

const res = await fetch("https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/batches", {
  method: "PATCH",
  headers: {
    "X-Auth-Token": process.env.STOQ_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "release_strategy": "sequential",
    "items": {
      "6f1c9e2a-0d4b-4c1e-9a57-2f0e8d3b7c11": {
        "quantity_limit": 120
      }
    }
  }),
});
const data = await res.json();

import os
import requests

res = requests.patch(
    "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/batches",
    headers={"X-Auth-Token": os.environ["STOQ_API_KEY"]},
    json={
        "release_strategy": "sequential",
        "items": {
            "6f1c9e2a-0d4b-4c1e-9a57-2f0e8d3b7c11": {
                "quantity_limit": 120
            }
        }
    },
)
data = res.json()

require "net/http"
require "json"

uri = URI("https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/batches")
req = Net::HTTP::Patch.new(uri, "X-Auth-Token" => ENV["STOQ_API_KEY"], "Content-Type" => "application/json")
req.body = {
  release_strategy: "sequential",
  items: {
    "6f1c9e2a-0d4b-4c1e-9a57-2f0e8d3b7c11" => {
      quantity_limit: 120
    }
  }
}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

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

{
  "errors": [
    "Invalid API key"
  ],
  "code": "auth_invalid",
  "details": [
    {
      "code": "auth_invalid",
      "message": "Invalid API key",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}

{
  "errors": [
    "Offer not found"
  ],
  "code": "not_found",
  "details": [
    {
      "code": "not_found",
      "message": "Offer not found",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}

{
  "errors": [
    "A request with this Idempotency-Key is still running"
  ],
  "code": "idempotency_key_in_progress",
  "details": [
    {
      "code": "idempotency_key_in_progress",
      "message": "A request with this Idempotency-Key is still running",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}

{
  "errors": [
    "widget.button.text_color must be a hex color"
  ],
  "code": "invalid_params",
  "details": [
    {
      "code": "invalid_params",
      "message": "must be a hex color",
      "path": "widget.button.text_color",
      "value": "blue",
      "expected": {
        "type": "string"
      }
    }
  ]
}

{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited",
  "details": [
    {
      "code": "rate_limited",
      "message": "Rate limit exceeded",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}