Build a headless storefront

A headless storefront replaces the marketplace’s theme with a front end you build yourself, in Next.js, Nuxt, Astro or anything else, while Kreezalid keeps the catalog, the vendors, the orders and the payouts. If you only want to change how the marketplace looks, a theme is far less work.

Who calls what

Part	Calls	With
Your server (rendering, API routes)	Admin API	Admin API credentials, server-side only
The visitor’s browser	Front API	The member’s token, or nothing for a guest
Kreezalid	Your webhook endpoint	Signed webhooks

The Front API acts for one visitor or member; it does not list the marketplace catalog. The catalog is read by your server, cached, and rendered into your pages.

Danger

Admin API credentials never reach the browser, not even in a build-time variable that ends up in a JavaScript bundle.

1. Render the catalog from your server

1. Navigation: GET /front_api/v1/categories needs no credentials and returns the marketplace’s categories with their id.

2. Category pages: GET /api/v1/listings with category_id, status=published and admin_status=approved, paged with page and limit (100 at most), trimmed with fields. See Pagination and filtering.

3. Product pages: GET /api/v1/listings/{id}. The listing comes back under product, with its images, attributes and vendor.

4. Vendor pages: GET /front_api/v1/directories/{user_id} for the public profile and GET /front_api/v1/reviews/user/{user_id} for the reviews.

Leave out listings whose visibility is search or none from category pages. Rebuild or revalidate pages from the listing.creation, listing.update and listing.delete webhooks instead of short cache lifetimes. The Admin API has no enforced rate limit, which is not a reason to call it on every page view.

2. Members

From the browser, call the Front API on the marketplace’s primary address. Cross-origin requests are allowed, so your front end can live on its own domain:

• sign-up: POST /front_api/v1/account/create with email, password and the group_id of the customer group;
• login: POST /front_api/v1/auth/login, then send Authorization: Bearer <token>;
• the current member: GET /front_api/v1/auth/me.

Keep the token where your front end keeps secrets for the session, and clear it on logout: logging out does not revoke it. Details in Authentication.

3. Cart

The cart is the Front API’s: create it with POST /front_api/v1/carts, keep its url_key, add listings with POST /front_api/v1/carts/{url_key}, and show it with GET /front_api/v1/carts/{url_key}. A guest can fill a cart; it is attached to their account once they sign in. The full sequence, delivery methods and addresses included, is in Build a mobile app: it is the same for a web front end.

Treat the url_key like a session secret: whoever knows a guest’s url_key can read and change that cart.

4. Payment

Choose one of two paths.

The hosted checkout. Send the member to the marketplace’s own checkout for the cart, at https://<primary address>/checkout/shipping/cart/{url_key}. The marketplace’s payment provider takes the payment and Kreezalid creates the orders, sends the emails and handles the vendor payouts. The checkout runs on the marketplace’s domain with its own browser session: a Front API token does not sign the member in there.

Your own payment provider. Take the payment in your front end, then let your server record it with POST /api/v1/checkout/preauth-success. Kreezalid closes the cart and passes the orders to the vendors, but capturing, refunding and paying vendors out stay with you. See Record orders paid outside Kreezalid.

5. After the purchase

• The member’s orders: GET /front_api/v1/orders and GET /front_api/v1/orders/{id}.
• Order follow-up in your own systems: the order.status.* webhooks. See Sync orders to an ERP.

Checklist

• No Admin API credentials in any code or variable sent to the browser.
• Catalog pages show only published, approved listings visible in the catalog.
• Pages are refreshed from listing webhooks, and webhook signatures are verified.
• A 403 from the Front API sends the member back to the login screen.
• Every Front API response is checked for its success or status field. See Errors.