Skip to content

Bulk release holds

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

POST/preorders/orders/bulk_release

Costs 2 rate-limit points · Rate limits

Release fulfillment holds on many preorder orders (up to 1000 order_ids, or apply_to_all with the order list filters).

Matches the dashboard bulk action Release "On hold" fulfillments. Poll status_url for per-order results.

Also searched asbulk releaserelease many ordersbatch releaserelease these orders

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

  • searchstring

    Order number or name, customer name, email, Shopify order id or gid, or admin order URL.

  • financial_statusstring

    Comma-separated Shopify financial statuses.

  • fulfillment_statusstring

    Comma-separated Shopify fulfillment statuses.

  • preorder_fulfillment_statusstring

    Comma-separated: on_hold, scheduled, open.

  • cancelled_statusstring

    Only cancelled orders, or only orders that are not cancelled.

    One of cancellednot_cancelled
  • payment_collection_statusstring

    Comma-separated: failed, success, unknown.

  • offer_idstring

    Comma-separated offer ids.

  • shopify_variant_idstring

    Comma-separated Shopify variant gids.

  • shopify_product_idstring

    Comma-separated Shopify product gids.

  • vendorsarray of strings

    Only orders with a preorder item from one of these vendor names. A single string is read as one vendor.

  • customer_idstring

    Our customer id.

  • fromstring

    Created on or after. A bare date is that whole day in shop time.

  • tostring

    Created on or before. A bare date is that whole day in shop time.

  • order_idsarray of strings

    Order ids or Shopify order ids (max 1000).

  • apply_to_allboolean

    Instead of order_ids: every order matching the GET /preorders/orders filters sent alongside (all preorder orders when none), like the dashboard's select all.

    Default false

Returns

  • job_idstring

    Id of the background job doing the work.

  • operationstring

    The bulk action started.

    One of releasesend_confirmationsend_shipping_updateopen_scheduled_fulfillmentsreschedule_fulfillmentreschedule_paymentcollect_paymenthold_fulfillmentssplit_fulfillment_orders
  • statusstring

    Always queued: the job runs in the background. Poll status_url for progress.

    One of queued
  • status_urlstring

    Path of the endpoint that reports this job's progress; poll it until the job finishes. Results are kept for 24 hours.

  • order_countinteger

    How many orders the job will act on.

Errors

403
forbidden

The credential is valid, but the store's plan or settings do not allow this operation.

403
plan_required

The change uses a feature that is only available on a paid STOQ plan. Connecting a paid-only integration returns 403; a write that sets paid-only fields returns 422 and saves nothing.

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
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.

POST/preorders/orders/bulk_release
curl -X POST "https://app.stoqapp.com/api/v2/external/preorders/orders/bulk_release" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apply_to_all": true,
    "offer_id": "73a74948-2b57-4cc3-971f-2b441828c977",
    "preorder_fulfillment_status": "on_hold"
  }'
Response
{
  "job_id": "e8f24b6d-1a93-4c57-b0e2-9d6a3f5c1b78",
  "operation": "release",
  "status": "queued",
  "status_url": "/api/v2/external/preorders/orders/jobs/e8f24b6d-1a93-4c57-b0e2-9d6a3f5c1b78",
  "order_count": 42
}