Inventory: Items

Base URL: $BUSINESS_API

List catalogue items

Logs

GET /inventory/items

Pages the tenant's catalogue with limit (default 20, max 100) and the after cursor. Filter by kind (bulk or serialised), is_meter and active (true or 1 for true, any other value for false), and search with q. Needs the inventory:read scope.

Parameters

kindstring · query · optional

bulk or serialised

one of bulk, serialised

is_meterboolean · query · optional

Only meter items

activeboolean · query · optional

Only active or inactive items

qstring · query · optional

Resource-specific text search.

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Catalogue items

Show attributes
dataarray of InventoryItem · required
Show child attributes
idstring · required

itm_ identifier

tenant_idstring · required
codestring · required
namestring · required
descriptionstring · optional
unitstring · required

one of un, m, kg, l, cx, rolo

kindstring · required

one of bulk, serialised

is_meterboolean · required

Units are meters owned by the meter module

meter_manufacturerstring · optional
meter_modelstring · optional
meter_diameter_mminteger · optional
reorder_levelnumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

reorder_levelsarray of InventoryReorderLevel · required
Show child attributes
location_idstring · required
levelnumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

standard_cost_minorinteger (int64) · required
average_cost_minorinteger (int64) · required

Moving weighted average cost per unit, in minor units of the tenant currency

activeboolean · required
created_atstring (date-time) · required
updated_atstring (date-time) · required
has_moreboolean · required
next_cursorstring · optional

Errors 400 · 401 · 403

Permissions inventory:read · Roles: admin, analyst, field_reader, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/inventory/items" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "inv_2gCDJwAl34EFzaahb8GfVEQrV6w",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "code": "COD-2026-000142",
      "name": "Ana Matsinhe",
      "description": "Leitura confirmada no local.",
      "unit": "un",
      "kind": "bulk",
      "is_meter": true,
      "meter_manufacturer": "meter manufacturer",
      "meter_model": "meter model",
      "meter_diameter_mm": 1,
      "reorder_level": 1,
      "reorder_levels": [
        {
          "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
          "level": 1
        }
      ],
      "standard_cost_minor": 1,
      "average_cost_minor": 1,
      "active": true,
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Create a catalogue item

Logs

POST /inventory/items

Adds a stock item to the catalogue and returns it with status 201. code (stored upper case, unique per tenant) and name are required; unit defaults to un and must be one of un, m, kg, l, cx or rolo, and kind defaults to bulk. Serialised items, including every item with is_meter set, are counted in un. Reorder levels need distinct, existing locations and values of zero or more. Needs the inventory:supervise scope; a duplicate code returns 409. Send an Idempotency-Key header to make retries safe.

Parameters

Idempotency-Keystring · header · optional

Makes an inventory write safe to retry, for field issues replayed from offline phones. 1 to 255 visible ASCII characters, scoped to the tenant and endpoint and kept for 30 days. A completed write is stored with its response in the same transaction and returned again with its original status and body and the header Idempotent-Replayed: true, recording nothing twice. The same key on a different request (body, path or caller) is refused with 409 idempotency_conflict. A refusal is never stored.

Body application/json

codestring · required
namestring · required
descriptionstring · optional
unitstring · optional · default un

one of un, m, kg, l, cx, rolo

kindstring · optional · default bulk

one of bulk, serialised

is_meterboolean · optional
meter_manufacturerstring · optional
meter_modelstring · optional
meter_diameter_mminteger · optional
reorder_levelnumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

reorder_levelsarray of InventoryReorderLevel · optional
Show child attributes
location_idstring · required
levelnumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

standard_cost_minorinteger (int64) · optional

Returns

201 Item created

Show attributes
idstring · required

itm_ identifier

tenant_idstring · required
codestring · required
namestring · required
descriptionstring · optional
unitstring · required

one of un, m, kg, l, cx, rolo

kindstring · required

one of bulk, serialised

is_meterboolean · required

Units are meters owned by the meter module

meter_manufacturerstring · optional
meter_modelstring · optional
meter_diameter_mminteger · optional
reorder_levelnumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

reorder_levelsarray of InventoryReorderLevel · required
Show child attributes
location_idstring · required
levelnumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

standard_cost_minorinteger (int64) · required
average_cost_minorinteger (int64) · required

Moving weighted average cost per unit, in minor units of the tenant currency

activeboolean · required
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 401 · 403 · 409

Permissions inventory:supervise · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/inventory/items" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "unit": "un",
  "kind": "bulk",
  "is_meter": true,
  "meter_manufacturer": "meter manufacturer",
  "meter_model": "meter model",
  "meter_diameter_mm": 1,
  "reorder_level": 1,
  "reorder_levels": [
    {
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "level": 1
    }
  ],
  "standard_cost_minor": 0
}'
Response 201
{
  "id": "inv_2gCDJwAl34EFzaahb8GfVEQrV6w",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "unit": "un",
  "kind": "bulk",
  "is_meter": true,
  "meter_manufacturer": "meter manufacturer",
  "meter_model": "meter model",
  "meter_diameter_mm": 1,
  "reorder_level": 1,
  "reorder_levels": [
    {
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "level": 1
    }
  ],
  "standard_cost_minor": 1,
  "average_cost_minor": 1,
  "active": true,
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Get a catalogue item with its reorder levels

Logs

GET /inventory/items/{id}

Returns one catalogue item of the caller's tenant, including its per-location reorder levels, standard and average cost, and meter details. Returns 404 when the item does not exist in this tenant. Needs the inventory:read scope.

Parameters

idstring · path · required

Item ID (itm_)

Returns

200 Item

Show attributes
idstring · required

itm_ identifier

tenant_idstring · required
codestring · required
namestring · required
descriptionstring · optional
unitstring · required

one of un, m, kg, l, cx, rolo

kindstring · required

one of bulk, serialised

is_meterboolean · required

Units are meters owned by the meter module

meter_manufacturerstring · optional
meter_modelstring · optional
meter_diameter_mminteger · optional
reorder_levelnumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

reorder_levelsarray of InventoryReorderLevel · required
Show child attributes
location_idstring · required
levelnumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

standard_cost_minorinteger (int64) · required
average_cost_minorinteger (int64) · required

Moving weighted average cost per unit, in minor units of the tenant currency

activeboolean · required
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 401 · 403 · 404

Permissions inventory:read · Roles: admin, analyst, field_reader, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/inventory/items/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "inv_2gCDJwAl34EFzaahb8GfVEQrV6w",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "unit": "un",
  "kind": "bulk",
  "is_meter": true,
  "meter_manufacturer": "meter manufacturer",
  "meter_model": "meter model",
  "meter_diameter_mm": 1,
  "reorder_level": 1,
  "reorder_levels": [
    {
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "level": 1
    }
  ],
  "standard_cost_minor": 1,
  "average_cost_minor": 1,
  "active": true,
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Change an item, its standard cost and reorder levels

Logs

PATCH /inventory/items/{id}

Changes only the fields you send: name, description, reorder_level, reorder_levels (replaces the whole list), standard_cost_minor, the meter manufacturer, model and diameter, and active. Code, unit and kind cannot be changed. Negative levels or costs and a blank name return 400, and an unknown item returns 404. Needs the inventory:supervise scope; send an Idempotency-Key header to make retries safe.

Parameters

idstring · path · required

Item ID (itm_)

Idempotency-Keystring · header · optional

Makes an inventory write safe to retry, for field issues replayed from offline phones. 1 to 255 visible ASCII characters, scoped to the tenant and endpoint and kept for 30 days. A completed write is stored with its response in the same transaction and returned again with its original status and body and the header Idempotent-Replayed: true, recording nothing twice. The same key on a different request (body, path or caller) is refused with 409 idempotency_conflict. A refusal is never stored.

Body application/json

namestring · optional
descriptionstring · optional
reorder_levelnumber · optional

Quantity in the item's unit, with at most three decimals (12.5 metres).

reorder_levelsarray of InventoryReorderLevel · optional

Replaces every per-location override.

Show child attributes
location_idstring · required
levelnumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

standard_cost_minorinteger (int64) · optional
meter_manufacturerstring · optional
meter_modelstring · optional
meter_diameter_mminteger · optional
activeboolean · optional

Returns

200 Item updated

Show attributes
idstring · required

itm_ identifier

tenant_idstring · required
codestring · required
namestring · required
descriptionstring · optional
unitstring · required

one of un, m, kg, l, cx, rolo

kindstring · required

one of bulk, serialised

is_meterboolean · required

Units are meters owned by the meter module

meter_manufacturerstring · optional
meter_modelstring · optional
meter_diameter_mminteger · optional
reorder_levelnumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

reorder_levelsarray of InventoryReorderLevel · required
Show child attributes
location_idstring · required
levelnumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

standard_cost_minorinteger (int64) · required
average_cost_minorinteger (int64) · required

Moving weighted average cost per unit, in minor units of the tenant currency

activeboolean · required
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 401 · 403 · 404

Permissions inventory:supervise · Roles: admin, operations, owner

curl -X PATCH "$BUSINESS_API/inventory/items/{id}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "reorder_level": 1,
  "reorder_levels": [
    {
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "level": 1
    }
  ],
  "standard_cost_minor": 0,
  "meter_manufacturer": "meter manufacturer",
  "meter_model": "meter model",
  "meter_diameter_mm": 1,
  "active": true
}'
Response 200
{
  "id": "inv_2gCDJwAl34EFzaahb8GfVEQrV6w",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "unit": "un",
  "kind": "bulk",
  "is_meter": true,
  "meter_manufacturer": "meter manufacturer",
  "meter_model": "meter model",
  "meter_diameter_mm": 1,
  "reorder_level": 1,
  "reorder_levels": [
    {
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "level": 1
    }
  ],
  "standard_cost_minor": 1,
  "average_cost_minor": 1,
  "active": true,
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Create and update catalogue items from CSV, matched by code

Logs

POST /inventory/items/import

Create and update catalogue items from CSV, matched by code, with a dry run

Columns code, name, unit, kind, description, reorder_level, standard_cost_minor, is_meter, meter_manufacturer, meter_model, meter_diameter_mm and active, as the catalogue export writes them. A unit or kind never changes on an existing item.

Parameters

dry_runboolean · query · optional

Check every row and report errors without writing anything

Idempotency-Keystring · header · optional

Makes an inventory write safe to retry, for field issues replayed from offline phones. 1 to 255 visible ASCII characters, scoped to the tenant and endpoint and kept for 30 days. A completed write is stored with its response in the same transaction and returned again with its original status and body and the header Idempotent-Replayed: true, recording nothing twice. The same key on a different request (body, path or caller) is refused with 409 idempotency_conflict. A refusal is never stored.

Body application/json

csvstring · required

The CSV text with a header row

dry_runboolean · optional
location_idstring · optional
referencestring · optional

Returns

200 Dry run report

Show attributes
dry_runboolean · required
rowsinteger · required
validinteger · required
committedboolean · required
createdinteger · optional
updatedinteger · optional
errorsarray of object · required
Show child attributes
rowinteger · required

Line number in the file, the header being 1

columnstring · optional
codestring · required

one of item_code_missing, item_unknown, item_inactive, location_unknown, location_missing, location_inactive, quantity_invalid, unit_cost_invalid, serials_missing, serials_count_mismatch, serial_repeated, serial_exists, …

parametersobject · optional

Stable values for client-localized error text, keyed by parameter name.

messagestring · optional

English compatibility text; use code and parameters for display.

movementsarray of InventoryMovement · optional
Show child attributes
idstring · required

mvt_ identifier

tenant_idstring · required
kindstring · required

one of receipt, issue, return, transfer_out, transfer_in, adjustment, scrap

item_idstring · required
quantitynumber · required

Quantity in the item's unit, with at most three decimals (12.5 metres).

from_location_idstring · optional
to_location_idstring · optional
serial_idstring · optional
serial_numberstring · optional
unit_cost_minorinteger (int64) · required
total_cost_minorinteger (int64) · required
value_change_minorinteger (int64) · optional

Exact change to the stock value the ledger posts to stock on hand; zero for a transfer.

reasonstring · optional
reason_codestring · optional

Stable code of a reason the server wrote (inventory.meter_installed, inventory.work_order_issue, inventory.stock_transfer, inventory.stocktake_difference, ...); clients word it and fall back to reason. Absent for reasons people typed.

reason_paramsobject · optional

Values the reason code fills in: stocktake and note for inventory.stocktake_difference.

source_typestring · optional
source_idstring · optional
referencestring · optional
actor_idstring · required
work_order_idstring · optional

Work order whose material line the movement served

material_line_idstring · optional

wml_ work-order material line

occurred_atstring (date-time) · required
created_atstring (date-time) · required
meter_idsarray of string · optional

Errors 400 · 401 · 403 · 409 · 413 · 422

Permissions inventory:supervise · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/inventory/items/import" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "csv": "csv",
  "dry_run": true,
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "reference": "REF-2026-000142"
}'
Response 200
{
  "dry_run": true,
  "rows": 1,
  "valid": 1,
  "committed": true,
  "created": 1,
  "updated": 1,
  "errors": [
    {
      "row": 1,
      "column": "column",
      "code": "item_code_missing",
      "parameters": {
        "key": "value"
      },
      "message": "Leitura confirmada no local."
    }
  ],
  "movements": [
    {
      "id": "inv_2i0F7y81HuA1jQivrIMplSQpd0Y",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "receipt",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
      "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
      "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
      "serial_number": "SER-2026-000142",
      "unit_cost_minor": 1,
      "total_cost_minor": 125000,
      "value_change_minor": 1342,
      "reason": "Leitura confirmada no local.",
      "reason_code": "REA-2026-000142",
      "reason_params": {
        "key": "value"
      },
      "source_type": "source type",
      "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
      "reference": "REF-2026-000142",
      "actor_id": "act_2HXCuXB4S938w5lomxpoS73e8fr",
      "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
      "material_line_id": "mat_2OqLrIeBheCpraGrhAOfvCsXF2k",
      "occurred_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ]
}

The catalogue as plain CSV, for an ERP

Logs

GET /inventory/items/export

Downloads the whole catalogue as a text/csv attachment, built in full before it is sent so a failure comes back as a problem response instead of a cut-off file. The columns are code, name, unit, kind, description, reorder_level, standard_cost_minor, average_cost_minor, is_meter, meter_manufacturer, meter_model, meter_diameter_mm and active, the same header the item import reads. Needs the inventory:read scope.

Returns

200 text/csv with the catalogue import's columns and average_cost_minor

Errors 400 · 401 · 403

Permissions inventory:read · Roles: admin, analyst, field_reader, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/inventory/items/export" \
  -H "Authorization: Bearer sk_test_..."
Response 200

text/csv with the catalogue import's columns and average_cost_minor