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.
Idempotency-Key?stringA 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.
length <= 128application/json- body
fileUrl*stringAn https link we can fetch, to an NDJSON or CSV file of products in the POST /products format.
^https:\/\/\S+$length <= 2000format*stringNDJSON: one product per line. CSV: the field names in the header row; dimensionsCm as dimensionsCm.w, dimensionsCm.h, dimensionsCm.d.
"ndjson""csv"dryRun?booleantrue checks the whole file and reports the outcome without writing anything.
Accepted
application/json- response
id*stringuuidstatus*string"queued""running""completed""failed"dryRun*booleanorderId*|The order the imported products landed in (null for a dry run).
rows*|Rows in the file, once read.
processed*integercounts*How many rows ended in each result so far.
error*|Why the import failed, when it did.
createdAt*stringdate-timefinishedAt*|nullcurl -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 }'{ "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}