Concepts
How an iotoms business is organised — tenants, venues, stores, registers, users and permissions.
You will meet the same few building blocks in almost every endpoint. Knowing them makes the rest of the reference easy to read.
Tenant
A tenant is one merchant business on iotoms. Each tenant's data is kept completely separate from every other tenant's.
Each tenant has a short tenant code. It is the value users type in the Domain field
on the iotoms login screen. Send it in the X-TenantID header on every request — including
login. A token only works with the tenant it was issued for.
Always the same tenant
Never mix tenant codes in one session. Records are looked up inside the tenant you name, so an ID from one tenant returns 404 in another.
Locations: venues, stores and registers
A business is organised as a three-level tree:
| Level | What it is | Example |
|---|---|---|
| Venue | A site or branch of the business | "Downtown branch" |
| Store | A selling point inside a venue | "Main counter", "Van 12" |
| Register | A till or device that rings up sales inside a store | "Till 1" |
Sales, stock and reports are recorded against these locations, so many endpoints take a
storeId, venueId or registerId. Create them in that order: venue, then store, then
register.
Catalog
Items are the products a merchant sells, organised with brands, categories, departments and attributes, and sold in units of measure (for example a piece, a box of 12, or a kilogram).
Users, roles and permissions
Every call runs as an iotoms user. Each user has one role, and the role decides which features the user can use — for example viewing reports or approving purchase orders. What a merchant can switch on also depends on their plan.
If the user behind your token lacks a feature, the endpoint answers 403 Forbidden. The fix is on the merchant's side: an administrator grants the feature to the role in the iotoms console.