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

# Migrar clientes

> Hace upsert de un lote de clientes desde un sistema legacy. La petición solo valida y encola el trabajo.

Valida un lote de 1–1000 clientes y encola un upsert asíncrono. La respuesta HTTP vuelve en cuanto el trabajo queda en cola. El procesamiento hace upsert por `id` + `merchant_id` + `env`.

> [!NOTE]
>
> Requiere un access token con el scope `customers:write`. Ver
> [Token](https://firespark.cloud/docs/es/admin-api/oauth/token/post.md).

Los pagos no se importan. Un cliente soft-deleted no genera conflicto: el import crea una fila viva. `id` o `email` duplicados en el mismo lote se rechazan con `422`.

Cada ítem usa el mismo cuerpo que [registrar cliente](https://firespark.cloud/docs/es/storefront-api/customers/post.md), excepto que `payments` se ignora. `notification_preferences` acepta `email`, `push`, `push_token` y `push_token_expires_at`. `push_token` y `push_token_expires_at` deben enviarse juntos; la fecha debe ser futura y como máximo 180 días.

## Respuesta

Devuelve `201` con el trabajo en cola (`id`, `status: QUEUED`, `accepted`).

| Estado | Significado |
| - | - |
| `201` | Lote aceptado y encolado |
| `422` | Error de validación |
| `429` | Rate limit (`admin-migrate`) o cola llena (100 trabajos en cola) |
| `503` | Falta la regla de rate limit en producción |

Sigue el progreso en el dashboard en **Clientes → Migraciones**. Los trabajos `SUCCESS`/`FAILED` de más de 30 días se eliminan.


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