Skip to Content

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:write

Send 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:write
Dry run
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 }'

The file holds up to 100,000 products. When the dry run looks right, start the import itself. It runs in the background:

Start the import
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 background
GET/api/v1/imports/{importId}products:read
curl -sS https://platform.charpstar.co/api/v1/imports/$IMPORT_ID \
  -H "Authorization: Bearer $CHARPSTAR_API_KEY"
GET/api/v1/imports/{importId}/resultsproducts:read

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:read

Store 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:write

Tell 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": [] } }'

On this page