End-to-End Integration Flow

This guide maps the full ordering journey to API calls, in the order a storefront makes them. It mirrors the flow used by ShopHero's own ecommerce front-end, so it's a reliable blueprint for integrating KitchenClick ordering into an existing ecommerce experience.

Server-side OAuth

All authenticated calls use the OAuth 2.0 client credentials grant. Keep your client_id/client_secret and the resulting token on your server — never ship them to the browser. Mint a token from Identity, cache it, and refresh on 401. See Authentication.

1. Resolve the store

Start from a concept slug (your storefront's brand) and a location. If you already know the location and concept IDs, you can skip the slug lookup.

Step	Call	Auth
Resolve concept + its locations	GET /v1/ecommerce/concepts/by-slug/{slug}	Public
List concepts at a location	GET /v1/ecommerce/locations/{location}/concepts	Public
Location details (hours, fulfillment options)	GET /v1/ecommerce/locations/{location}	Public

2. Browse the menu

Step	Call	Auth
List menus for a concept	GET .../concepts/{concept}/menus	Public
Menu items + categories	GET .../menus/{menu}/items	Public
Item details + modifiers	GET .../concepts/{concept}/items/{item}	Public
Build-your-own items	GET /v1/ecommerce/items/{item}/configurator	Public

3. Build the cart

The cart is client-side — KitchenClick has no server-side cart. Accumulate items, quantities, and modifier selections in your own session/state. For configurator items, optionally call POST .../configurator/validate to validate a build as the customer makes selections.

4. Checkout

Step	Call	Auth
Scheduling config (lead time, slot rules)	GET .../scheduling-config	Public
Available time slots for a date	GET .../time-slots	Public
Delivery quote (delivery orders only)	POST .../delivery/quote	Public
Re-check item availability before charging	POST .../items/check-availability	menus.read
Calculate totals (tax, fees, tip)	POST /v1/ecommerce/orders/calculate	orders.calculate

POST /orders/calculate returns the authoritative totals. Always recalculate after the customer changes order type, tip, address, or items — never trust a client-side total.

5. Pay and place the order

The card-payment path uses Stripe:

1. GET /v1/ecommerce/payment/stripe/config — publishable key + connected account (payments.read).
2. POST /v1/ecommerce/payment/stripe/create-intent — PaymentIntent client_secret (payments.create).
3. Confirm the payment client-side with Stripe.js.
4. POST /v1/ecommerce/orders/stripe — create the order with the confirmed payment_intent_id (orders.create).

Which order endpoint?

• POST /orders/stripe — the standard online path: create the order after a Stripe payment is confirmed. Use this for card payments.
• POST /orders — create an order without an attached online card payment (e.g. pay-in-store).
• Payment presentment (Payments) is for in-person terminals/kiosks, not browser checkout.

6. Confirm and track

After creation you get an order_id and order_number. Track status via the public tracking endpoint:

GET /v1/ecommerce/orders/{order}/track

See Track Order for the status values.

Getting order status updates

Polling (recommended default). Poll GET /orders/{order}/track on an interval (e.g. every 10–15 seconds) until the order reaches a terminal state (completed or cancelled). This is public, requires no extra setup, and is exactly what ShopHero's own storefront does.

async function pollOrderStatus(orderId, onUpdate, intervalMs = 15000) {
  const poll = async () => {
    const res = await fetch(
      `https://api.kitchenclick.retailsuccessplatform.com/api/v1/ecommerce/orders/${orderId}/track`
    );
    const { data } = await res.json();
    onUpdate(data);
    if (!['completed', 'cancelled'].includes(data.status)) {
      setTimeout(poll, intervalMs);
    }
  };
  poll();
}

Real-time via CommerceStream (optional). KitchenClick publishes order lifecycle events to CommerceStream, the platform's real-time event service. If you want push updates instead of polling, you can subscribe to order events over a WebSocket rather than polling /track. This is a separate integration with its own credentials and SDK — it is not part of the KitchenClick Ecommerce API. Contact your ShopHero integration manager for CommerceStream access and channel/scope provisioning if real-time delivery matters for your use case.

Catering (alternative flow)

Catering pre-orders follow a separate path:

1. GET .../event-menus — list available event menus (public).
2. GET /v1/ecommerce/event-menus/{eventMenu}/availability — capacity + slots (public).
3. POST /v1/ecommerce/event-menus/{eventMenu}/orders — place the pre-order (orders.create). Orders are created unpaid.
4. Collect the balance later via the Invoices API (payments.create).

Cross-service dependencies

• Identity — issues your OAuth token (POST {identity}/oauth/token). Required for every authenticated call.
• Stripe — client-side payment confirmation runs against Stripe directly using the client_secret and publishable key returned by the Payments endpoints.
• CommerceStream (optional) — real-time order events, as described above.

---

Changelog

Date	Change
2026-06-17	Initial publication.