Reference

API reference

Every route of the Uncart API, version 1.0.0. The reference is drawn from the API’s own OpenAPI spec, and every example on it is run against the API by its tests.

Shop

The shop a key belongs to, and the domains Uncart may link to.

RouteWhat it does
GET /v1/shopThe shop of this key
GET /v1/domainsThe shop's domains

Catalogue

Your products, their variants and their stock, so the assistant answers from them. A test key works on its own test catalogue; the assistant reads the live one.

RouteWhat it does
GET /v1/productsList products
GET /v1/products/{product_id}Get a product
PUT /v1/products/{product_id}Create or replace a product
DELETE /v1/products/{product_id}Delete a product
POST /v1/inventorySet stock

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 POSTs 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.

RouteWhat it does
GET /v1/storefront/configThe web components' settings
POST /v1/storefront/optin-linksA link for the opt-in
POST /v1/storefront/ask-linksA link to ask the shop
POST /v1/storefront/basket-linksA link to send the basket

Carts

Your shoppers' carts, so Uncart can remind a shopper who said yes about the cart they left. Report every change; Uncart keeps only the carts of shoppers who linked theirs with <uncart-send-basket> and said yes to basket reminders.

RouteWhat it does
PUT /v1/carts/{cart_id}Report a cart

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.

RouteWhat it does
POST /v1/ordersReport an order
POST /v1/test-linksStart the round trip with a test link
POST /v1/orders/{order_id}/refundsReport a refund or a cancellation

Webhooks

Where Uncart tells your system what happened on its side: an order billed on an Uncart link, a refund taken off one, your shop's go-live changed, a test. One endpoint per mode, on a verified domain. Every delivery is signed with your shop's signing secret (Uncart-Signature), and every event has an id to drop repeats by. The webhooks guide shows how to check a signature.

RouteWhat it does
GET /v1/webhook-endpointGet your webhook endpoint
PUT /v1/webhook-endpointSet your webhook endpoint
DELETE /v1/webhook-endpointRemove your webhook endpoint
POST /v1/webhook-endpoint/testSend a test event

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.

RouteWhat it does
GET /v1/discount-codesSee your discount pool
POST /v1/discount-codesAdd discount codes