Migrate orders

Validates a batch of 1–1000 terminal orders and enqueues an async upsert job. COMPLETED, VOIDED, REVERSED, REFUNDED, and CANCELLED are accepted. OPEN and CLOSED are rejected with 422. Live OPEN/CLOSED orders are never overwritten.

Requires an access token with the orders:write scope. See Token to obtain a token.

Migrate customers first. Every customer_id must already exist as a live customer. Store, channel, fulfillment, and optional brand identifiers are validated against live records. COMPLETED orders must be PAID and include at least one payment intent. Each intent’s tenders[] are the payments. REFUNDED orders must have payment_status REFUNDED. issued_at and resolved_at are required, and resolved_at must be greater than or equal to issued_at. If you omit fulfillment_status, it is derived from status (FULFILLED, VOIDED, REVERSED, CANCELLED, or REFUNDED). The fulfillment walker is not started.

Request

curl -X POST "https://firespark.cloud/api/admin/v1/orders/migrate" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orders": [
      {
        "id": "ord-001",
        "store_id": "store-1",
        "channel_id": "web",
        "fulfillment_id": "pickup",
        "customer_id": "crm-001",
        "status": "COMPLETED",
        "payment_status": "PAID",
        "issued_at": "2024-01-01T12:00:00Z",
        "resolved_at": "2024-01-01T12:30:00Z"
      }
    ]
  }'

Response

Returns 201 with the queued job:

{
  "data": {
    "id": "8a2d41c0-1f7e-4b33-91aa-0c4e6f2d9b11",
    "status": "QUEUED",
    "accepted": 1
  }
}

Status	Meaning
`201`	Batch accepted and queued
`422`	Validation error or non-terminal status
`429`	Rate limited (`admin-migrate`) or merchant queue is full (100 queued jobs)
`503`	Rate-limit rule missing in production

Track progress in the dashboard under Orders → Migrations. Successful and failed jobs older than 30 days are deleted.

API Documentation

Endpoints

Guides

Resources

Request

Response

​Request

​Response

Request

Response