Reference
Orders
Your orders, their refunds and cancellations: what closes a cart, what Uncart bills on (an order within 3 days after a tap on an Uncart link), and what keeps your shop live. Report every order with the click id you kept from the visit.
Report an order
POST /v1/orders
A secret key with the orders:write scope. See scopes.
Tells Uncart about an order the moment it is placed: every order, whether or not it came through Uncart. Uncart closes the cart it names (no reminder about it is sent) and matches its click id to your Uncart links. An order placed within 3 days after a tap on an Uncart link is billed on that link, once (15% of value; the same as Shopify shops). Send the click id you kept from the visit; an order without one is still reported.
Your order reports keep your shop live: once it is, Uncart pauses sending by itself if order reports stop, or fall far below the taps on your links, and shows you why on the dashboard (Home, "Needs you").
The same order sent again is billed once. In test mode the order is checked and answered, and nothing is kept or billed.
Parameters
| Field | Type | Required | What it is |
|---|---|---|---|
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 |
|---|---|---|---|
id | string | Required | Your own id of the order: 1 to 64 letters, digits, ., _, : and -, once per shop and mode. |
placed_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. |
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. |
total | string | Required | A decimal amount in the currency, exact: at most as many decimals as the currency has (EUR 2, JPY 0, KWD 3). Never rounded: more decimals are refused. |
value | string | Required | A decimal amount in the currency, exact: at most as many decimals as the currency has (EUR 2, JPY 0, KWD 3). Never rounded: more decimals are refused. |
click_id | string | Optional | Uncart's click id: the value of uc_click in the address the shopper arrived at from an Uncart link (43 letters, digits, - and _). Keep it with the visit and send it with the order. Keeping it in the shopper's browser needs their consent; without it, send the one in the address of the page where the order was placed. |
discount_codes | array of string | Optional | The codes the shopper entered on the order, as your shop received them. |
cart_id | string | Optional | Your own id of the cart: 1 to 64 letters, digits, ., _, : and -. The same id your pages give <uncart-send-basket>, so Uncart knows which shopper linked it. Make it unguessable (random, never a sequence): a cart stays linked to the first shopper who linked it while that link lasts, and is never handed to another. |
Answers
| Status | When |
|---|---|
200 | What Uncart made of the order's click id. |
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 |
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. |
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/orders' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"id": "order-1001",
"placed_at": "2026-10-27T08:30:00Z",
"currency": "EUR",
"total": "154.90",
"value": "129.90",
"click_id": "Wq3vC4yT9mJbX0kLr2sPdE7uHf1aNg6oZiY5xQwB8cK",
"discount_codes": [],
"cart_id": "cart-7f3a91"
}'
{
"id": "order-1001",
"click_id": "unknown"
}
curl 'https://api.uncart.ai/v1/orders' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"id": "order-1002",
"placed_at": "2026-10-27T08:40:00Z",
"currency": "EUR",
"total": "59.90",
"value": "50.34",
"discount_codes": [
"HERBST10"
]
}'
{
"id": "order-1002",
"click_id": "none"
}
curl 'https://api.uncart.ai/v1/orders' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"id": "order-1003",
"placed_at": "2026-10-27T08:45:00Z",
"currency": "EUR",
"total": "59.90",
"value": "69.90"
}'
{
"error": "validation_failed",
"message": "The request does not match the schema.",
"request_id": "req_00000000000000000000000000000000",
"details": [
{
"field": "/value",
"problem": "above_total"
}
]
}
curl 'https://api.uncart.ai/v1/orders' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"id": "order-1001",
"placed_at": "2026-10-27T08:30:00Z",
"currency": "EUR",
"total": "154.90",
"value": "129.90",
"click_id": "Wq3vC4yT9mJbX0kLr2sPdE7uHf1aNg6oZiY5xQwB8cK",
"discount_codes": [],
"cart_id": "cart-7f3a91"
}'
{
"error": "validation_failed",
"message": "The request does not match the schema.",
"request_id": "req_00000000000000000000000000000000",
"details": [
{
"field": "/url",
"problem": "not_verified"
}
]
}
curl 'https://api.uncart.ai/v1/orders' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"id": "order-1001",
"placed_at": "2026-10-27T08:30:00Z",
"currency": "EUR",
"total": "154.90",
"value": "129.90",
"click_id": "Wq3vC4yT9mJbX0kLr2sPdE7uHf1aNg6oZiY5xQwB8cK",
"discount_codes": [],
"cart_id": "cart-7f3a91"
}'
{
"error": "idempotency_key_reused",
"message": "This Idempotency-Key was used for a different request.",
"request_id": "req_00000000000000000000000000000000"
}
Start the round trip with a test link
POST /v1/test-links
A secret key with the orders:write scope. See scopes.
Makes your shop's test link: an Uncart link to the front page of your first verified domain, or the page path names there (/ for the front page). Your shop sends no WhatsApp messages until it is live: billing connected on the dashboard, and this round trip passed. Open the link on your shop as a shopper would, place a test order, and report it with POST /v1/orders and the click id the visit carried (within 3 days of the tap). That order passes the round trip, and it is never billed. A new test link replaces the last one, and one passes one round trip. Once live, keep reporting every order: if order reports stop, or fall far below the taps on your links, sending pauses by itself, and your dashboard says why under "Needs you"; the next order report (for too few reports: the next order that names an Uncart link), or a new round trip, lifts it. Your live webhook endpoint hears each change (go_live.changed). With a test key the link is a test-mode link to the same page, so you can check that your page keeps the click id; it never starts the round trip.
Parameters
| Field | Type | Required | What it is |
|---|---|---|---|
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 |
|---|---|---|---|
path | string | Required | The page on your first verified domain the link leads to, as a path (/ for the front page). Use the page where your shop keeps the click id from the address. Uncart links only to pages it may: a path it refuses is 422 validation_failed naming /path. |
Answers
| Status | When |
|---|---|
201 | The test link. |
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 |
409 | No test link now (details names why: billing_needed (connect billing on the dashboard first), sending_off (sending is not switched on yet for shops on the Uncart API), currency_unsupported (Uncart bills in euros for now), no_link_address (verify one of your shop's domains first)), or a request with this Idempotency-Key is still being handled. |
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/test-links' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"path": "/"
}'
{
"url": "https://links.uncart.ai/l/QXhLcDBmN2tRbVo1VHdKeTJiTjhjVnJXc0Rn"
}
curl 'https://api.uncart.ai/v1/test-links' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"path": "/"
}'
{
"error": "idempotency_in_progress",
"message": "A request with this Idempotency-Key is still in progress.",
"request_id": "req_00000000000000000000000000000000"
}
Report a refund or a cancellation
POST /v1/orders/{order_id}/refunds
A secret key with the orders:write scope. See scopes.
Tells Uncart about money given back on an order, or the order's cancellation. On an order Uncart billed, the fee follows: a refund in a month already invoiced is credited on the next invoice. Uncart keeps the refund id, its kind, the amounts and the time; nothing else. A refund made more than 30 days after the order changes nothing (the order is final).
In test mode nothing is kept: a test order is never billed.
Parameters
| Field | Type | Required | What it is |
|---|---|---|---|
order_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 |
|---|---|---|---|
id | string | Required | Your own id of the refund (for a cancellation, any id of yours, such as cancelled): once per order. The same id again is the same refund. |
kind | string: "refund", "cancellation" | Required | refund: money given back; cancellation: the order is cancelled (send its total as amount). |
amount | string | Required | A decimal amount in the currency, exact: at most as many decimals as the currency has (EUR 2, JPY 0, KWD 3). Never rounded: more decimals are refused. |
value | string | Optional | A decimal amount in the currency, exact: at most as many decimals as the currency has (EUR 2, JPY 0, KWD 3). Never rounded: more decimals are refused. |
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. |
created_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. |
Answers
| Status | When |
|---|---|
200 | What became of the refund. |
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. |
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/orders/order-1001/refunds' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"id": "refund-1",
"kind": "refund",
"amount": "50.00",
"value": "42.02",
"currency": "EUR",
"created_at": "2026-10-28T10:00:00Z"
}'
{
"order_id": "order-1001",
"id": "refund-1",
"status": "not_credited"
}
curl 'https://api.uncart.ai/v1/orders/order-1001/refunds' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"id": "refund-2",
"kind": "refund",
"amount": "10.00",
"value": "12.00",
"currency": "EUR",
"created_at": "2026-10-28T10:00:00Z"
}'
{
"error": "validation_failed",
"message": "The request does not match the schema.",
"request_id": "req_00000000000000000000000000000000",
"details": [
{
"field": "/value",
"problem": "above_amount"
}
]
}
curl 'https://api.uncart.ai/v1/orders/order-1001/refunds' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"id": "refund-1",
"kind": "refund",
"amount": "50.00",
"value": "42.02",
"currency": "EUR",
"created_at": "2026-10-28T10:00:00Z"
}'
{
"error": "validation_failed",
"message": "The request does not match the schema.",
"request_id": "req_00000000000000000000000000000000",
"details": [
{
"field": "/url",
"problem": "not_verified"
}
]
}
curl 'https://api.uncart.ai/v1/orders/order-1001/refunds' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"id": "refund-1",
"kind": "refund",
"amount": "50.00",
"value": "42.02",
"currency": "EUR",
"created_at": "2026-10-28T10:00:00Z"
}'
{
"error": "idempotency_key_reused",
"message": "This Idempotency-Key was used for a different request.",
"request_id": "req_00000000000000000000000000000000"
}