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

FieldTypeRequiredWhat it is
cart_idstring, in the pathRequired
Idempotency-Keystring, in the headerOptionalA 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

FieldTypeRequiredWhat it is
currencystringRequiredAn 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.
linesarray of objectRequiredEvery line of the cart now (up to 50): a report replaces the last one. No lines: the cart is empty.
lines[].product_idstringRequiredYour own id of the product: 1 to 64 letters, digits, - and _.
lines[].variant_idstringRequiredYour own id of the variant: 1 to 64 letters, digits, - and _, once per shop and mode.
lines[].quantityintegerRequired
updated_atstring (date-time)RequiredA time with its offset (RFC 3339): 2026-10-27T08:15:00Z. A time after now is taken as now.
basket_urlstring (uri)OptionalThe 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

StatusWhen
200The cart as Uncart states it (whether it was kept or not).
400The request is not as documented: unreadable JSON, a header that is not as documented, or a POST without an Idempotency-Key. More
401No 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
403The key is valid, but its shop does not connect through the Uncart API. More
404Nothing is at this address, or the shop has no such object. More
409A request with this Idempotency-Key is still being handled. Try again after Retry-After seconds. More
413The body is over 1 MB. More
415A body was sent that is not application/json. More
422The 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
429Too 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
500Something 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
503Uncart cannot check API keys at this moment. Nothing was done; try again after Retry-After seconds. More

Example

ShellRequest
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"
}'
JSONAnswer 200
{
  "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"
}
ShellRequest: empty
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"
}'
JSONAnswer 200
{
  "id": "cart-7f3a91",
  "currency": "EUR",
  "lines": [],
  "dropped": [],
  "reminders": "possible"
}