10 · Auth, idempotency, errors, money and time

Read this once before either site spec. Everything here is from the frozen /v1 contract.

1 · Credentials a storefront uses

Tenant, channel, customer and outlet permissions are never taken from a request body. The channel_id you send is overwritten with the key's own (see "Channel id" below).

Guest token handling (important)

1. The token is in the 201 response of the place call and nowhere else, ever again. A replay of the same place request returns guest_access_token: null.
2. Persist it before you render anything: localStorage key munim.guest.<order_id> (and nothing else about the customer). If the first response is lost (tab closed, network drop) the order exists but this browser can no longer track it. See gaps.md; in the UI say "We couldn't confirm your order on this device. Check with the outlet using your phone number."
3. Never put the token in a URL or analytics event. Send it only as the header.

Channel and brand id

The preview and place payloads require a UUIDv7 channel_id (and device_id: null, external_ref: null). Send the menu's channel_id (the key's channel; core overwrites the field with it anyway). For brand_id, send the items' brand_id when the whole cart is one brand's (menu.brands[] lists the brands selling at the outlet), else null.

2 · Idempotency keys

Writes (POST /v1/storefront/orders, cancel, reschedule) are commands. The command envelope is in the JSON body (there is no Idempotency-Key header):

{ "command_id": "<uuidv7>", "idempotency_key": "<8-100 chars of A-Z a-z 0-9 _ . : ->", "type": "orders.place.v1", "payload": { } }

3 · The error envelope

Every non-2xx response has this body (text is composed by the server from a fixed table, never raw text; show it only as a fallback):

{ "error": { "code": "conflict", "message": "That pickup time just filled up. Please choose another.", "reason_code": "window_full" } }

code is the machine class; reason_code is set when it is one of the named refusals. Always switch on reason_code first, then code, and treat unknown values as generic.

Error code values a storefront can see

Generic fallback copy (D-2 S-err): checkout "Your order was not placed. Please try again."; menu "The menu couldn't load. Please try again."; tracker "Can't load your order right now. It is still placed."

Reason codes a shopper can hit

Copy in "double quotes" is the literal approved text (screen spec O2/O3). {braces} are parameters. A refusal carries its typed params where it has any: beside error in a 409 / 422 body, and on each entry of a preview's refusals[]. params holds ids and server-computed amounts only (never text): line_no, item_id, variant_id, code (the coupon as sent), min_spend_minor, shortfall_minor, old_total_minor, new_total_minor, currency. Each field is present only when the refusal has it. The "Fill from" column says which to use.

{ "error": { "code": "conflict", "message": "Spend a little more to use this coupon.", "reason_code": "coupon_min_spend" },
  "params": { "code": "SPICE10", "min_spend_minor": 30000, "shortfall_minor": 2000, "currency": "INR" } }

A preview refusal is returned inside a 200 response (refusals: [{line_no, reason_code, params?}]), not as an error: render it inline and disable "Place order" until the list is empty.

Not for shoppers (do not special-case): cannot_verify, stale_draft, authority_denied, period_closed, model_blocked and the rest of the member/back-office codes. Unknown code: show error.message.

4 · 404 on a bad key

A missing, wrong or revoked storefront key, a wrong guest token, and an order that is not yours all return 404 not_found, never 401/403 and never a hint which part was wrong. Build one full-page "not found" state ("This link isn't valid.") and use it for any 404 on the first menu/outlets call and on the tracker page.

5 · Rate limits (429 + Retry-After)

core-api limits /v1/cares-network/* to 60 requests a minute per client address and /v1/storefront/cares to 60 a minute per (address, key). Over the limit the response is 429 with a Retry-After header (whole seconds) and the body {"error": {"code": "unavailable", "reason_code": "rate_limited", ...}}. Order and menu routes have no documented limit (gaps G-08), but handle 429 on any call:

// lib/errors.ts (excerpt)
export function retryAfterMs(res: Response, fallbackMs = 2000): number {
  const s = Number(res.headers.get("Retry-After"));
  return Number.isFinite(s) && s > 0 ? Math.min(s, 60) * 1000 : fallbackMs;
}

Wait that long (disable the button, show a countdown), then retry the same request with the same idempotency keys. Don't poll the Cares route faster than once per 5 seconds; fetch it once per page view. The mock never sends a 429.

6 · Money

• Every amount is an integer in minor units (paise, cents) with a separate currency (INR, AUD). Field names end in _minor. Quantities are qty_milli = thousandths (1000 = 1).
• Never compute a total as truth. The only totals on screen are subtotal_minor, discount_minor, tax_minor, total_minor from the preview response (before placing) and from GET /v1/storefront/orders/{id} (after). The server re-derives everything at placement and ignores what you send. Sending client_totals is allowed but pointless: send null.
• A cart badge showing a running sum before any preview is not allowed: show the item count and "Total at checkout" until a preview exists. A line price in the menu is the server's price_minor for display.
• Show a "Preview" label on the checkout price breakdown (the response has label: "preview").
• Format with Intl.NumberFormat using the business's locale (en-IN, en-AU). Dividing by the currency's minor-unit exponent for display only is fine:

// lib/format.ts
export function formatMoney(minor: number, currency: string, locale: string): string {
  const nf = new Intl.NumberFormat(locale, { style: "currency", currency });
  const digits = nf.resolvedOptions().maximumFractionDigits ?? 2;
  return nf.format(minor / 10 ** digits);   // display only; never feed this back into an API call
}

/** "1" for qty_milli 1000, "0.5" for 500. */
export const formatQty = (milli: number): string => String(milli / 1000);

India groups in lakhs (₹1,23,456.00 via en-IN); Australia uses $1,234.50 via en-AU. Negative amounts use the real minus sign: Intl does this for you.

7 · Time zones

• Every instant is ISO-8601 with an offset (2026-10-14T12:30:00+05:30). Every outlet has an IANA tz (Asia/Kolkata, Australia/Melbourne) in GET /v1/storefront/outlets and the state response.
• Render all times in the outlet's zone, not the browser's, even if the shopper travels:

// lib/time.ts
export function formatTime(iso: string, tz: string, locale: string): string {
  return new Intl.DateTimeFormat(locale, { timeZone: tz, hour: "numeric", minute: "2-digit" }).format(new Date(iso));
}
export function formatDay(iso: string, tz: string, locale: string): string {
  return new Intl.DateTimeFormat(locale, { timeZone: tz, weekday: "short", day: "numeric", month: "short" }).format(new Date(iso));
}

• Use one library (Intl) only; never mix date libraries. Never do offset arithmetic by hand. Melbourne changes clocks on 4 Oct 2026 (to AEDT, +11:00): if you ever see +10:00 vs +11:00 offsets in one list, that is correct.
• Deal windows (deals[].windows) are in the outlet's local time (ISO weekday 1 = Monday + local time range; an overnight range wraps past midnight).
• "Ready in about N min" = accepting.default_prep_min + accepting.busy_extra_min (two server fields, shown as returned; busy_extra_min counts only while state === "busy").

8 · Calling the real API from a browser (CORS)

The mock is served by your own site, so it is same-origin. The real core-api answers CORS only on the public browser routes (/v1/storefront/**, /v1/stream, /v1/cares-network/**) and only for the exact origins its operator allows (no *). Send the operator your site's origin (for example https://spice-route.example) before you switch NEXT_PUBLIC_MUNIM_API. Preflights are answered for the headers a storefront sends (X-Munim-Storefront-Key, X-Munim-Guest-Token, Last-Event-ID, Content-Type, Authorization); responses expose X-Munim-Replayed and Retry-After. Credentials are headers, never cookies. An origin that is not allowed gets no CORS headers, so the browser blocks the call: until your origin is on the list, call the real API through your own site (a rewrite or proxy route).