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

FieldTypeRequiredWhat it is
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
idstringRequiredYour own id of the order: 1 to 64 letters, digits, ., _, : and -, once per shop and mode.
placed_atstring (date-time)RequiredA time with its offset (RFC 3339): 2026-10-27T08:15:00Z. A time after now is taken as now.
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.
totalstringRequiredA 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.
valuestringRequiredA 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_idstringOptionalUncart'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_codesarray of stringOptionalThe codes the shopper entered on the order, as your shop received them.
cart_idstringOptionalYour 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

StatusWhen
200What Uncart made of the order's click id.
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
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.
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/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"
}'
JSONAnswer 200
{
  "id": "order-1001",
  "click_id": "unknown"
}
ShellRequest: no_click_id
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"
  ]
}'
JSONAnswer 200
{
  "id": "order-1002",
  "click_id": "none"
}
ShellRequest: value_above_total
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"
}'
JSONAnswer 422
{
  "error": "validation_failed",
  "message": "The request does not match the schema.",
  "request_id": "req_00000000000000000000000000000000",
  "details": [
    {
      "field": "/value",
      "problem": "above_total"
    }
  ]
}
ShellRequest: validation_failed
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"
}'
JSONAnswer 422
{
  "error": "validation_failed",
  "message": "The request does not match the schema.",
  "request_id": "req_00000000000000000000000000000000",
  "details": [
    {
      "field": "/url",
      "problem": "not_verified"
    }
  ]
}
ShellRequest: idempotency_key_reused
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"
}'
JSONAnswer 422
{
  "error": "idempotency_key_reused",
  "message": "This Idempotency-Key was used for a different request.",
  "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

FieldTypeRequiredWhat it is
order_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
idstringRequiredYour 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.
kindstring: "refund", "cancellation"Requiredrefund: money given back; cancellation: the order is cancelled (send its total as amount).
amountstringRequiredA 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.
valuestringOptionalA 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.
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.
created_atstring (date-time)RequiredA time with its offset (RFC 3339): 2026-10-27T08:15:00Z. A time after now is taken as now.

Answers

StatusWhen
200What became of the refund.
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.
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/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"
}'
JSONAnswer 200
{
  "order_id": "order-1001",
  "id": "refund-1",
  "status": "not_credited"
}
ShellRequest: value_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-2",
  "kind": "refund",
  "amount": "10.00",
  "value": "12.00",
  "currency": "EUR",
  "created_at": "2026-10-28T10:00:00Z"
}'
JSONAnswer 422
{
  "error": "validation_failed",
  "message": "The request does not match the schema.",
  "request_id": "req_00000000000000000000000000000000",
  "details": [
    {
      "field": "/value",
      "problem": "above_amount"
    }
  ]
}
ShellRequest: validation_failed
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"
}'
JSONAnswer 422
{
  "error": "validation_failed",
  "message": "The request does not match the schema.",
  "request_id": "req_00000000000000000000000000000000",
  "details": [
    {
      "field": "/url",
      "problem": "not_verified"
    }
  ]
}
ShellRequest: idempotency_key_reused
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"
}'
JSONAnswer 422
{
  "error": "idempotency_key_reused",
  "message": "This Idempotency-Key was used for a different request.",
  "request_id": "req_00000000000000000000000000000000"
}