Bulk import
The column contract for file uploads and the Google Sheets sync.
When to use it
Import is the batch path for systems that already produce a spreadsheet, and today it is also how orders created outside the dashboard get queued for a confirmation call. It does not return the created ids, so match rows back by the fingerprint described under Deduplication, or read them out of the orders table afterwards.
Column matching
Headers are lowercased and matched by substring, first match wins. Extra columns are ignored.
| Target field | Header matches on | Required |
|---|---|---|
| client_name | client, customer, name | yes |
| phone | phone, mobile, number, tel | yes |
| store_name | store, shop, vendor | yes |
| products_name | product, item, description | yes |
| address | address, location, delivery | no |
| google_sheet_order_id | order id, id, orderid, order | no |
| created_at | date, created, order date | no |
Header collisions
Substring matching is greedy, so a header like "order name" can be claimed by the client_name matcher before your intended column. Name headers unambiguously (client name, phone, store name, products) if a sheet is generated by your code.
Sources
- File upload
- .csv, .xlsx, and .xls. The first row is treated as the header row.
- Google Sheets link
- The sheet must be shared as "Anyone with the link can view". Same header contract.
- Connected Google account
- OAuth connection under Integrations, which re-syncs new rows rather than importing once.
Deduplication
The sync skips a row when an existing order matches on the fingerprint store_name + client_name + phone + products_name, with the phone compared in its normalized form. Re-running a sync over the same sheet is safe. Changing any of those four values makes the row look new.
Row failures
Rows are validated individually against the same rules as the API. An invalid row is reported and skipped, and the rest of the batch still imports. A whole-file rejection means a required column was not found at all.