Dukachap / Developer guide
Your storefront. Our commerce core.
Build a storefront with your own design and framework. Connect products, carts, checkout and customer accounts through the Dukachap gateway.
Overview
A storefront is a website you build yourself (any framework) that reads a merchant's published catalogue and builds a cart through the Storefront API. Dukachap owns the catalogue, stock and pricing; you own the site.
Copy the Storefront request base URL and full relay token when you create an API key group. Requests go through that issued endpoint; append a path such as /storefront/products. Keep the relay token on your server. Every write that mutates state should be treated as idempotent on retry.
Practical tutorial: build an eatery storefront
Follow Kisumu Kitchen from a new React and TypeScript project through a menu and cart, customer accounts, M-Pesa orders, verified table requests, staff delivery workflows and an AI menu guide. Each step says whether it was run against a local API or checked against the API source, and the Netlify deployment step is documented but was not run.
DukaChap provides the business services; you build the frontend and a small server-side proxy that attaches your relay token and keys. The tutorial explains where table confirmation and fulfilment still require staff actions.
Build the React eatery storefront →Authentication & scopes
Create a Storefront endpoint and a matching publishable or secret key from API keys in the dashboard. The endpoint and key must belong to the same store and environment. Keep the full relay token on your server. Shoppers who sign in get a separate customer credential (see Customer accounts below).
For the examples below, set these values from the one-time creation dialog:
STOREFRONT_BASE_URL="<paste Storefront request base URL>"
STOREFRONT_RELAY_TOKEN="<paste full Storefront endpoint token>"
DUKACHAP_PUBLISHABLE_KEY="<paste publishable key>"
DUKACHAP_SECRET_KEY="<paste secret key>"
# Send X-Dukachap-Relay and X-Dukachap-Key with every gateway request.- Publishable (
pk_) keys can be exposed to browser code, but calls through this endpoint still need the private relay token; send those calls through your own server. They can only be grantedproducts:read,collections:read,metafields:read,metaobjects:read,metaobjects:write(verified forms),media:read,carts:read,carts:write,payments:readandsubscribers:write— never checkout, payment-write, order, AI or customer access, regardless of what a merchant tries to grant. - Secret (
sk_) keys must stay on a server you control — never in a browser. They're the only key type that can create checkouts, start a payment, read an order, manage customer accounts, or call AI endpoints.
A key only ever belongs to one store. TEST and LIVE credentials must match their endpoint; use TEST with a sandbox and LIVE for real payments. An invalid, revoked, expired or malformed key all return the same generic 401— don't rely on the error message to distinguish "wrong key" from "revoked key".
Keys can also be scoped down below their type's default — e.g. a secret key that can only read orders, for a back-office tool that should never start a payment. The resources today are products, collections, metafields, metaobjects, carts, checkouts, payments, orders, customers, media, subscribers and ai, each as :read / :write. Not every resource has a live route yet — the scope catalog is deliberately ahead of the API surface, so a merchant choosing scopes sees the full shape of what a key could eventually do.
Introspection
Call GET /me to check what a key is actually scoped to, instead of hard-coding assumptions about it client-side.
Store display: settings, branding & media
A storefront can render a merchant's own branding and copy without you hand-coding any of it per store.
Catalogue — products
All money values use integer minor units: 27500 means KES 275.00. Format values for display at the edge. A product withprice_minor: null is unpriced; never show it as free. Lists return data and next_cursor; pass that cursor into the next request until it is null.
Only products the merchant has explicitly published to this store are returned, regardless of scope.
Carts
Carts are anonymous and identified by a token, not by the API key alone — keep the token wherever you'd keep a session id (cookie, local storage).
Payment methods
Checkout and payment
Create a checkout from the cart, complete it to create the order, then start the payment with a separate request. Completion checks prices and stock; a cart does not reserve inventory. Every write here needs an Idempotency-Key header (a UUID for each user intent — retry the exact same request with the exact same key and you get back the same result instead of a duplicate order).
Orders & receipts
An order is a read-only projection of the sale and its payment attempts — there is no "set order status" call; poll this instead of trusting whatever the payment-attempts step returned, since STK confirmation arrives asynchronously from the customer's phone.
Customer accounts
Only relevant once a merchant has turned Customer accounts on for their store (see GET /settings above). Through the endpoint, every /customer/* route needs a secret key that carries customers:read (for GET) or customers:write (for everything else), and the endpoint must carry the same scope. A signed-in shopper also sends Authorization: Bearer <customer access token>alongside the store key and relay token. The gateway requires both store credentials on every customer request, including refresh and logout.
Coming-soon unlock
AI tools
Available when AI features are enabled on the merchant's account. All of these require a secret key with ai:write.
Errors & idempotency
Errors are JSON with a stable code and a human-readable message. Tenant isolation means a product, cart or order belonging to a different store returns a plain 404, the same as if it never existed — never a 403 that would confirm its existence.
Any endpoint documented above with an Idempotency-Key requirement expects a valid UUID. The gateway generates a key when omitted, but you should always provide your own and reuse it when retrying the same action. Direct backend writes reject missing or invalid keys with 422. Reusing a key with a changed payload returns 409 IDEMPOTENCY_CONFLICT.
