Appearance
Shop-to-order flow (web)
One journey from the store picker to a paid order. It starts with two calls: the storefront loads its brand key, then selects a hub.
Play the flow
Two paths: a signed-in customer, and a guest, who places the order through a different endpoint and gets a customer token back from it.
shop.example.com/
shop · rewards · scan
choose a store
stock, prices and payment options depend on the store
Mission Stpickup · 0.8 mi›
Delivery to 94105delivery›
Ship anywhereshipment›
Page not designed yet — drawn from what the documented flow requires.
States
What happens to the order after PLACED — fulfilment steps, cancellation, which types can be cancelled when — is the order's own lifecycle, on Orders and checkout.
API calls by stage
| Stage | Action | API call | Access |
|---|---|---|---|
| 1 | Storefront loads | POST /api/v1/tenant | Origin |
| 2 | Choose a store | PUT /api/v1/set-hub — hubId, roomId, type, all required | Origin + Brand key |
| 3 | Browse | GET /api/v1/user/available-catalog · guest: GET /api/v1/available-catalog | Origin + Brand key + Hub selected (+ Customer) |
| 4 | Product page | GET /api/v1/getproduct/:slug | Origin + Brand key |
| 5 | Add to bag, change quantity | PUT /api/v1/user/syncBag · guest: PUT /api/v1/syncBag — the whole bag[] every time | Origin + Brand key + Hub selected (+ Customer) |
| 6 | Create the order | POST /api/v1/user/createOrder · guest: POST /api/v1/user/create-order | Origin + Brand key + Hub selected (+ Customer) |
| 7 | Payment options | GET /api/v1/payment/gateways | Origin + Brand key + Hub selected |
| 8 | Pay | POST /api/v1/user/payment/link/:paymentGatewayId — orderId, currency | Origin + Brand key + Hub selected + Customer |
| 9 | Provider returns | Not a storefront call: the provider redirects to the backend, which updates the order | — |
| 10 | Order page | GET /api/v1/user/order/:orderId | Origin + Customer |
The hosted link is one of several ways to pay. The storefront can instead collect a card or bank token itself and send it to a gateway's own endpoint — Stripe, Square, NMI, Authorize.Net, Apple Pay or AeroPay — each of which moves the order to PLACED on success.
What carries this flow
- The hub key replaces the brand key.
set-hubreturns a newapiKey; send that asapi-keyon every call marked Hub selected. Stock, prices and payment gateways all come from the hub the key carries. syncBagis the whole cart. There is no add-line or get-cart call: send the complete bag, draw what comes back.- The order exists before the money does.
createOrderruns when the customer leaves the details step. A prepaid order with something to pay waits inPAYMENT_PENDINGuntil the provider calls back; the order-placed and payment-pending notifications are sent accordingly. - A guest order returns a customer token.
create-orderreuses a customer matching the email or phone, or creates one, and the response carries a token for that customer. The payment link is customer-only, so a guest pays with that token. - An address is required for every order type except
PICKUP.