CSV Migration

The migration API lets you bulk-import patients, products, coupons, orders, and subscriptions from CSV files. Imports follow a dry-run → run-live lifecycle to catch errors before any records are written to production.

Job lifecycle

Upload CSV
    │
    ▼
PENDING_VALIDATION  ──▶  VALIDATING  ──▶  VALIDATION_COMPLETE
                                                  │
                              errorRows > 0?      │
                                  No ─────────────┤
                                                  ▼
                                           PENDING_IMPORT  ──▶  IMPORTING  ──▶  COMPLETED
                                                                                    │
                                                                               ROLLED_BACK
                          ┌─────────────── FAILED ◀── any step

Status	Meaning
`PENDING_VALIDATION`	Job created; queued for dry-run validation
`VALIDATING`	Worker is parsing and validating the CSV
`VALIDATION_COMPLETE`	Dry-run finished; check `errorRows` before promoting
`PENDING_IMPORT`	Live job created; queued for actual import
`IMPORTING`	Worker is writing records to the database
`COMPLETED`	All records imported successfully
`FAILED`	Unrecoverable error during validation or import
`ROLLED_BACK`	Live import rolled back via the rollback action

Required import order

When migrating all entity types, import them in this order to satisfy foreign-key dependencies:

PATIENTS
PRODUCTS
COUPONS
ORDERS
SUBSCRIPTIONS

File requirements

Format: text/csv with a header row
Max file size: 50 MB
Encoding: UTF-8

Download blank template files from GET /v2/migration/templates/:type.