> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/admin/data-migration/start-a-data-import.md). # Start a data import Starts a bulk import from one or more uploaded data files. Use this as the first step of a migration: pick the record type you are importing, upload the file(s), and receive an identifier you can use to track progress and review errors. The import runs in the background — the response returns immediately with an identifier, not the final result. The record type is chosen with the `migration_key` in the path; each type has its own set of columns: * `user` — customer accounts, with login credentials (columns: UserImportRow) * `address` — delivery/billing addresses of migrated customers (columns: AddressImportRow) * `order` — historical orders of migrated customers (columns: OrderImportRow) * `order_item` — line items of migrated orders (columns: OrderItemImportRow) * `retail_store` — physical stores (columns: RetailStoreImportRow) Each uploaded file must be tabular, with one record per row and the columns listed for the chosen record type. Multiple files may be uploaded together. Import options can be supplied in the `params` field (see ImportOptions). ```json {"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"tags":[{"name":"Data Migration","description":"Bulk-import existing customer, address, order and store records into the commerce platform. These endpoints are used when moving a merchant's data from an external or legacy system into Akinon — most commonly during an initial go-live or a platform migration — without re-entering records by hand.\n\n## What you can migrate\n\nEach import handles a single kind of record. Choose the type that matches the data file you are uploading:\n\n- **Customers** — customer accounts, including their login credentials\n- **Addresses** — delivery and billing addresses linked to migrated customers\n- **Orders** — historical orders linked to migrated customers\n- **Order items** — the line items belonging to migrated orders\n- **Retail stores** — physical store records\n\n## Typical workflow\n\nA migration runs in the background, so the three endpoints are used in order:\n\n1. **Start the import** by uploading one or more data files for a given record\n type. The response returns an identifier for the import.\n2. **Track progress** by polling with that identifier until the import finishes.\n3. **Review errors** with the same identifier to see which records were\n rejected and why, so they can be corrected and re-uploaded.\n\nBecause addresses, orders and order items reference customers (and order items\nreference orders), migrate the records in a dependency-friendly order: customers\nfirst, then addresses and orders, then order items.\n\n## Data files\n\nUploaded files must be tabular: the **first row is the header**, and each of\nthe following rows is one record. Every column header must exactly match a\nfield name of the record type you are importing (for example `customer_code`,\n`order_number`), and the values must follow the types described for that type.\n\nThe file format is taken from the file extension. CSV is the primary format —\nits separator (`;`, `,` or `|`) is detected automatically — and common\nspreadsheet formats such as Excel are also accepted. More than one file may be\nuploaded in a single request; all rows are imported together."}],"servers":[{"description":"Omnitron Remote Proxy (external access — recommended)","url":"https://{omnitron_url}/api/remote/{channel_id}","variables":{"omnitron_url":{"default":"sandbox.akinon.com","description":"Omnitron server URL (e.g., {omnitron.akinon.com})"},"channel_id":{"default":"1","description":"The channel identifier the remote request is routed through"}}},{"description":"Commerce API Server (internal / direct access only)","url":"https://{commerce_url}/api/v1","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Internal commerce server URL, reachable only from within the Omnitron network"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token credential sent in the Authorization header, in the form: `Token `. Requires a staff (admin) account."}},"schemas":{"ErrorResponse":{"type":"object","description":"Standard error payload.","properties":{"non_field_errors":{"type":"string","description":"Human-readable error message."},"error_code":{"type":"string","description":"Machine-readable error code."}}}}},"paths":{"/migrations/start/{migration_key}/":{"post":{"tags":["Data Migration"],"summary":"Start a data import","description":"Starts a bulk import from one or more uploaded data files. Use this as the\nfirst step of a migration: pick the record type you are importing, upload\nthe file(s), and receive an identifier you can use to track progress and\nreview errors.\n\nThe import runs in the background — the response returns immediately with an\nidentifier, not the final result.\n\nThe record type is chosen with the `migration_key` in the path; each type\nhas its own set of columns:\n\n- `user` — customer accounts, with login credentials (columns: UserImportRow)\n- `address` — delivery/billing addresses of migrated customers (columns: AddressImportRow)\n- `order` — historical orders of migrated customers (columns: OrderImportRow)\n- `order_item` — line items of migrated orders (columns: OrderItemImportRow)\n- `retail_store` — physical stores (columns: RetailStoreImportRow)\n\nEach uploaded file must be tabular, with one record per row and the columns\nlisted for the chosen record type. Multiple files may be uploaded together.\nImport options can be supplied in the `params` field (see ImportOptions).","operationId":"startMigration","parameters":[{"name":"migration_key","in":"path","required":true,"description":"The type of record to import.","schema":{"type":"string","enum":["user","address","order","order_item","retail_store"]}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["files"],"properties":{"files":{"type":"array","description":"One or more tabular data files. Each row is one record; columns must match the fields of the chosen record type. At least one file part is required, but the form-part name itself is not significant — every uploaded file is processed regardless of the field name used (it need not literally be `files`).","items":{"type":"string","format":"binary"}},"params":{"type":"string","description":"Optional JSON object (sent as a string) with import options. See the Import options schema for the available settings."}}}}}},"responses":{"200":{"description":"The import has been queued. Use the returned identifier to track it.","content":{"application/json":{"schema":{"type":"object","properties":{"migration_id":{"type":"string","description":"Identifier of the started import."}}}}}},"400":{"description":"The request could not be accepted — for example an unknown record type, or no data file was uploaded. Individual rows are validated while the import runs, not here; row-level problems appear via the errors endpoint."},"401":{"description":"Authentication credentials were missing or invalid."},"403":{"description":"The account does not have staff (admin) permission."},"406":{"description":"The import options could not be read as JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://apidocs.akinon.com/commerce-openapis/admin/data-migration/start-a-data-import.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.