Core concepts

Kentro is the system of record for a business's commerce, and every integration acts for exactly one of those businesses. The terms on this page appear on every API page; learn them once here.

Tenants and workspaces

A tenant is one Kentro account: one business with its users, settings, sales channels, warehouses and documents. Kentro OS also calls it the workspace; tenant-wide settings appear there as workspace defaults.

Every API key belongs to one tenant, and the key's tenant is the tenant of every request. No header, body field or query parameter selects a tenant.
Nothing a key does reaches another tenant. A Channel API channelId from another tenant answers 404 not_found; a Store API storefront host of another tenant answers 403 FORBIDDEN.
A partner that works for several businesses (an agency, a 3PL, an ERP consultant) holds one key per tenant.

Sales channels

A sales channel is a place orders come from: a marketplace, a cart, a B2B storefront, an EDI retailer. Each has an id, a type and a currency; GET /v1/channels lists the ones a key may write into.

Every document the Channel API writes belongs to one channel: channelId in the body of a create, the document's own channel afterwards.
externalId, the integration's own id for a document, is unique within its channel.
A key can be bound to channels. A bound key writes only into its channels and still reads everything; an unbound key writes into any channel of its tenant.
A storefront is tied to one sales channel. Its catalog, buyers and orders live on that channel, so storefront orders are ordinary Kentro orders on that channel.

Warehouses and locations

Stock lives in warehouses. A warehouse holds locations (bins), and stock can be tracked per lot.

Inventory levels are set per warehouse, location and lot: PUT /v1/products/:id/inventory-levels takes warehouseId, locationId, lotNumber or lotId, and onHand.
When an order arrives, Kentro routes its lines through the tenant's routing rules and creates fulfillment orders. Each one is the part of the order one warehouse ships, and it reserves that stock.
The warehouse can be the tenant's own, a 3PL's, or the sales channel itself when the channel ships and Kentro only records the shipment.
Shipping moves stock: a shipment or a fulfill call credits the order lines and, by default, takes the units out of inventory.

Documents and ids

The Channel API calls each record a document.

Document	What it is
Customer	A buyer: a business or a person.
Product	A sellable item, or a group of variants, with listings per sales channel and prices.
Order	What a buyer ordered on a channel, with lines and totals.
Fulfillment order	The part of an order one warehouse ships.
Shipment	Units that left a warehouse, with carrier, tracking and package.
Invoice	A charge or a refund for an order.
Payment	Money received or refunded, applied to invoices.
Purchase order	A retailer's order, accepted into a sales order or rejected.
Vendor	A supplier of the tenant, with contacts.

Every document has a Kentro id, a uuid, on every response.
The Channel API also addresses a document by its 24-hex id, or as ext:<channelId>:<externalId>, wherever a path or a body takes an id.
displayId carries the number people see (#1001).
version is an optimistic-concurrency token on every document: send it back on an update to refuse the write if the document changed in between (409 version_conflict).
The Store API names records by uuid (orders.get { id }), and products also by handle (catalog.get { id, selector: "handle" }).

Details: Channel API: Requests and responses.

Environments

Production (apis.kentro.live, Kentro OS at https://kentro.app) runs live tenants. The sandbox (apis.kentro.dev, Kentro OS at https://kentro.cc) is Kentro's staging environment, with its own tenants, keys and data. See Environments.

Events

Every write that changes a document records events, such as order.created. Kentro acts on them downstream: confirmation emails, packing slips, accounting exports and EDI documents.

A write that answers outcome: unchanged wrote nothing and recorded no event, so replaying a feed is safe.
X-Import-Mode: historical stores documents without those downstream effects, for loading a channel's history. X-Dry-Run: true runs a write in full and rolls it back.
Integrations do not subscribe to these events: neither the Channel API nor the Store API calls a URL of yours. To pick up what changed in Kentro, poll the list endpoints with updatedSince; see Common flows.
Pixel events are a different thing: measurement events such as marketing.page_viewed or commerce.order_paid that a website or a server sends to Kentro Pixel. See Pixel events.