Customers & Instances

A Customer is a company you sell to — the commercial counterparty. An Instance is one running copy of your product for that customer, and the record every other concept attaches to: the License it runs under, the usage it reports, the flags evaluated for it, the zone it runs in, its audit trail.

Kaiten Sushi Shop sells to four restaurant groups through six instances. Sakura Tokyo runs sakura-tokyo-prod on Premium and a sales demo, sakura-tokyo-demo, on Starter — one customer, two instances, two Licenses. Ninja Osaka runs ninja-osaka-prod on Starter and a delivery pilot, ninja-osaka-delivery, on the second version of Standard. Demo Restaurant runs demo-restaurant-prod on Standard, and Kappa Kyoto runs kappa-kyoto-prod on the first version of Premium, kept after that version left the catalog.

Customer

A customer has a name, a slug, and two optional fields that carry your identifiers: externalCustomerId — the record ID in your CRM or billing tool — and domain. That is the BYO-ID principle: Kaiten stores the key your other systems already use, so matching a customer across tools needs no mapping table — Sakura Tokyo carries crm-1024; Demo Restaurant, created for demos, carries none. Customers are created by hand in the console or over the API (POST /customers); a CRM connector such as Attio then mirrors them into the CRM, and the link to each CRM record hangs off the customer as a per-adapter integration record.

Deleting a customer deletes its instances with it. Every customer change is an event — CUSTOMER_CREATED, CUSTOMER_UPDATED, CUSTOMER_DELETED — and so is a refusal: when an organization has reached its own customer cap, the attempt is recorded as CUSTOMER_CREATION_REJECTED and nothing is created. Kaiten gates itself with Kaiten.

Instance

An instance references exactly one customer and exactly one License — both required at creation (POST /instances with customerId and licenseId) — and optionally one deployment zone. The License it references is one version of a product: the instance is pinned to that version, and a newer version of the same License family changes nothing for it. Two dates, startLicenseDate and endLicenseDate, bound the contract period for that instance. Two more fields describe its situation without changing its contract:

• status is operational: HEALTHY, DEGRADED, INCIDENT, or MAINTENANCE.
• lifecycleStage is commercial and free-form; TRIAL, ACTIVE, AT_RISK, CHURNED are the suggested values.

Both change through PATCH /instances/{slug}, and each change is its own event (INSTANCE_STATUS_CHANGED, INSTANCE_LIFECYCLE_STAGE_CHANGED). metadata holds the typed properties your organization declared as metadata fields — here environment: production; the instance has no other free-form property.

The instance is the convergence point because it is the only record that knows both sides: the grant (through its License) and the runtime (its slug is the instanceSlug path parameter your product sends when it reports usage, and the kaiten.instanceSlug context attribute when it evaluates a flag). Usage lives per instance, a flag evaluation can name its instance in its context, and the audit trail is read per instance.

Lifecycle

Create the instance under a License, then operate it — your product reports usage and evaluates flags with the instance slug. Change the License to upgrade, downgrade, or move to a newer version (PUT /instances/{slug} with a new licenseId). The version's state decides what can be assigned: a published version always; a draft too, to try it before it goes on sale; an archived version — withdrawn from sale — never, at creation or by a change of License (422). An instance already on a version that is archived later keeps it and stays editable, as Kappa Kyoto's does.

Assign the instance to a deployment zone, or move it to another; both are events (INSTANCE_DEPLOYED, INSTANCE_MIGRATED). Deletion is a real delete — there is no trash — but the audit trail entries recorded for the instance survive it.

Slugs are URL-safe, unique per organization, generated from the name when you omit them, and the identifier used in every API path (/instances/sakura-tokyo-prod).

Where to go next

The quickstart builds this chain from the console and the API; the console tour walks the seeded restaurants.

Exact reference: data model.