Skip to content

Get batches

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

GET/preorders/offers/{id}/batches

Costs 1 rate-limit point · Rate limits

Read the batch settings of a preorder offer: release strategy, advance schedule, labels, storefront widget and the kept batches in order.

Batches only run while release_strategy is sequential, which needs a paid plan, at least two items and an offer not scoped to markets. With advance_schedule automatic a variant moves to the next batch once it sells that batch's quantity_limit; with manual it waits for POST /preorders/offers/:id/products/advance_batches. Each item's label comes from label_format and is read-only. Per-variant batch limits and progress are on GET /preorders/offers/:id/products/variants. Edit with PATCH /preorders/offers/:id/batches.

Also searched asget batchesshow batchesview batchesbatch settingslist batches

Path parameters

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.

Errors

404
not_found

The path is valid but nothing with that id exists in this store.

422
invalid_params

One or more fields failed the action's schema.

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.

GET/preorders/offers/{id}/batches
curl "https://app.stoqapp.com/api/v2/external/preorders/offers/73a74948-2b57-4cc3-971f-2b441828c977/batches" \
  -H "X-Auth-Token: $STOQ_API_KEY"
Response
{
  "release_strategy": "sequential",
  "advance_schedule": "automatic",
  "label_format": "string",
  "status_text": {
    "past": "string",
    "live": "string",
    "upcoming": "string"
  },
  "widget": {
    "style": "string",
    "progress": "counts",
    "show_other_ship_dates": true,
    "show_names": true
  },
  "items": [
    {
      "id": "string",
      "position": 1,
      "quantity_limit": 1,
      "shipping_text": "string",
      "label": "string"
    }
  ]
}