> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate orders

> Upsert a batch of terminal historical orders. Migrate customers first.

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.

> [!NOTE]
>
> Requires an access token with the `orders:write` scope. See
> [Token](https://firespark.cloud/docs/admin-api/oauth/token/post.md) 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

```bash theme={null}
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:

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.