external_ref — your
id for that business — in every path.
Provision
owner_email must be unique
Each tenant gets its own owner login, and a login belongs to exactly one
business. Reusing an address that already owns a tenant returns 400:
Worth planning for rather than discovering. Sharing one contact address across
several merchants is ordinary — a franchise group, or an agency onboarding
under its own ops address — so if you provision from a single ops mailbox, use
a per-tenant alias such as
ops+merch_8812@yourcompany.com.Idempotency
Keyed on(you, external_ref). A repeat returns 200 with the existing
tenant instead of 201 with a duplicate, so a retry after a timeout is safe.
The uniqueness is enforced by the database, not just checked, so two concurrent
requests cannot both win.
Re-provisioning an offboarded tenant revives it rather than returning a
dead record.
Read and list
Update
name, monthly_credit_cap, is_active.
Offboard
Isolation
A tenant belonging to another partner returns 404, never 403. That is
deliberate: a 403 would confirm the id exists, which would let anyone walk a
competitor’s customer list one guess at a time. An id you do not own and an id
that does not exist are indistinguishable to you.
tenants/{external_ref}/ — knowledge,
assistants, tools, channels.