Reference
Storefront
What Uncart's web components (`<uncart-optin>`, `<uncart-ask>`, `<uncart-send-basket>`) call from your shop's own pages, with your publishable key. You rarely call these yourself: the components do. - **The page.** A request must come from a page on one of the shop's verified domains, exactly (`https://`, no port, no subdomain): its `Origin` names it. Any other page, or none, gets `403 origin_not_allowed`, and nothing is done. Browsers' preflight requests are answered for these endpoints only; answers name the page's own address in `Access-Control-Allow-Origin`, never `*`, and allow no credentials. - **Limits.** Each requester (the address the request came from; an IPv6 network as one) has a limit of its own for these endpoints, checked before the key: a burst of 50, refilled at 5 a second. Your publishable keys then count against their own limits and a storefront limit of the shop's own, never the limits your secret keys share, so a busy or flooded page cannot slow your catalogue sync. - **What the page check is, and is not.** The `Origin` check stops other websites' pages from using your key in a shopper's browser. It is no protection against a server, which can send any `Origin`: your publishable key is public by design, so what protects your shop is that it opens only these endpoints, that each component works only while you switch it on, and that nothing happens for a shopper until they send their own WhatsApp message. - **No Idempotency-Key.** A tap is never sent twice by the components, and nothing is kept for one: these `POST`s take no `Idempotency-Key`. - **Each component has its own switch**, off until you switch it on (dashboard, Shop setup, Connection). A component also needs a WhatsApp number to open. With a live key, nothing is offered until your shop is live. A component that is not offered answers `404 feature_off`. - **The links.** Each tap gets a `https://wa.me/...` link with the shopper's ready-made message, in Uncart's checked words: the opt-in is the shopper's own yes when they send it; the other two are requests, never a yes. Products and variants are named as your synced catalogue (of the key's mode) names them. - **Test mode.** A publishable test key gets the same links, but the reference in the message is `Ref TEST` and Uncart keeps nothing: no reference, no count, no yes. - **Not offered yet: `<uncart-back-in-stock>` and `<uncart-price-drop>`.** Their one message is sent when your stock or price changes, and the Uncart API does not carry those changes to Uncart yet. Until it does, the configuration answers `backInStock: false` and `priceDrop: false`, and these two components stay hidden.
Laufkontor Brandt is a sample shop. The examples show sample data.
The web components' settings
GET /v1/storefront/config
A publishable key with the storefront scope. See scopes.
What the web components draw with: the shop's name, its form of address in German, whether the key is a test key, and which components the shop offers now (each one's own switch, switched on on the dashboard; a WhatsApp number to open; with a live key, a shop that is live). Back in stock and price drops are not offered yet: their messages wait for stock and price changes, which the Uncart API does not carry yet. Called with the publishable key from a page on one of the shop's verified domains; it counts against the limits the Storefront section describes.
Answers
| Status | When |
|---|---|
200 | The settings. |
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, or the page's address (Origin) is not on one of the shop's verified domains. More |
422 | The body or the query does not match the schema. details names each field and the rule it broke, at most 10, never its value; never a name you chose either (an unknown property is named by its parent, an unknown query parameter as query, and a step of a field's path that is no name of the spec is *). 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/storefront/config' \
-H "Authorization: Bearer $UNCART_KEY"
{
"shopName": "Laufkontor Brandt",
"tone": "du",
"testMode": true,
"features": {
"optin": true,
"ask": true,
"sendBasket": true,
"backInStock": false,
"priceDrop": false
}
}
A link for the opt-in
POST /v1/storefront/optin-links
A publishable key with the storefront scope. See scopes.
<uncart-optin>: a link whose ready-made message is the shopper's own yes to stay in touch with the shop via Uncart on WhatsApp (basket reminders, and news and offers), in Uncart's words whatever number it goes to. Sending it is the yes; Uncart records it with the component's wording version. Offered while the shop has switched the opt-in on. Called with the publishable key from a page on one of the shop's verified domains; it takes no Idempotency-Key. Each requester (by a fingerprint of its address, never kept as such) has a limit of its own at the door, before the key is checked: a burst of 50, refilled at 5 a second, in either mode. The page's requests then count against the key's limits and the shop's storefront limit, which is its own: your pages never use up your secret keys' limits. Each requester's links also count against Uncart's limits for a shop's pages. Past any of them, 429 rate_limited with Retry-After. With a test key the message names Ref TEST and Uncart keeps nothing.
Request body
| Field | Type | Required | What it is |
|---|---|---|---|
wordingVersion | string: "components-optin-stay-in-touch-2026-10-v2-uncart", "components-optin-stay-in-touch-2026-10-v2-uncart_sie" | Required | The version of the words the component showed (the one permission on Uncart's number); _sie is German Sie, in German only. The component sends it; Uncart records it with the shopper's message. |
locale | string: "en", "de" | Required | The page's language, as the component reads it: German (de) or English (en). |
Answers
| Status | When |
|---|---|
200 | The link for this tap. |
400 | The body is not JSON. 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, or the page's address (Origin) is not on one of the shop's verified domains. More |
404 | The shop does not offer this web component now (see feature_off). 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 does not match the schema. details names each field and the rule it broke, at most 10, never its value; never a name you chose either (an unknown property is named by its parent, an unknown query parameter as query, and a step of a field's path that is no name of the spec is *). 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/storefront/optin-links' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"wordingVersion": "components-optin-stay-in-touch-2026-10-v2-uncart",
"locale": "de"
}'
{
"link": "https://wa.me/493000000099?text=Hallo%20Uncart%2C%20ich%20m%C3%B6chte%20mit%20Laufkontor%20Brandt%20%C3%BCber%20Uncart%20auf%20WhatsApp%20in%20Kontakt%20bleiben%3A%20Erinnerungen%20an%20meinen%20Warenkorb%20sowie%20Neuigkeiten%20und%20Angebote.%20Ich%20kann%20jederzeit%20mit%20STOP%20antworten.%20Ref%20TEST"
}
curl 'https://api.uncart.ai/v1/storefront/optin-links' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"wordingVersion": "components-optin-stay-in-touch-2026-10-v2-uncart",
"locale": "en"
}'
{
"link": "https://wa.me/493000000099?text=Hi%20Uncart%2C%20I%20would%20like%20to%20stay%20in%20touch%20with%20Laufkontor%20Brandt%20via%20Uncart%20on%20WhatsApp%3A%20reminders%20about%20my%20basket%2C%20and%20news%20and%20offers.%20I%20can%20reply%20STOP%20at%20any%20time.%20Ref%20TEST"
}
curl 'https://api.uncart.ai/v1/storefront/optin-links' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"wordingVersion": "components-optin-stay-in-touch-2026-10-v2-uncart_sie",
"locale": "de"
}'
{
"link": "https://wa.me/493000000099?text=Guten%20Tag%20Uncart%2C%20ich%20m%C3%B6chte%20mit%20Laufkontor%20Brandt%20%C3%BCber%20Uncart%20auf%20WhatsApp%20in%20Kontakt%20bleiben%3A%20Erinnerungen%20an%20meinen%20Warenkorb%20sowie%20Neuigkeiten%20und%20Angebote.%20Ich%20kann%20jederzeit%20mit%20STOP%20antworten.%20Ref%20TEST"
}
A link to ask the shop
POST /v1/storefront/ask-links
A publishable key with the storefront scope. See scopes.
<uncart-ask>: a link whose ready-made message is the shopper's question about a product (named as your synced catalogue names it), or, without a product, a plain question to the shop. A variant is taken only with its product: a variantId alone is 422 validation_failed. A question, never a yes. Offered while the shop has switched "Ask us" on. Called with the publishable key from a page on one of the shop's verified domains; it takes no Idempotency-Key. Each requester (by a fingerprint of its address, never kept as such) has a limit of its own at the door, before the key is checked: a burst of 50, refilled at 5 a second, in either mode. The page's requests then count against the key's limits and the shop's storefront limit, which is its own: your pages never use up your secret keys' limits. Each requester's links also count against Uncart's limits for a shop's pages. Past any of them, 429 rate_limited with Retry-After. With a test key the message names Ref TEST and Uncart keeps nothing.
Request body
| Field | Type | Required | What it is |
|---|---|---|---|
wordingVersion | string: "components-ask-us-2026-10-v1-uncart", "components-ask-us-2026-10-v1-uncart_sie" | Required | The version of the words the component showed ("Ask us"); _sie is German Sie, in German only. The component sends it; Uncart records it with the shopper's message. |
locale | string: "en", "de" | Required | The page's language, as the component reads it: German (de) or English (en). |
productId | string | Optional | A product's or variant's id as the page names it (the component's own check); Uncart looks it up in your synced catalogue of the key's mode. |
variantId | string | Optional | A product's or variant's id as the page names it (the component's own check); Uncart looks it up in your synced catalogue of the key's mode. |
Answers
| Status | When |
|---|---|
200 | The link for this tap. |
400 | The body is not JSON. 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, or the page's address (Origin) is not on one of the shop's verified domains. More |
404 | The shop does not offer this component now (feature_off), or your synced catalogue of the key's mode holds no active product, or no variant of it, with this id (not_found). |
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 does not match the schema. details names each field and the rule it broke, at most 10, never its value; never a name you chose either (an unknown property is named by its parent, an unknown query parameter as query, and a step of a field's path that is no name of the spec is *). 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/storefront/ask-links' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"wordingVersion": "components-ask-us-2026-10-v1-uncart",
"locale": "de",
"productId": "trail-schuh-1",
"variantId": "trail-schuh-1-42"
}'
{
"link": "https://wa.me/493000000099?text=Hallo%2C%20ich%20habe%20eine%20Frage%20zu%20Trailschuh%20Kante%20(Ref%20TEST)"
}
curl 'https://api.uncart.ai/v1/storefront/ask-links' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"wordingVersion": "components-ask-us-2026-10-v1-uncart",
"locale": "en"
}'
{
"link": "https://wa.me/493000000099?text=Hi%20Uncart%2C%20I%20have%20a%20question%20for%20Laufkontor%20Brandt."
}
curl 'https://api.uncart.ai/v1/storefront/ask-links' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"wordingVersion": "components-ask-us-2026-10-v1-uncart",
"locale": "de",
"productId": "gibt-es-nicht"
}'
{
"error": "not_found",
"message": "No product or variant with this id.",
"request_id": "req_00000000000000000000000000000000"
}
curl 'https://api.uncart.ai/v1/storefront/ask-links' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"wordingVersion": "components-ask-us-2026-10-v1-uncart",
"locale": "de",
"productId": "trail-schuh-1",
"variantId": "trail-schuh-1-42"
}'
{
"error": "feature_off",
"message": "This shop has this feature switched off in Uncart.",
"request_id": "req_00000000000000000000000000000000"
}
A link to send the basket
POST /v1/storefront/basket-links
A publishable key with the storefront scope. See scopes.
<uncart-send-basket>: a link whose ready-made message asks the shop for the shopper's basket, named by the SHA-256 of your cart's id. A request, never a yes. Offered while the shop has switched the basket button on. Called with the publishable key from a page on one of the shop's verified domains; it takes no Idempotency-Key. Each requester (by a fingerprint of its address, never kept as such) has a limit of its own at the door, before the key is checked: a burst of 50, refilled at 5 a second, in either mode. The page's requests then count against the key's limits and the shop's storefront limit, which is its own: your pages never use up your secret keys' limits. Each requester's links also count against Uncart's limits for a shop's pages. Past any of them, 429 rate_limited with Retry-After. With a test key the message names Ref TEST and Uncart keeps nothing.
Request body
| Field | Type | Required | What it is |
|---|---|---|---|
wordingVersion | string: "components-basket-button-2026-10-v1-uncart", "components-basket-button-2026-10-v1-uncart_sie" | Required | The version of the words the component showed (the basket button); _sie is German Sie, in German only. The component sends it; Uncart records it with the shopper's message. |
locale | string: "en", "de" | Required | The page's language, as the component reads it: German (de) or English (en). |
cartRef | string | Required | Your cart, named by the lower-case hex SHA-256 of its id; never the id itself. |
Answers
| Status | When |
|---|---|
200 | The link for this tap. |
400 | The body is not JSON. 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, or the page's address (Origin) is not on one of the shop's verified domains. More |
404 | The shop does not offer this web component now (see feature_off). 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 does not match the schema. details names each field and the rule it broke, at most 10, never its value; never a name you chose either (an unknown property is named by its parent, an unknown query parameter as query, and a step of a field's path that is no name of the spec is *). 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/storefront/basket-links' \
-X POST \
-H "Authorization: Bearer $UNCART_KEY" \
-H 'Content-Type: application/json' \
-d '{
"wordingVersion": "components-basket-button-2026-10-v1-uncart",
"locale": "de",
"cartRef": "3a6eb0790f39ac87c94f3856b2dd2c5d110e6811602261a9a923d3bb23adc8b7"
}'
{
"link": "https://wa.me/493000000099?text=Hallo%20Uncart%2C%20bitte%20schick%20mir%20meinen%20Warenkorb%20von%20Laufkontor%20Brandt.%20(Ref%20TEST)"
}