Create multiple orders in one request.

Batch processed with one or more failures

POST /v1/tenants/{tenant_id}/orders/batch

cURL

curl --request POST \
  --url 'https://api.sync.stateset.com/v1/tenants/{tenant_id}/orders/batch' \
  --header "x-stateset-api-key: $STATESET_SYNC_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "dryRun": false,
  "orders": [
    {
      "createdAt": "2026-08-31T14:22:05Z",
      "externalOrderId": "string",
      "externalPlatform": "string",
      "lineItems": [],
      "locationId": "string",
      "netsuiteId": "string",
      "orderNumber": "M-1001",
      "shopifyOrderId": "1234567890",
      "sourceOrderPayload": null,
      "tags": [],
      "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "stopOnError": true
}'

200

{
  "completed": true,
  "dryRun": false,
  "failed": 1,
  "results": [
    {
      "action": "string",
      "error": {
        "code": null,
        "message": null
      },
      "index": 1,
      "shopifyOrderId": "string",
      "statesetOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "success": true
    }
  ],
  "succeeded": 1,
  "total": 102
}

Path parameters

tenant_id · string · required

Tenant identifier

Query parameters

dry_run · boolean

When true, validates and previews results without creating orders

Request body

CreateOrdersBatchRequest

dryRun · boolean

Validate and preview batch execution without writing any orders.

orders · CreateOrderRequest[]

Orders to create in sequence.

stopOnError · boolean

Stop processing after the first failed item.

Response

CreateOrdersBatchResponse

completed · boolean · required

Whether every input entry was attempted.

dryRun · boolean · required

True when the request executed in dry-run mode (no writes performed).

failed · integer · required

Number of failed orders.

results · CreateOrderBatchResult[] · required

Per-order result details.

Show CreateOrderBatchResult

action · string · required

Result action: · created_or_reused for live writes. · would_create / would_reuse_existing for dry-run previews. · failed when validation or write fails.

error · object

Show error

code · string · required

Stable machine-readable error code.

message · string · required

Human-readable error message.

index · integer · required

Input index of this order in the original request array.

shopifyOrderId · string · required

Shopify order id from input.

statesetOrderId · string (uuid)

Created/reused StateSet order id on success.

success · boolean · required

True when creation succeeded (or was idempotently resolved).

succeeded · integer · required

Number of successfully created/reused orders.

total · integer · required

Number of input orders.

Status codes

Code	Meaning
200	Batch processed with one or more failures
201	All orders created successfully
401	Unauthorized - invalid or missing API key
422	Validation error

cURL

curl --request POST \
  --url 'https://api.sync.stateset.com/v1/tenants/{tenant_id}/orders/batch' \
  --header "x-stateset-api-key: $STATESET_SYNC_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "dryRun": false,
  "orders": [
    {
      "createdAt": "2026-08-31T14:22:05Z",
      "externalOrderId": "string",
      "externalPlatform": "string",
      "lineItems": [],
      "locationId": "string",
      "netsuiteId": "string",
      "orderNumber": "M-1001",
      "shopifyOrderId": "1234567890",
      "sourceOrderPayload": null,
      "tags": [],
      "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
  ],
  "stopOnError": true
}'

200

{
  "completed": true,
  "dryRun": false,
  "failed": 1,
  "results": [
    {
      "action": "string",
      "error": {
        "code": null,
        "message": null
      },
      "index": 1,
      "shopifyOrderId": "string",
      "statesetOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "success": true
    }
  ],
  "succeeded": 1,
  "total": 102
}