Sync your catalogue every night
Send your products in batches or from one file, read what changed since the last run and report the run.
You end up with a nightly job that sends your catalogue to us, reads back what changed and tells us the run went well. Every call is safe to repeat, so a run that stops halfway can start again.
Send products in batches
POST/api/v1/productsproducts:writeSend up to 50 products in one request as { "products": [...] }. A new article is created and a known one is updated. Sending the same product again is safe: it answers unchanged and writes nothing.
curl -sS https://platform.charpstar.co/api/v1/products \
-H "Authorization: Bearer $CHARPSTAR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "products": [
{ "articleId": "CH-1001", "name": "Oslo lounge chair" },
{ "articleId": "CH-1002", "name": "Oslo side table" }
] }'The answer has one entry per product in results, each with its own httpStatus:
{
"results": [
{ "articleId": "CH-1001", "result": "unchanged", "status": "received", "httpStatus": 200 },
{ "articleId": "CH-1002", "result": "created", "status": "received", "httpStatus": 201 }
]
}Or load one file with an import
For a first load or a full refresh, load one file instead. Check it first with a dry run: the whole file is checked and nothing is written.
POST/api/v1/importsproducts:writecurl -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 }'The file holds up to 100,000 products. When the dry run looks right, start the import itself. It runs in the background:
const res = await fetch(`https://platform.charpstar.co/api/v1/imports`, {
method: "POST",
headers: { Authorization: `Bearer ${process.env.CHARPSTAR_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({ fileUrl: "https://example.com/exports/catalogue.ndjson", format: "ndjson" }),
});
const { id } = await res.json(); // 202: it runs in the backgroundcurl -sS https://platform.charpstar.co/api/v1/imports/$IMPORT_ID \
-H "Authorization: Bearer $CHARPSTAR_API_KEY"Once the import has finished, read one result per row:
curl -sS https://platform.charpstar.co/api/v1/imports/$IMPORT_ID/results \
-H "Authorization: Bearer $CHARPSTAR_API_KEY"Before it has finished, this answers 409 not_ready. import.completed is sent when the import has finished.
Read what changed since the last run
GET/api/v1/assetsassets:readStore the time of your last read. since returns every article that changed after it, oldest change first, 100 a page. Keep calling with cursor set to nextCursor until it is null. A product can appear in two runs in a row, so write its current state, keyed on articleId.
curl -sS "https://platform.charpstar.co/api/v1/assets?articles=CH-1001,CH-1002" \
-H "Authorization: Bearer $CHARPSTAR_API_KEY"
curl -sS "https://platform.charpstar.co/api/v1/assets?since=2026-10-20T00:00:00Z" \
-H "Authorization: Bearer $CHARPSTAR_API_KEY"Report the run
POST/api/v1/integration/heartbeatproducts:writeTell us after each scheduled run. Your CharpstAR contact then sees when your system last synced and whether it went well. This is optional.
curl -sS https://platform.charpstar.co/api/v1/integration/heartbeat \
-H "Authorization: Bearer $CHARPSTAR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "displayName": "Nightly catalogue sync", "run": { "startedAt": "2026-10-20T02:00:00Z", "read": 412, "sent": 12, "writtenBack": 3, "errors": [] } }'