> ## 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 customers

> Upsert a batch of customers from a legacy system. The request only validates and enqueues the job.

Validates a batch of 1–1000 customers and enqueues an async upsert job. The HTTP response returns as soon as the job is queued. Processing happens in a workflow that upserts by `id` + `merchant_id` + `env`.

> [!NOTE]
>
> Requires an access token with the `customers:write` scope. See
> [Token](https://firespark.cloud/docs/admin-api/oauth/token/post.md) to obtain a token.

Payments are not imported. Soft-deleted customers do not conflict; the import creates a live row. Duplicate `id` or `email` values inside the same batch are rejected with `422`.

Each item uses the same body as [register customer](https://firespark.cloud/docs/storefront-api/customers/post.md), except `payments` are ignored. `notification_preferences` accepts `email`, `push`, `push_token`, and `push_token_expires_at`. `push_token` and `push_token_expires_at` must be sent together; the expiry must be in the future and at most 180 days from now.

## Request

```bash theme={null}
curl -X POST "https://firespark.cloud/api/admin/v1/customers/migrate" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customers": [
      {
        "id": "crm-001",
        "name": "Jane Doe",
        "email": "jane@example.com"
      }
    ]
  }'
```

## Response

Returns `201` with the queued job:

```json theme={null}
{
  "data": {
    "id": "3b1c8f2e-5a44-4d1b-9c0e-2f6a1d8b7e90",
    "status": "QUEUED",
    "accepted": 1
  }
}
```

| Status | Meaning |
| - | - |
| `201` | Batch accepted and queued |
| `422` | Validation error |
| `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 **Customers → 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.