Skip to content

Bulk collect payments

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

POST/preorders/orders/bulk_collect_payment

Costs 2 rate-limit points · Rate limits

Collect the outstanding balance of many preorder orders now (up to 1000 order_ids, or apply_to_all with the order list filters), charging each customer's saved payment method.

Matches the dashboard bulk action Collect payment. Each order is charged its full outstanding balance; paid and cancelled orders are skipped and reported failed. Shopify settles charges asynchronously, so a succeeded order means the charge was created; its payments.last_payment_attempt shows the final state. send_notifications false suppresses the customer email sent when a charge fails. Poll status_url for per-order results.

Also searched asbulk collect paymentcollect payment for many orderscharge balances in bulkcapture payments in bulkcollect all outstanding balances

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
  • send_notificationsboolean

    Whether to email a customer whose charge fails. True by default.

    Default true

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_collect_payment
curl -X POST "https://app.stoqapp.com/api/v2/external/preorders/orders/bulk_collect_payment" \
  -H "X-Auth-Token: $STOQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_ids": [
      "5f0c8a3e-6b2d-4f1a-9c7e-2d8b1a4e6f30",
      "e27b9d40-5c13-4a8f-9e61-3f0a2c7d5b18",
      "gid://shopify/Order/6123456698900"
    ],
    "send_notifications": true
  }'
Response
{
  "job_id": "0b6f2d84-3c1e-4a97-b5d8-6e2f9a1c7b40",
  "operation": "collect_payment",
  "status": "queued",
  "status_url": "/api/v2/external/preorders/orders/jobs/0b6f2d84-3c1e-4a97-b5d8-6e2f9a1c7b40",
  "order_count": 3
}