Imports
CSV / Excel / Google Sheets / feed imports.
5 endpoints.
GET /v1/importsPOST /v1/importsPOST /v1/imports/uploadGET /v1/imports/{import_id}PATCH /v1/imports/{import_id}
GET
/v1/importsList imports
Needs a key or a dashboard session
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
cursor | query | string | null | no | max length 200 |
limit | query | integer | no | default 20 · min 1 · max 200 |
Responses
- 200Successful Response
Page_ImportOut_
POST
/v1/importsStart an import from a URL (Google Sheets, Google Merchant feed)
Needs a key or a dashboard session
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | null | no | Unique per logical write (8-255 chars). Retries with the same key are safe. · pattern ^[A-Za-z0-9_\-:.]{8,255}$ |
Request body application/json ImportCreate
| Name | Type | Required | Description |
|---|---|---|---|
source | "csv" | "xlsx" | "gsheet" | "feed_google" | yes | |
url | string | null | no | Google Sheets or feed URL.max length 2048 |
mapping | map<string, string> | no | Column -> product field, e.g. {"Product name": "name.ar", "Price": "price", "Colour": "attributes.Color", "Notes": "ignore"}. Columns without a mapping are matched by name. |
dry_run | boolean | no | default false |
locale | string | null | no | Language of untagged text (a plain `name` column, feed titles). Default: the store's default language.pattern ^[a-z]{2}$ |
repeat | "hourly" | "daily" | null | no | URL imports only: run the same import again every hour or every day. |
Responses
- 202Successful Response
ImportOut
POST
/v1/imports/uploadStart an import from a CSV or Excel file
Needs a key or a dashboard session
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
Idempotency-Key | header | string | null | no | Unique per logical write (8-255 chars). Retries with the same key are safe. · pattern ^[A-Za-z0-9_\-:.]{8,255}$ |
Request body multipart/form-data Body_imports_upload
| Name | Type | Required | Description |
|---|---|---|---|
file | string | yes | |
source | "csv" | "xlsx" | "gsheet" | "feed_google" | yes | |
dry_run | boolean | no | default false |
mapping | string | null | no | JSON object, column -> product field (see ImportCreate).max length 20000 |
locale | string | null | no | pattern ^[a-z]{2}$ |
Responses
- 202Successful Response
ImportOut
GET
/v1/imports/{import_id}Get one import
Needs a key or a dashboard session
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
import_id | path | string | yes |
Responses
- 200Successful Response
ImportOut
PATCH
/v1/imports/{import_id}Change or stop a repeating URL import
Needs a key or a dashboard session
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
import_id | path | string | yes | |
Idempotency-Key | header | string | null | no | Unique per logical write (8-255 chars). Retries with the same key are safe. · pattern ^[A-Za-z0-9_\-:.]{8,255}$ |
Request body application/json ImportUpdate
| Name | Type | Required | Description |
|---|---|---|---|
repeat | "hourly" | "daily" | null | no |
Responses
- 200Successful Response
ImportOut
Data shapes on this page
Page_ImportOut_
| Name | Type | Required | Description |
|---|---|---|---|
data | ImportOut[] | yes | |
next_cursor | string | null | no | |
total | integer | null | no | Present when cheap to count. |
ImportOut
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
source | "csv" | "xlsx" | "gsheet" | "feed_google" | "connector" | "api" | yes | |
status | "queued" | "running" | "succeeded" | "failed" | "canceled" | yes | |
stats | map<string, integer> | no | |
errors | ItemError[] | no | |
created_at | string (date-time) | yes | |
finished_at | string (date-time) | null | no | |
job | Job | null | no | |
source_url | string | null | no | |
filename | string | null | no | |
locale | string | null | no | |
dry_run | boolean | no | default false |
repeat | "hourly" | "daily" | null | no | |
next_run_at | string (date-time) | null | no | |
parent_id | string | null | no | The repeating import that started this run. |
started_at | string (date-time) | null | no |
ItemError
| Name | Type | Required | Description |
|---|---|---|---|
id | string | null | no | |
index | integer | yes | |
code | string | yes | |
message | string | yes |
Job
A row of the shared `jobs` table. Poll GET /v1/jobs/{id} until status is terminal.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
kind | "reindex" | "import" | "sync" | "translate_backfill" | "translate_writeback" | "export" | "data_export" | "data_delete" | "embed" | "synonym_mining" | yes | |
status | "queued" | "running" | "succeeded" | "failed" | "canceled" | yes | |
progress | number | no | default 0 · min 0 · max 1 |
created_at | string (date-time) | yes | |
started_at | string (date-time) | null | no | |
finished_at | string (date-time) | null | no | |
result | object | null | no | |
error | string | null | no |
ImportCreate
For file imports send multipart/form-data with `file` + `source`; for URLs send this JSON.
| Name | Type | Required | Description |
|---|---|---|---|
source | "csv" | "xlsx" | "gsheet" | "feed_google" | yes | |
url | string | null | no | Google Sheets or feed URL.max length 2048 |
mapping | map<string, string> | no | Column -> product field, e.g. {"Product name": "name.ar", "Price": "price", "Colour": "attributes.Color", "Notes": "ignore"}. Columns without a mapping are matched by name. |
dry_run | boolean | no | default false |
locale | string | null | no | Language of untagged text (a plain `name` column, feed titles). Default: the store's default language.pattern ^[a-z]{2}$ |
repeat | "hourly" | "daily" | null | no | URL imports only: run the same import again every hour or every day. |
Body_imports_upload
| Name | Type | Required | Description |
|---|---|---|---|
file | string | yes | |
source | "csv" | "xlsx" | "gsheet" | "feed_google" | yes | |
dry_run | boolean | no | default false |
mapping | string | null | no | JSON object, column -> product field (see ImportCreate).max length 20000 |
locale | string | null | no | pattern ^[a-z]{2}$ |
ImportUpdate
Change a repeating URL import. `repeat: null` stops it.
| Name | Type | Required | Description |
|---|---|---|---|
repeat | "hourly" | "daily" | null | no |