Skip to Content

Send products

Create or update products by article number, one at a time or in a batch, and read the answer.

Send one product, or { "products": [ ... ] } with up to 50. We match on articleId within your company: a new article is created, a known article is updated.

Create or update a product

POST/api/v1/productsproducts:write

New products go to our production team's intake. They plan, price and schedule them the usual way, and the product shows up in your CharpstAR account as soon as you send it.

Images and 3D files are sent as links, never inside the request. A request body can be up to 4 MB. The reference page lists every field of a product.

curl -sS https://platform.charpstar.co/api/v1/products \
  -H "Authorization: Bearer $CHARPSTAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "articleId": "CH-1001",
    "externalId": "8f2c1a7e-item-guid",
    "name": "Oslo lounge chair",
    "category": "Furniture",
    "subcategory": "Chairs",
    "dimensionsCm": { "w": 72, "h": 81, "d": 78 },
    "variants": [
      { "code": "OAK", "colour": "Oak" },
      { "code": "BLACK", "colour": "Black", "articleId": "CH-1001-B" }
    ],
    "referenceImages": [{ "url": "https://example.com/images/oslo-front.jpg" }],
    "productLink": "https://example.com/products/oslo-lounge-chair",
    "active": true
  }'

To send several products in one call, put them in products:

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

result is one of:

resultHTTPMeaning
created201New product, now in our intake.
updated200Known product; the fields you own were updated.
unchanged200Nothing changed since your last call. Nothing was written.
change_request200Modelling has started and you changed the dimensions or the 3D source file. We hold the change for our production team instead of applying it; the answer lists it in pendingChanges.
exists_delivered200The model is already delivered. We keep the delivered product as it is.
refused400 or 409The product was not accepted. See error.
A new product
{ "articleId": "CH-1001", "result": "created", "status": "received" }

The answer can also carry:

  • status (and statusDetail), the product's status after the call;
  • variantsCreated: variant article numbers that became their own products;
  • warnings: for example, a reference image we could not fetch. The product itself was saved, and we try the image again on your next identical call.
Updated; one variant became its own product
{
  "articleId": "CH-1001",
  "result": "updated",
  "status": "received",
  "variantsCreated": ["CH-1001-B"]
}

A batch answers:

  • { "results": [ ... ] }: one entry per product, in the order you sent them, each with its own httpStatus;
  • HTTP 200 when every product succeeded, 207 when some did and some did not, and the shared status when every product failed the same way.
A batch where every product succeeded
{
  "results": [
    { "articleId": "CH-1001", "result": "unchanged", "status": "received", "httpStatus": 200 },
    { "articleId": "CH-1002", "result": "created", "status": "received", "httpStatus": 201 }
  ]
}

Sending the same product again is safe

We compare what you send with what you sent last time. An identical product answers unchanged and writes nothing.

So you can send your full catalogue on every sync, or retry a call that timed out, without creating duplicates.

If two calls for the same new article arrive at the same moment, one of them may get 409 in_progress with details.retry true. Send it again a few seconds later.

On this page