Skip to Content

Load many products from a file

Needs the scope products:write

Load many products from one file, for a first catalogue load or a full refresh.

  • The file is NDJSON (one product per line in the POST /api/v1/products format) or CSV with the same field names in the header row, up to 100,000 products, fetched from an https link.
  • The import runs in the background and applies the same rules as POST /api/v1/products. import.completed is sent when it has finished.
  • With dryRun the whole file is checked and nothing is written.

Header Parameters

Idempotency-Key?string

A unique value such as a UUID. A retry with the same key within 24 hours returns the original answer and runs nothing twice; the same key with a different body is refused with 409 idempotency_conflict.

Lengthlength <= 128

Request Body

application/json
  1. body
fileUrl*string

An https link we can fetch, to an NDJSON or CSV file of products in the POST /products format.

Match^https:\/\/\S+$
Lengthlength <= 2000
format*string

NDJSON: one product per line. CSV: the field names in the header row; dimensionsCm as dimensionsCm.w, dimensionsCm.h, dimensionsCm.d.

Value in"ndjson""csv"
dryRun?boolean

true checks the whole file and reports the outcome without writing anything.

Response Body

Accepted

application/json
  1. response
id*string
Formatuuid
status*string
Value in"queued""running""completed""failed"
dryRun*boolean
orderId*|

The order the imported products landed in (null for a dry run).

rows*|

Rows in the file, once read.

processed*integer
counts*

How many rows ended in each result so far.

error*|

Why the import failed, when it did.

createdAt*string
Formatdate-time
finishedAt*|null
Example Request
curl -sS -X POST https://platform.charpstar.co/api/v1/imports \  -H "Authorization: Bearer $CHARPSTAR_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "fileUrl": "https://example.com/exports/catalogue.ndjson", "format": "ndjson", "dryRun": true }'
Example Response
{  "id": "7a6b5c4d-0000-4000-8000-000000000022",  "status": "queued",  "dryRun": false,  "orderId": null,  "rows": null,  "processed": 0,  "counts": {    "created": 0,    "updated": 0,    "unchanged": 0,    "change_request": 0,    "exists_delivered": 0,    "refused": 0  },  "error": null,  "createdAt": "2026-10-20T09:31:00.000Z",  "finishedAt": null}