Set up a location

Every sale, stock count and report in iotoms belongs to a location. In this guide you create the three levels of the location tree, in order: a venue (a site or branch), a store (a selling point inside the venue) and a register (the till or device that rings up sales). See Concepts for how they fit together.

At the end you will have a venue ID, a store ID and a register ID that later calls (sales, reports) can use, plus the ID of the store's stockroom.

Before you start you need a token and the merchant's tenant code. See Authentication.

Step 1 — Check what already existsCopy Anchor Link

Look before you create, so you do not add a second venue for a branch the merchant already set up.

curl 'https://beta.iotoms.com/api/v1/catalog/business/venues?page=0&size=20' \
  -H 'X-TenantID: <tenant-code>' \
  -H 'Authorization: Bearer <token>'

• data.content[].id and data.content[].name: the existing venues, sorted by name.
• query filters by text. size must be between 1 and 100.

You can list stores and registers in the same way with List stores (filter by venueId) and List registers (filter by storeId).

Endpoint: List venues

Step 2 — Create the venueCopy Anchor Link

A venue is the top of the tree; every store hangs off one.

curl -X POST 'https://beta.iotoms.com/api/v1/catalog/business/venues' \
  -H 'X-TenantID: <tenant-code>' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Downtown branch",
    "status": "ACTIVE"
  }'

The server answers 201 Created with the venue itself. It does not wrap it in the usual envelope:

{
  "id": 3,
  "name": "Downtown branch",
  "status": "ACTIVE",
  "modifiedTime": "2026-10-18T09:30:00Z"
}

• id: the venue ID. Venue, store and register IDs are whole numbers.
• Venue names must be unique within the merchant. A duplicate name returns 409.
• You do not send modifiedTime. iotoms sets it.

Endpoint: Create a venue

Step 3 — Create the storeCopy Anchor Link

A store is where selling happens, and it owns a stockroom.

curl -X POST 'https://beta.iotoms.com/api/v1/catalog/business/stores' \
  -H 'X-TenantID: <tenant-code>' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Main counter",
    "venueId": 3,
    "storeType": "FLAGSHIP",
    "status": "ACTIVE"
  }'

• venueId is the id from Step 2. An unknown venue returns 404.
• storeType is a short label of your choice. It is required.
• Store names must be unique within the merchant. A duplicate name returns 409.

The response (201, no envelope) gives you:

• id: the store ID, for example 7.
• venue: the venue the store belongs to.

When the store is created, iotoms also creates a stockroom for it. A stockroom is an inventory location named after the store, for example "Main counter (Store)". Its stock is what the store sells from. You need its ID in the next step.

Endpoint: Create a store

Step 4 — Find the store's stockroomCopy Anchor Link

The register needs to know which stockroom to take stock from when it sells.

curl 'https://beta.iotoms.com/api/v1/inventory/locations?locationType=STORE' \
  -H 'X-TenantID: <tenant-code>' \
  -H 'Authorization: Bearer <token>'

data is a plain list. Pick the entry whose storeId equals your store ID:

• id: the stockroom ID (a UUID), for example 5b0f6c1e-2d8a-4f3b-9e71-0c4d2a6b8f13.
• locationName, locationCode (for example STORE-7) and isActive.

Endpoint: List inventory locations

Step 5 — Create the registerCopy Anchor Link

The register rings up sales. Linking it to the stockroom makes every sale on it reduce that stockroom's stock.

curl -X POST 'https://beta.iotoms.com/api/v1/catalog/business/registers' \
  -H 'X-TenantID: <tenant-code>' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Till 1",
    "storeId": 7,
    "fromTime": "2026-10-18T09:00:00Z",
    "type": "POS",
    "status": "ACTIVE",
    "inventoryLocationId": "5b0f6c1e-2d8a-4f3b-9e71-0c4d2a6b8f13"
  }'

• storeId is the store ID from Step 3.
• fromTime is when the register comes into use. Send a full date and time with a time zone.
• type is POS for a fixed till and VAN for a van-sales device.
• inventoryLocationId is the stockroom ID from Step 4. It must be an active stockroom.

The response (201, no envelope) gives you id, the register ID (for example 11), and echoes inventoryLocationId.

Endpoint: Create a register

Step 6 — Confirm the setupCopy Anchor Link

Read the register back to check that it is linked to the right store and stockroom.

curl 'https://beta.iotoms.com/api/v1/catalog/business/registers/11' \
  -H 'X-TenantID: <tenant-code>' \
  -H 'Authorization: Bearer <token>'

Check store.id, store.venue.id and inventoryLocationId. Keep the register ID and store ID. You will send them with every sale.

Endpoint: Get a register

What's nextCopy Anchor Link