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

StatusWhen
200The settings.
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, or the page's address (Origin) is not on one of the shop's verified domains. More
422The 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
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/storefront/config' \
  -H "Authorization: Bearer $UNCART_KEY"
JSONAnswer 200
{
  "shopName": "Laufkontor Brandt",
  "tone": "du",
  "testMode": true,
  "features": {
    "optin": true,
    "ask": true,
    "sendBasket": true,
    "backInStock": false,
    "priceDrop": false
  }
}