Getting started

Kentro has two public APIs, and the first decision is which one a project needs.

• The Channel API (apis.kentro.live/channel/v1) moves a sales channel's data into and out of Kentro: orders, customers, products, inventory, fulfillment, shipments, invoices, payments, purchase orders. It is for integrations (marketplaces, carts, EDI, 3PLs, ERPs). Kentro is the system of record; the caller is a system. Start at Channel API: Getting started.
• The Store API (apis.kentro.live/store/v1) is Kentro's storefront infrastructure (buyer sign-in, the catalog with the buyer's prices, cart, quotes, checkout, orders, invoices, account, subscriptions) for a tenant who builds their own storefront UI instead of using the templates in Kentro OS > Storefront. The caller is the tenant's storefront server, acting for one buyer at a time.

This page covers the Store API. The pages after it cover authentication, the conventions every operation shares, the buyer's journey with bodies, the migration from the legacy Store API and the changelog.

What a custom storefront is

A storefront in Kentro is a published B2B store: a sales channel, a catalog with price lists, buyers with accounts, a checkout and the orders it produces. Kentro OS ships storefront templates that render all of that on a host Kentro serves. A custom storefront replaces the rendering only. The tenant runs their own web application, and that application's server calls the Store API for the buyer in front of it, exactly as Kentro's own templates do: one API key identifies the storefront server, one storefront host names the store, and one buyer token (or guest token) names the buyer of the current request.

What stays in Kentro: the catalog, prices and stock, buyer accounts and approvals, carts, quotes with shipping and tax, checkout and payment, orders, invoices and subscriptions. What the custom storefront owns: pages, layout, sessions in the browser, and the mapping between the browser's cookie and the buyer token it holds for that browser.

The Store API is server-to-server. A browser never calls it directly: the API key is a tenant credential, and the API answers with no CORS headers for tenant origins.

Prerequisites

1. A published storefront

1. In Kentro OS open Storefronts and create a storefront or open an existing one. The storefront is tied to one sales channel; its catalog, buyers and orders live on that channel.
2. Complete the publish checklist and click Publish. Under Publish or hide the storefront has a managed address (a subdomain of Kentro's storefront domain) that Kentro serves.
3. The host the Store API needs is the host buyers use. With a custom domain, add it under Custom domain in the storefront's settings, add the DNS records the panel lists (an ownership TXT record, and a CNAME to Kentro's ingress or A and AAAA records for a zone apex), and click Verify. Either host works as X-Storefront-Host once the storefront is published and the host is live.

A storefront that is not published does not answer: every call for its host is 404 NOT_FOUND.

2. An API key with the Store API scope

An API key belongs to one tenant and carries the scopes of its permission groups.

1. Sign in to Kentro OS as a user with the Admin permission group.
2. Open Users > Permission groups and create a group (Custom storefront) that holds the Store API scope storefront:serve. The Admin group also carries it.
3. Open Users, select the API keys tab and click Create. Label the key after the storefront (shop.example.com server), assign the group, click Save.
4. The dialog shows the key once. Store it in the storefront server's secrets store; it never reaches a browser bundle.

A key without storefront:serve or admin is refused on every Store API operation with 403 FORBIDDEN and the message "This API key cannot serve a storefront." A key can serve only the storefronts of its own tenant; see the tenant guard.

Base URLs

Every operation on this reference is relative to the base URL: POST /cart.add is POST https://apis.kentro.live/store/v1/cart.add. The sandbox runs the same release train one step ahead of production and holds its own tenants, storefronts and keys; a production key does not work there.

The first call

store.get reads the published storefront behind a host: branding, access rules, the capabilities a storefront UI needs (guest checkout, payment provider, fulfillment methods, subscriptions, applications) and the content configuration. It needs the API key and the host, nothing else.

curl -s -X POST https://apis.kentro.live/store/v1/store.get \
  -H "X-API-Key: $KENTRO_API_KEY" \
  -H "X-Storefront-Host: shop.example.com" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "id": "0b6c2e51-5f1e-4a4f-8d0e-6a3d5c2f9a10",
  "name": "Example Wholesale",
  "tagline": "Trade pricing for stockists",
  "description": "",
  "accent": "#0B5FFF",
  "access": "approval",
  "guestCheckout": false,
  "publicPrices": false,
  "guestPrices": false,
  "canAddCard": true,
  "paymentProvider": "stripe",
  "checkoutEnabled": true,
  "fulfillment": ["shipping", "pickup"],
  "locations": [],
  "currency": "USD",
  "minimumOrder": 0,
  "freeShippingThreshold": 0,
  "categories": ["Mugs", "Glassware"],
  "logo": "https://cdn.kentro.live/.../logo.png",
  "announcement": "",
  "supportEmail": "[email protected]",
  "support": { "email": "[email protected]", "phone": "", "hours": "" },
  "theme": { "logoUrl": "...", "primaryColor": "#0B5FFF", "secondaryColor": "#111827", "headingFont": "inter", "bodyFont": "inter" },
  "catalogViews": ["grid", "list", "quick-order"],
  "defaultCatalogView": "grid",
  "acquisition": { "methods": ["email"], "requiredFields": ["name", "company"], "inviteCodeIsEnabled": false, "publicSignup": true, "requireConfirmation": true, "mode": "approval" },
  "applicationEnabled": true,
  "applicationFields": [],
  "checkoutPolicy": { "..." : "..." },
  "content": { "..." : "..." },
  "pages": { "home": [], "collection": [], "product": [], "content": [] }
}

The fields a custom storefront reads first:

A X-Store-Degraded: payment-config response header means the payment capabilities were built from a fallback; do not cache that answer.

What to build next

1. Authentication: the API key, the buyer token from POST /auth/login/customer, the guest token from POST /session.guest, refresh and password reset.
2. Conventions: operations and bodies, cart revisions, money, the error envelope.
3. Flows: the catalog, the cart, the quote, checkout and what comes after, each with its request and answer.
4. The operation reference below this page, generated from the API's own schemas.