Skip to content

Bulk hold fulfillments

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

POST/preorders/orders/bulk_hold_fulfillments

Costs 2 rate-limit points · Rate limits

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

Matches the dashboard bulk action Hold fulfillments. Cancelled and fulfilled orders, and orders with nothing to hold, are reported failed. Poll status_url for per-order results.

Also searched asbulk hold fulfillmentshold many ordersbulk hold ordershold 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
  • reason_notesstring

    Reason shown on each hold in Shopify. Defaults to the standard hold note.

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.

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_hold_fulfillments
curl -X POST "https://app.stoqapp.com/api/v2/external/preorders/orders/bulk_hold_fulfillments" \
  -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": "open",
    "reason_notes": "Waiting on stock"
  }'
Response
{
  "job_id": "5d1a8e3f-7b26-4c90-a4e1-2f8c6b9d0a73",
  "operation": "hold_fulfillments",
  "status": "queued",
  "status_url": "/api/v2/external/preorders/orders/jobs/5d1a8e3f-7b26-4c90-a4e1-2f8c6b9d0a73",
  "order_count": 42
}