Reference

Discounts

Your own single-use codes, which Uncart gives to the shoppers who join your deals on WhatsApp: one code each, the one ending first. You make the codes in your system and add them here; Uncart keeps each one sealed until it gives it. An order carrying a code Uncart gave is never billed. A test key's codes are a pool of their own and never reach a shopper.

See your discount pool

GET /v1/discount-codes

A secret key with the discounts:write scope. See scopes.

How many of your codes Uncart may still give in the key's mode, how many it gave and how many ended, and when the next one ends. A test key sees the test pool, whose codes are never given to a shopper.

Answers

StatusWhen
200Your pool in the key's mode.
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
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/discount-codes' \
  -H "Authorization: Bearer $UNCART_KEY"
JSONAnswer 200
{
  "mode": "test",
  "available": 2,
  "handed_out": 0,
  "ended": 0,
  "next_end": "2026-12-31T23:00:00.000Z",
  "low": true,
  "low_at": 20
}

Add discount codes

POST /v1/discount-codes

A secret key with the discounts:write scope. See scopes.

Adds single-use codes you made in your system to the pool of the key's mode. Welcome codes for shops on the Uncart API come later: until then, Uncart gives none of these codes. Once it does, it gives one live code to each shopper who joins your deals on WhatsApp, the one ending first with more than 7 days left, and tells them its percent. Only the first order carrying a code Uncart gave is never billed; a later order carrying the same code is. Uncart keeps each code sealed with your shop's own key until it gives it, and never shows a code again. A code Uncart gave before is refused if you add it again. A pool holds at most 10,000 codes not given yet per mode, ended ones included until Uncart forgets them at their end.

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
percentintegerRequiredWhat each of these codes takes off an order, in percent, as you set them up in your system. Uncart tells the shopper this number.
expires_atstring (date-time)RequiredWhen these codes stop working in your system (RFC 3339, with its offset): more than 7 days on, so a code Uncart gives always has that long left, and at most 366 days on (too_soon and date refuse an end outside those). Uncart gives no code within 7 days of its end.
codesarray of stringRequiredSingle-use codes you made in your system, at most 500 per request. A code already in the pool is counted, not added again; the same code twice in one request is refused, and so is a live code Uncart gave a shopper before (already_given). Letter case does not tell two codes apart.

Answers

StatusWhen
200The codes added, and the pool now.
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/discount-codes' \
  -X POST \
  -H "Authorization: Bearer $UNCART_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "percent": 10,
  "expires_at": "2026-12-31T23:00:00Z",
  "codes": [
    "LAUF-7Q2M-9KX4",
    "LAUF-3H8D-2VNP",
    "LAUF-5TRW-8YCE"
  ]
}'
JSONAnswer 200
{
  "added": 3,
  "already_in_pool": 0,
  "pool": {
    "mode": "test",
    "available": 5,
    "handed_out": 0,
    "ended": 0,
    "next_end": "2026-12-31T23:00:00.000Z",
    "low": true,
    "low_at": 20
  }
}
ShellRequest: repeated
curl 'https://api.uncart.ai/v1/discount-codes' \
  -X POST \
  -H "Authorization: Bearer $UNCART_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "percent": 10,
  "expires_at": "2026-12-31T23:00:00Z",
  "codes": [
    "LAUF-7Q2M-9KX4",
    "lauf-7q2m-9kx4"
  ]
}'
JSONAnswer 422
{
  "error": "validation_failed",
  "message": "The request does not match the schema.",
  "request_id": "req_00000000000000000000000000000000",
  "details": [
    {
      "field": "/codes/1",
      "problem": "repeated"
    }
  ]
}
ShellRequest: validation_failed
curl 'https://api.uncart.ai/v1/discount-codes' \
  -X POST \
  -H "Authorization: Bearer $UNCART_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "percent": 10,
  "expires_at": "2026-12-31T23:00:00Z",
  "codes": [
    "LAUF-7Q2M-9KX4",
    "LAUF-3H8D-2VNP",
    "LAUF-5TRW-8YCE"
  ]
}'
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/discount-codes' \
  -X POST \
  -H "Authorization: Bearer $UNCART_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "percent": 10,
  "expires_at": "2026-12-31T23:00:00Z",
  "codes": [
    "LAUF-7Q2M-9KX4",
    "LAUF-3H8D-2VNP",
    "LAUF-5TRW-8YCE"
  ]
}'
JSONAnswer 422
{
  "error": "idempotency_key_reused",
  "message": "This Idempotency-Key was used for a different request.",
  "request_id": "req_00000000000000000000000000000000"
}