Add products to the catalog

Items are the products a merchant sells. Each item can sit in a category and a brand, has a selling price and a cost price, and is counted in a base unit (for example "Each"). It can also be bought or sold in bigger units, such as a case of 24.

At the end you will have an item with prices, a base unit and a case pack size, ready to be bought in and sold.

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

Step 1 — Create a categoryCopy Anchor Link

Categories group items in the catalog and in sales reports.

curl -X POST 'https://beta.iotoms.com/api/v1/catalog/attributes/categories' \
  -H 'X-TenantID: <tenant-code>' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Beverages"
  }'

The response (201) is the category itself, with no envelope. Read id, the category ID, which is a whole number. You do not send modifiedTime here or on the other catalog create calls in this guide. iotoms sets it.

Category names are unique, so creating "Beverages" twice returns 409. To reuse an existing category, call List categories. It returns a plain list of id and name.

Subcategories and departments work the same way: send a name, then read back the id.

Endpoint: Create a category

Step 2 — Create a brandCopy Anchor Link

Brands are optional, but the sales-by-brand report needs them.

curl -X POST 'https://beta.iotoms.com/api/v1/catalog/attributes/brands' \
  -H 'X-TenantID: <tenant-code>' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Fresh Springs"
  }'

The response (201, no envelope) gives you id, the brand ID.

Endpoint: Create a brand

Step 3 — Look up the tax and the unitsCopy Anchor Link

An item points to a tax rate and a base unit that already exist, so find their IDs first.

Taxes. Read id, name and taxRate1 for each tax rate the merchant has set up:

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

Units of measure. Every merchant starts with a standard set: EACH, DOZEN, CASE, BOX, KG, G, L, ML, M and CM.

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

Note the id (a UUID) of EACH and of CASE from data.content. If you need a unit that is not in the list, create it with Create a unit of measure. Send a unique code, a name, a category (COUNT, WEIGHT, VOLUME or LENGTH), the decimalPrecision and the status.

Endpoints: List taxes · List units of measure

Step 4 — Create the itemCopy Anchor Link

This call creates the product with its prices, its place in the catalog and its base unit.

curl -X POST 'https://beta.iotoms.com/api/v1/catalog/items' \
  -H 'X-TenantID: <tenant-code>' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "itemId": "SKU-10042",
    "productId": "PRD-10042",
    "upc": "8901234567890",
    "itemName": "Sparkling Water 500 ml",
    "description": "Natural sparkling mineral water",
    "sellingPrice": 1.20,
    "costPrice": 0.65,
    "categoryId": 4,
    "brandId": 9,
    "taxId": 2,
    "type": "STORE_ITEM",
    "status": "ACTIVE",
    "baseUomId": "9a3d2f10-6b7c-4e81-a5d2-3f0e1c7b6a24"
  }'

• Required: itemId, productId, itemName, sellingPrice, costPrice and type. Use STORE_ITEM for a product you sell.
• categoryId, brandId and taxId are the IDs from Steps 1–3. An ID that does not exist returns 404.
• baseUomId is the unit the item is counted and stocked in. Here it is EACH. When you send it, iotoms also records that unit on the item with a conversion factor of 1.
• description can be up to 255 characters.

The response (201) is the item itself, with no envelope. It includes the linked category, brand and tax as full objects. Store itemId. A duplicate itemId returns 409.

Endpoint: Create an item

Step 5 — Add a pack sizeCopy Anchor Link

A pack size lets the item be bought or sold in a bigger unit and still be counted in the base unit.

curl -X POST 'https://beta.iotoms.com/api/v1/catalog/items/SKU-10042/uoms' \
  -H 'X-TenantID: <tenant-code>' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "uomId": "e4c81b27-0f5a-4d39-b6e2-81a9c0d3f57e",
    "factorToBase": 24,
    "isPurchaseDefault": true,
    "isReceiveDefault": true,
    "isSellDefault": false,
    "isCountDefault": false
  }'

• The path takes the item's itemId.
• uomId is the CASE unit from Step 3. factorToBase is how many base units one case holds. It must be greater than 0.
• The four is…Default flags choose which unit is suggested when the item is bought, received, sold or counted. Only one unit per item can hold each flag. Setting a flag here clears it from the item's other units.
• Adding the same unit to an item twice returns 409.

When stock is received against a purchase order line in cases, iotoms multiplies by factorToBase. Receiving 10 cases adds 240 to stock on hand.

Endpoint: Add a unit of measure to an item

Step 6 — Check the itemCopy Anchor Link

Read back the item's units to confirm the setup.

curl 'https://beta.iotoms.com/api/v1/catalog/items/SKU-10042/uoms' \
  -H 'X-TenantID: <tenant-code>' \
  -H 'Authorization: Bearer <token>'

data.baseUomId is the base unit. data.units[] lists each unit with its code, factorToBase, isBase and default flags.

To find items later, call List items with filters such as itemId, upc, categoryId or brandId. The response has no envelope: rows are in content and paging details in page.

Endpoints: List an item's units of measure · Get an item

What's nextCopy Anchor Link