Reference
Carts
Your shoppers' carts, so Uncart can remind a shopper who said yes about the cart they left. Report every change; Uncart keeps only the carts of shoppers who linked theirs with `<uncart-send-basket>` and said yes to basket reminders.
Report a cart
PUT /v1/carts/{cart_id}
A secret key with the carts:write scope. See scopes.
Tells Uncart what a cart holds now, whole: send it whenever a shopper changes their cart (an empty lines when they empty it). Uncart names each line as your synced catalogue of the key's mode states it now (title and price from there, never from you) and leaves out what it cannot state, naming it back in dropped.
Uncart keeps a cart only for a shopper who linked it to themselves with <uncart-send-basket> and said yes to basket reminders on WhatsApp in Uncart's words, with no STOP since. For anyone else nothing about the cart is kept. The answer is the same either way: it never tells you who said yes. A kept cart gets one reminder at most, after the shopper left it for an hour, unless an order closes it first (send cart_id with the order). Nothing is sent before your shop is live.
In test mode the cart is checked against your test catalogue and answered the same way, and nothing is kept.
Parameters
| Field | Type | Required | What it is |
|---|---|---|---|
cart_id | string, in the path | Required | |
Idempotency-Key | string, in the header | Optional | A value you choose (a UUID) that makes this write safe to send again: for 24 hours the same key answers the first answer and does nothing twice. 1 to 255 visible ASCII characters. Required on every POST. |
Request body
| Field | Type | Required | What it is |
|---|---|---|---|
currency | string | Required | An ISO 4217 currency code (EUR), only one that names money: never a precious metal, drawing right, bond-market unit, the testing code or "no currency" (XAU, XAG, XPT, XPD, XDR, XBA to XBD, XSU, XUA, XTS, XXX), and never a code ISO 4217 does not list. |
lines | array of object | Required | Every line of the cart now (up to 50): a report replaces the last one. No lines: the cart is empty. |
lines[].product_id | string | Required | Your own id of the product: 1 to 64 letters, digits, - and _. |
lines[].variant_id | string | Required | Your own id of the variant: 1 to 64 letters, digits, - and _, once per shop and mode. |
lines[].quantity | integer | Required | |
updated_at | string (date-time) | Required | A time with its offset (RFC 3339): 2026-10-27T08:15:00Z. A time after now is taken as now. |
basket_url | string (uri) | Optional | The cart's own page in your shop, which brings this basket back: https on one of your verified domains, with a path and no query or fragment, as Rule L takes it (a page it refuses is 422 naming /basket_url). A reminder's Uncart link leads there, and so does the basket a shopper asked for with <uncart-send-basket>. Without it no reminder is scheduled for the cart, and the answer's reminders says no_basket_url. Send it with every report. |
Answers
| Status | When |
|---|---|
200 | The cart as Uncart states it (whether it was kept or not). |
400 | The request is not as documented: unreadable JSON, a header that is not as documented, or a POST without an Idempotency-Key. More |
401 | No valid API key. Every refusal of a key (missing, malformed, unknown, revoked, expired, the wrong mode or a missing scope) gets this same answer, so it tells nobody why. More |
403 | The key is valid, but its shop does not connect through the Uncart API. More |
404 | Nothing is at this address, or the shop has no such object. More |
409 | A request with this Idempotency-Key is still being handled. Try again after Retry-After seconds. More |
413 | The body is over 1 MB. More |
415 | A body was sent that is not application/json. More |
422 | The body or the query breaks the schema or Uncart's rules (details names each field and rule, never a value), or this Idempotency-Key was used for another request. More |
429 | Too many requests. Try again after Retry-After seconds. Each key may make requests_per_second (bursts of burst), and each shop, all its keys together, shop_requests_per_second (bursts of shop_burst); the RateLimit headers say what is left of the nearer limit. These are counted in each of Uncart's API tasks (one, and two for a few minutes while Uncart deploys; a deploy starts every count afresh). In front of them, all of the Uncart API's clients together may make gateway_requests_per_second (bursts of gateway_burst): past that, Uncart's gateway itself answers 429 with {"message":"Too Many Requests"}, without the RateLimit headers. Treat that 429 the same way. More |
500 | Something went wrong on Uncart's side. Nothing the request did is kept, nor its answer: send the same request again, with the same Idempotency-Key, and it runs once. More |
503 | Uncart cannot check API keys at this moment. Nothing was done; try again after Retry-After seconds. More |
Example
curl 'https://api.uncart.ai/v1/carts/cart-7f3a91' \
-X PUT \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"currency": "EUR",
"lines": [
{
"product_id": "trail-schuh-1",
"variant_id": "trail-schuh-1-42",
"quantity": 1
},
{
"product_id": "trail-schuh-1",
"variant_id": "trail-schuh-1-42",
"quantity": 1
},
{
"product_id": "trail-schuh-1",
"variant_id": "gibt-es-nicht",
"quantity": 1
}
],
"updated_at": "2026-10-27T08:15:00Z",
"basket_url": "https://shop.example.com/warenkorb/7f3a91"
}'
{
"id": "cart-7f3a91",
"currency": "EUR",
"lines": [
{
"product_id": "trail-schuh-1",
"variant_id": "trail-schuh-1-42",
"quantity": 2,
"title": "Trailschuh Kante",
"price": "129.90"
}
],
"dropped": [
{
"product_id": "trail-schuh-1",
"variant_id": "gibt-es-nicht",
"problem": "not_in_catalogue"
}
],
"reminders": "possible"
}
curl 'https://api.uncart.ai/v1/carts/cart-7f3a91' \
-X PUT \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"currency": "EUR",
"lines": [],
"updated_at": "2026-10-27T08:20:00Z",
"basket_url": "https://shop.example.com/warenkorb/7f3a91"
}'
{
"id": "cart-7f3a91",
"currency": "EUR",
"lines": [],
"dropped": [],
"reminders": "possible"
}