Inventory: Inventory

Base URL: $BUSINESS_API

What is where

Logs

GET /inventory/balances

What is where: on hand, reserved, available and in transit

Pages the stock balance rows (one per location and item), ordered by location then item, with limit (default 20, max 100) and the after cursor. Narrow with location_id and item_id. Set non_zero=true to skip empty rows, below_reorder=true for rows at or under the reorder level once holds and planned shortfalls are taken off, and short_for_planned=true for rows where planned work orders need more than is available. Needs the inventory:read scope.

Parameters

location_idstring · query · optional

One location

item_idstring · query · optional

One item

below_reorderboolean · query · optional

Only balances at or under their reorder level

non_zeroboolean · query · optional

Leave out empty balances

short_for_plannedboolean · query · optional

Only balances whose available stock does not cover the unreserved need of planned work orders

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Balances ordered by location and item

Show attributes
dataarray of InventoryBalance · required
Show child attributes
tenant_idstring · required
item_idstring · required
item_codestring · required
item_namestring · required
unitstring · required
location_idstring · required
location_namestring · required
on_handnumber · required

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

reservednumber · required

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

availablenumber · required

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

in_transitnumber · required

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

reorder_levelnumber · optional

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

planned_shortnumber · optional

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

below_reorderboolean · required

Available less planned_short is at or under the reorder level

value_minorinteger (int64) · 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/balances" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "item_code": "ITE-2026-000142",
      "item_name": "Ana Matsinhe",
      "unit": "unit",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "location_name": "Ana Matsinhe",
      "on_hand": 1,
      "reserved": 1,
      "available": 1,
      "in_transit": 1,
      "reorder_level": 1,
      "planned_short": 1,
      "below_reorder": true,
      "value_minor": 1342,
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

On hand, reserved and available for one item, by location

Logs

GET /inventory/availability

Adds up the balances of one item across locations and returns the totals together with the per-location balances. item_id is required (400 when missing, 404 when the item does not exist in this tenant). Pass location_id to limit the answer to one location; without it, only locations with a non-zero on-hand, reserved or in-transit quantity are listed. Needs the inventory:read scope.

Parameters

item_idstring · query · required

The item

location_idstring · query · optional

One location; without it every location holding the item

Returns

200 Availability

Show attributes
item_idstring · required
on_handnumber · required

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

reservednumber · required

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

availablenumber · required

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

in_transitnumber · required

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

locationsarray of InventoryBalance · required
Show child attributes
tenant_idstring · required
item_idstring · required
item_codestring · required
item_namestring · required
unitstring · required
location_idstring · required
location_namestring · required
on_handnumber · required

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

reservednumber · required

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

availablenumber · required

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

in_transitnumber · required

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

reorder_levelnumber · optional

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

planned_shortnumber · optional

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

below_reorderboolean · required

Available less planned_short is at or under the reorder level

value_minorinteger (int64) · required
updated_atstring (date-time) · required

Errors 400 · 401 · 403 · 404

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

curl -X GET "$BUSINESS_API/inventory/availability" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
  "on_hand": 1,
  "reserved": 1,
  "available": 1,
  "in_transit": 1,
  "locations": [
    {
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "item_code": "ITE-2026-000142",
      "item_name": "Ana Matsinhe",
      "unit": "unit",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "location_name": "Ana Matsinhe",
      "on_hand": 1,
      "reserved": 1,
      "available": 1,
      "in_transit": 1,
      "reorder_level": 1,
      "planned_short": 1,
      "below_reorder": true,
      "value_minor": 1342,
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Receive stock

Logs

POST /inventory/receipts

Receive stock, with serials for serialised items

Receiving units of a meter item registers each meter in the meter module (device status in_warehouse) and its serial at the location in one action. Each unit cost feeds the moving weighted average cost.

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

location_idstring · required
referencestring · optional

Delivery note

reasonstring · optional
occurred_atstring (date-time) · optional
meter_unitstring · optional

Dial unit of received meters (default m3)

meter_precisioninteger · optional
linesarray of InventoryMovementLine · required
Show child attributes
item_idstring · required
quantitynumber · optional

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

serialsarray of string · optional

Serial numbers of a serialised item; their count is the quantity.

unit_cost_minorinteger (int64) · optional

Receipts only: cost per unit

Returns

201 Receipt recorded

Show attributes
movementsarray of InventoryMovement · required
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
transferobject · optional
Show child attributes
idstring · required

xfr_ identifier

tenant_idstring · required
from_location_idstring · required
to_location_idstring · required
statusstring · required

one of in_transit, received

reasonstring · optional
linesarray of InventoryTransferLine · required
Show child attributes
item_idstring · required
quantitynumber · required

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

serialsarray of string · optional
created_bystring · required
received_bystring · optional
created_atstring (date-time) · required
received_atstring (date-time) · optional
stocktakeobject · optional
Show child attributes
idstring · required

stk_ identifier

tenant_idstring · required
location_idstring · required
statusstring · required

one of counting, approved

reasonstring · optional
created_bystring · required
frozen_atstring (date-time) · required
approved_bystring · optional
approval_reasonstring · optional
approved_atstring (date-time) · optional
linesarray of InventoryStocktakeLine · required
Show child attributes
item_idstring · required
expectednumber · required

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

expected_serialsarray of string · optional
countednumber · optional

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

counted_serialsarray of string · optional
differencenumber · optional

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

unit_cost_minorinteger (int64) · required
difference_value_minorinteger (int64) · required
counted_bystring · optional
counted_atstring (date-time) · optional
difference_value_minorinteger (int64) · required
created_atstring (date-time) · required
updated_atstring (date-time) · required
meter_idsarray of string · optional

Meters a receipt registered, in line order.

alertsarray of InventoryAlert · optional
Show child attributes
idstring · required

sal_ identifier

tenant_idstring · required
kindstring · required

one of negative_balance, below_reorder, short_for_planned

item_idstring · required
location_idstring · required
quantitynumber · required

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

levelnumber · optional

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

statusstring · required

one of open, resolved

movement_idstring · optional
created_atstring (date-time) · required
resolved_atstring (date-time) · optional

Errors 400 · 401 · 403 · 404 · 409

Permissions inventory:write · Roles: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/inventory/receipts" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "reference": "REF-2026-000142",
  "reason": "Leitura confirmada no local.",
  "occurred_at": "2026-11-19T09:30:00Z",
  "meter_unit": "meter unit",
  "meter_precision": 1,
  "lines": [
    {
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "serials": [
        "serial"
      ],
      "unit_cost_minor": 0
    }
  ]
}'
Response 201
{
  "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"
    }
  ],
  "transfer": {
    "id": "inv_2wMjl0ORXYUtt0UhtMAjLG4p9sC",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
    "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
    "status": "in_transit",
    "reason": "Leitura confirmada no local.",
    "lines": [
      {
        "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
        "quantity": 1,
        "serials": [
          "serial"
        ]
      }
    ],
    "created_by": "created by",
    "received_by": "received by",
    "created_at": "2026-11-19T09:30:00Z",
    "received_at": "2026-11-19T09:30:00Z"
  },
  "stocktake": {
    "id": "inv_24EVJwEl7uYvnWsNvQCjjGAh7m0",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
    "status": "counting",
    "reason": "Leitura confirmada no local.",
    "created_by": "created by",
    "frozen_at": "2026-11-19T09:30:00Z",
    "approved_by": "approved by",
    "approval_reason": "approval reason",
    "approved_at": "2026-11-19T09:30:00Z",
    "lines": [
      {
        "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
        "expected": 1,
        "expected_serials": [
          "expected serial"
        ],
        "counted": 1,
        "counted_serials": [
          "counted serial"
        ],
        "difference": 1,
        "unit_cost_minor": 1,
        "difference_value_minor": 1342,
        "counted_by": "counted by",
        "counted_at": "2026-11-19T09:30:00Z"
      }
    ],
    "difference_value_minor": 1342,
    "created_at": "2026-11-19T09:30:00Z",
    "updated_at": "2026-11-19T09:30:00Z"
  },
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "alerts": [
    {
      "id": "inv_2H3QUvtWWV98WDVE0D7m29HSOlh",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "negative_balance",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "level": 1,
      "status": "open",
      "movement_id": "mov_2xXIgdXcMfHmUBNcWnVo85VUmtl",
      "created_at": "2026-11-19T09:30:00Z",
      "resolved_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Issue stock to a work order or connection

Logs

POST /inventory/issues

Refused with insufficient_stock when available stock would go below zero, unless the location allows negative stock; a negative balance then raises an alert. Meter serials are issued by installing the meter.

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

location_idstring · required
source_typestring · optional

one of work_order, connection, other

source_idstring · optional
reasonstring · required
occurred_atstring (date-time) · optional
linesarray of InventoryMovementLine · required
Show child attributes
item_idstring · required
quantitynumber · optional

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

serialsarray of string · optional

Serial numbers of a serialised item; their count is the quantity.

unit_cost_minorinteger (int64) · optional

Receipts only: cost per unit

Returns

201 Issue recorded at the average cost

Show attributes
movementsarray of InventoryMovement · required
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
transferobject · optional
Show child attributes
idstring · required

xfr_ identifier

tenant_idstring · required
from_location_idstring · required
to_location_idstring · required
statusstring · required

one of in_transit, received

reasonstring · optional
linesarray of InventoryTransferLine · required
Show child attributes
item_idstring · required
quantitynumber · required

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

serialsarray of string · optional
created_bystring · required
received_bystring · optional
created_atstring (date-time) · required
received_atstring (date-time) · optional
stocktakeobject · optional
Show child attributes
idstring · required

stk_ identifier

tenant_idstring · required
location_idstring · required
statusstring · required

one of counting, approved

reasonstring · optional
created_bystring · required
frozen_atstring (date-time) · required
approved_bystring · optional
approval_reasonstring · optional
approved_atstring (date-time) · optional
linesarray of InventoryStocktakeLine · required
Show child attributes
item_idstring · required
expectednumber · required

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

expected_serialsarray of string · optional
countednumber · optional

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

counted_serialsarray of string · optional
differencenumber · optional

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

unit_cost_minorinteger (int64) · required
difference_value_minorinteger (int64) · required
counted_bystring · optional
counted_atstring (date-time) · optional
difference_value_minorinteger (int64) · required
created_atstring (date-time) · required
updated_atstring (date-time) · required
meter_idsarray of string · optional

Meters a receipt registered, in line order.

alertsarray of InventoryAlert · optional
Show child attributes
idstring · required

sal_ identifier

tenant_idstring · required
kindstring · required

one of negative_balance, below_reorder, short_for_planned

item_idstring · required
location_idstring · required
quantitynumber · required

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

levelnumber · optional

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

statusstring · required

one of open, resolved

movement_idstring · optional
created_atstring (date-time) · required
resolved_atstring (date-time) · optional

Errors 400 · 401 · 403 · 404 · 409

Permissions inventory:van:write · Roles: admin, field_reader, owner

curl -X POST "$BUSINESS_API/inventory/issues" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "source_type": "work_order",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "reason": "Leitura confirmada no local.",
  "occurred_at": "2026-11-19T09:30:00Z",
  "lines": [
    {
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "serials": [
        "serial"
      ],
      "unit_cost_minor": 0
    }
  ]
}'
Response 201
{
  "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"
    }
  ],
  "transfer": {
    "id": "inv_2wMjl0ORXYUtt0UhtMAjLG4p9sC",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
    "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
    "status": "in_transit",
    "reason": "Leitura confirmada no local.",
    "lines": [
      {
        "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
        "quantity": 1,
        "serials": [
          "serial"
        ]
      }
    ],
    "created_by": "created by",
    "received_by": "received by",
    "created_at": "2026-11-19T09:30:00Z",
    "received_at": "2026-11-19T09:30:00Z"
  },
  "stocktake": {
    "id": "inv_24EVJwEl7uYvnWsNvQCjjGAh7m0",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
    "status": "counting",
    "reason": "Leitura confirmada no local.",
    "created_by": "created by",
    "frozen_at": "2026-11-19T09:30:00Z",
    "approved_by": "approved by",
    "approval_reason": "approval reason",
    "approved_at": "2026-11-19T09:30:00Z",
    "lines": [
      {
        "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
        "expected": 1,
        "expected_serials": [
          "expected serial"
        ],
        "counted": 1,
        "counted_serials": [
          "counted serial"
        ],
        "difference": 1,
        "unit_cost_minor": 1,
        "difference_value_minor": 1342,
        "counted_by": "counted by",
        "counted_at": "2026-11-19T09:30:00Z"
      }
    ],
    "difference_value_minor": 1342,
    "created_at": "2026-11-19T09:30:00Z",
    "updated_at": "2026-11-19T09:30:00Z"
  },
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "alerts": [
    {
      "id": "inv_2H3QUvtWWV98WDVE0D7m29HSOlh",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "negative_balance",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "level": 1,
      "status": "open",
      "movement_id": "mov_2xXIgdXcMfHmUBNcWnVo85VUmtl",
      "created_at": "2026-11-19T09:30:00Z",
      "resolved_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Return issued stock to a location

Logs

POST /inventory/returns

Puts issued stock back into an active location as return movements and responds with status 201. A reason is required; source_type and source_id can point at the work order or record the stock came back from, and occurred_at can backdate the movement. Serialised lines must list serials that are currently issued (409 serial_mismatch otherwise), and they move back in stock at the location. Callers with only the inventory:van:write scope can return only into a van whose members include them. 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

location_idstring · required
source_typestring · optional

one of work_order, connection, other

source_idstring · optional
reasonstring · required
occurred_atstring (date-time) · optional
linesarray of InventoryMovementLine · required
Show child attributes
item_idstring · required
quantitynumber · optional

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

serialsarray of string · optional

Serial numbers of a serialised item; their count is the quantity.

unit_cost_minorinteger (int64) · optional

Receipts only: cost per unit

Returns

201 Return recorded

Show attributes
movementsarray of InventoryMovement · required
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
transferobject · optional
Show child attributes
idstring · required

xfr_ identifier

tenant_idstring · required
from_location_idstring · required
to_location_idstring · required
statusstring · required

one of in_transit, received

reasonstring · optional
linesarray of InventoryTransferLine · required
Show child attributes
item_idstring · required
quantitynumber · required

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

serialsarray of string · optional
created_bystring · required
received_bystring · optional
created_atstring (date-time) · required
received_atstring (date-time) · optional
stocktakeobject · optional
Show child attributes
idstring · required

stk_ identifier

tenant_idstring · required
location_idstring · required
statusstring · required

one of counting, approved

reasonstring · optional
created_bystring · required
frozen_atstring (date-time) · required
approved_bystring · optional
approval_reasonstring · optional
approved_atstring (date-time) · optional
linesarray of InventoryStocktakeLine · required
Show child attributes
item_idstring · required
expectednumber · required

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

expected_serialsarray of string · optional
countednumber · optional

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

counted_serialsarray of string · optional
differencenumber · optional

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

unit_cost_minorinteger (int64) · required
difference_value_minorinteger (int64) · required
counted_bystring · optional
counted_atstring (date-time) · optional
difference_value_minorinteger (int64) · required
created_atstring (date-time) · required
updated_atstring (date-time) · required
meter_idsarray of string · optional

Meters a receipt registered, in line order.

alertsarray of InventoryAlert · optional
Show child attributes
idstring · required

sal_ identifier

tenant_idstring · required
kindstring · required

one of negative_balance, below_reorder, short_for_planned

item_idstring · required
location_idstring · required
quantitynumber · required

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

levelnumber · optional

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

statusstring · required

one of open, resolved

movement_idstring · optional
created_atstring (date-time) · required
resolved_atstring (date-time) · optional

Errors 400 · 401 · 403 · 404 · 409

Permissions inventory:van:write · Roles: admin, field_reader, owner

curl -X POST "$BUSINESS_API/inventory/returns" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "source_type": "work_order",
  "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
  "reason": "Leitura confirmada no local.",
  "occurred_at": "2026-11-19T09:30:00Z",
  "lines": [
    {
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "serials": [
        "serial"
      ],
      "unit_cost_minor": 0
    }
  ]
}'
Response 201
{
  "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"
    }
  ],
  "transfer": {
    "id": "inv_2wMjl0ORXYUtt0UhtMAjLG4p9sC",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
    "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
    "status": "in_transit",
    "reason": "Leitura confirmada no local.",
    "lines": [
      {
        "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
        "quantity": 1,
        "serials": [
          "serial"
        ]
      }
    ],
    "created_by": "created by",
    "received_by": "received by",
    "created_at": "2026-11-19T09:30:00Z",
    "received_at": "2026-11-19T09:30:00Z"
  },
  "stocktake": {
    "id": "inv_24EVJwEl7uYvnWsNvQCjjGAh7m0",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
    "status": "counting",
    "reason": "Leitura confirmada no local.",
    "created_by": "created by",
    "frozen_at": "2026-11-19T09:30:00Z",
    "approved_by": "approved by",
    "approval_reason": "approval reason",
    "approved_at": "2026-11-19T09:30:00Z",
    "lines": [
      {
        "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
        "expected": 1,
        "expected_serials": [
          "expected serial"
        ],
        "counted": 1,
        "counted_serials": [
          "counted serial"
        ],
        "difference": 1,
        "unit_cost_minor": 1,
        "difference_value_minor": 1342,
        "counted_by": "counted by",
        "counted_at": "2026-11-19T09:30:00Z"
      }
    ],
    "difference_value_minor": 1342,
    "created_at": "2026-11-19T09:30:00Z",
    "updated_at": "2026-11-19T09:30:00Z"
  },
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "alerts": [
    {
      "id": "inv_2H3QUvtWWV98WDVE0D7m29HSOlh",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "negative_balance",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "level": 1,
      "status": "open",
      "movement_id": "mov_2xXIgdXcMfHmUBNcWnVo85VUmtl",
      "created_at": "2026-11-19T09:30:00Z",
      "resolved_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Adjust stock found

Logs

POST /inventory/adjustments

Adjust stock found (positive) or missing (negative)

Corrects the on-hand stock at one active location: a positive line quantity records stock found, a negative one removes stock missing, and each line becomes an append-only adjustment movement. Needs the inventory:supervise scope and a reason. For serialised items, the serials you list are created in stock (found) or marked lost (missing). Meters found must come in through a receipt and return 409, as do removals that would take the location below its reserved stock (insufficient_stock) unless it allows negative stock. Movements that carry value raise an inventory.movement.recorded event for the ledger. Send an Idempotency-Key header to make retries safe: a replay returns the stored response with Idempotent-Replayed: true.

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

location_idstring · required
reasonstring · required
linesarray of InventoryMovementLine · required

A positive quantity adds stock found; a negative one removes stock missing.

Show child attributes
item_idstring · required
quantitynumber · optional

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

serialsarray of string · optional

Serial numbers of a serialised item; their count is the quantity.

unit_cost_minorinteger (int64) · optional

Receipts only: cost per unit

Returns

201 Adjustment recorded

Show attributes
movementsarray of InventoryMovement · required
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
transferobject · optional
Show child attributes
idstring · required

xfr_ identifier

tenant_idstring · required
from_location_idstring · required
to_location_idstring · required
statusstring · required

one of in_transit, received

reasonstring · optional
linesarray of InventoryTransferLine · required
Show child attributes
item_idstring · required
quantitynumber · required

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

serialsarray of string · optional
created_bystring · required
received_bystring · optional
created_atstring (date-time) · required
received_atstring (date-time) · optional
stocktakeobject · optional
Show child attributes
idstring · required

stk_ identifier

tenant_idstring · required
location_idstring · required
statusstring · required

one of counting, approved

reasonstring · optional
created_bystring · required
frozen_atstring (date-time) · required
approved_bystring · optional
approval_reasonstring · optional
approved_atstring (date-time) · optional
linesarray of InventoryStocktakeLine · required
Show child attributes
item_idstring · required
expectednumber · required

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

expected_serialsarray of string · optional
countednumber · optional

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

counted_serialsarray of string · optional
differencenumber · optional

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

unit_cost_minorinteger (int64) · required
difference_value_minorinteger (int64) · required
counted_bystring · optional
counted_atstring (date-time) · optional
difference_value_minorinteger (int64) · required
created_atstring (date-time) · required
updated_atstring (date-time) · required
meter_idsarray of string · optional

Meters a receipt registered, in line order.

alertsarray of InventoryAlert · optional
Show child attributes
idstring · required

sal_ identifier

tenant_idstring · required
kindstring · required

one of negative_balance, below_reorder, short_for_planned

item_idstring · required
location_idstring · required
quantitynumber · required

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

levelnumber · optional

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

statusstring · required

one of open, resolved

movement_idstring · optional
created_atstring (date-time) · required
resolved_atstring (date-time) · optional

Errors 400 · 401 · 403 · 404 · 409

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

curl -X POST "$BUSINESS_API/inventory/adjustments" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "reason": "Leitura confirmada no local.",
  "lines": [
    {
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "serials": [
        "serial"
      ],
      "unit_cost_minor": 0
    }
  ]
}'
Response 201
{
  "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"
    }
  ],
  "transfer": {
    "id": "inv_2wMjl0ORXYUtt0UhtMAjLG4p9sC",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
    "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
    "status": "in_transit",
    "reason": "Leitura confirmada no local.",
    "lines": [
      {
        "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
        "quantity": 1,
        "serials": [
          "serial"
        ]
      }
    ],
    "created_by": "created by",
    "received_by": "received by",
    "created_at": "2026-11-19T09:30:00Z",
    "received_at": "2026-11-19T09:30:00Z"
  },
  "stocktake": {
    "id": "inv_24EVJwEl7uYvnWsNvQCjjGAh7m0",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
    "status": "counting",
    "reason": "Leitura confirmada no local.",
    "created_by": "created by",
    "frozen_at": "2026-11-19T09:30:00Z",
    "approved_by": "approved by",
    "approval_reason": "approval reason",
    "approved_at": "2026-11-19T09:30:00Z",
    "lines": [
      {
        "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
        "expected": 1,
        "expected_serials": [
          "expected serial"
        ],
        "counted": 1,
        "counted_serials": [
          "counted serial"
        ],
        "difference": 1,
        "unit_cost_minor": 1,
        "difference_value_minor": 1342,
        "counted_by": "counted by",
        "counted_at": "2026-11-19T09:30:00Z"
      }
    ],
    "difference_value_minor": 1342,
    "created_at": "2026-11-19T09:30:00Z",
    "updated_at": "2026-11-19T09:30:00Z"
  },
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "alerts": [
    {
      "id": "inv_2H3QUvtWWV98WDVE0D7m29HSOlh",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "negative_balance",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "level": 1,
      "status": "open",
      "movement_id": "mov_2xXIgdXcMfHmUBNcWnVo85VUmtl",
      "created_at": "2026-11-19T09:30:00Z",
      "resolved_at": "2026-11-19T09:30:00Z"
    }
  ]
}

Write off damaged stock

Logs

POST /inventory/scraps

Meter serials are scrapped through POST $BUSINESS_API/meters/{id}/device-status.

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

location_idstring · required
reasonstring · required
linesarray of InventoryMovementLine · required
Show child attributes
item_idstring · required
quantitynumber · optional

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

serialsarray of string · optional

Serial numbers of a serialised item; their count is the quantity.

unit_cost_minorinteger (int64) · optional

Receipts only: cost per unit

Returns

201 Scrap recorded

Show attributes
movementsarray of InventoryMovement · required
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
transferobject · optional
Show child attributes
idstring · required

xfr_ identifier

tenant_idstring · required
from_location_idstring · required
to_location_idstring · required
statusstring · required

one of in_transit, received

reasonstring · optional
linesarray of InventoryTransferLine · required
Show child attributes
item_idstring · required
quantitynumber · required

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

serialsarray of string · optional
created_bystring · required
received_bystring · optional
created_atstring (date-time) · required
received_atstring (date-time) · optional
stocktakeobject · optional
Show child attributes
idstring · required

stk_ identifier

tenant_idstring · required
location_idstring · required
statusstring · required

one of counting, approved

reasonstring · optional
created_bystring · required
frozen_atstring (date-time) · required
approved_bystring · optional
approval_reasonstring · optional
approved_atstring (date-time) · optional
linesarray of InventoryStocktakeLine · required
Show child attributes
item_idstring · required
expectednumber · required

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

expected_serialsarray of string · optional
countednumber · optional

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

counted_serialsarray of string · optional
differencenumber · optional

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

unit_cost_minorinteger (int64) · required
difference_value_minorinteger (int64) · required
counted_bystring · optional
counted_atstring (date-time) · optional
difference_value_minorinteger (int64) · required
created_atstring (date-time) · required
updated_atstring (date-time) · required
meter_idsarray of string · optional

Meters a receipt registered, in line order.

alertsarray of InventoryAlert · optional
Show child attributes
idstring · required

sal_ identifier

tenant_idstring · required
kindstring · required

one of negative_balance, below_reorder, short_for_planned

item_idstring · required
location_idstring · required
quantitynumber · required

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

levelnumber · optional

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

statusstring · required

one of open, resolved

movement_idstring · optional
created_atstring (date-time) · required
resolved_atstring (date-time) · optional

Errors 400 · 401 · 403 · 404 · 409

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

curl -X POST "$BUSINESS_API/inventory/scraps" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "reason": "Leitura confirmada no local.",
  "lines": [
    {
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "quantity": 1,
      "serials": [
        "serial"
      ],
      "unit_cost_minor": 0
    }
  ]
}'
Response 201
{
  "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"
    }
  ],
  "transfer": {
    "id": "inv_2wMjl0ORXYUtt0UhtMAjLG4p9sC",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
    "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
    "status": "in_transit",
    "reason": "Leitura confirmada no local.",
    "lines": [
      {
        "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
        "quantity": 1,
        "serials": [
          "serial"
        ]
      }
    ],
    "created_by": "created by",
    "received_by": "received by",
    "created_at": "2026-11-19T09:30:00Z",
    "received_at": "2026-11-19T09:30:00Z"
  },
  "stocktake": {
    "id": "inv_24EVJwEl7uYvnWsNvQCjjGAh7m0",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
    "status": "counting",
    "reason": "Leitura confirmada no local.",
    "created_by": "created by",
    "frozen_at": "2026-11-19T09:30:00Z",
    "approved_by": "approved by",
    "approval_reason": "approval reason",
    "approved_at": "2026-11-19T09:30:00Z",
    "lines": [
      {
        "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
        "expected": 1,
        "expected_serials": [
          "expected serial"
        ],
        "counted": 1,
        "counted_serials": [
          "counted serial"
        ],
        "difference": 1,
        "unit_cost_minor": 1,
        "difference_value_minor": 1342,
        "counted_by": "counted by",
        "counted_at": "2026-11-19T09:30:00Z"
      }
    ],
    "difference_value_minor": 1342,
    "created_at": "2026-11-19T09:30:00Z",
    "updated_at": "2026-11-19T09:30:00Z"
  },
  "meter_ids": [
    "mtr_21F02THKOD7uMpvUalZKsBv64nN"
  ],
  "alerts": [
    {
      "id": "inv_2H3QUvtWWV98WDVE0D7m29HSOlh",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "negative_balance",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "level": 1,
      "status": "open",
      "movement_id": "mov_2xXIgdXcMfHmUBNcWnVo85VUmtl",
      "created_at": "2026-11-19T09:30:00Z",
      "resolved_at": "2026-11-19T09:30:00Z"
    }
  ]
}

The append-only movement ledger

Logs

GET /inventory/movements

Pages the movements, each one a positive quantity moving into or out of a location (receipt, issue, return, transfer_out, transfer_in, adjustment or scrap). Use limit (default 20, max 100) and the after cursor. Filter by item_id, location_id (matches either side), kind, source_type, source_id, work_order_id, actor_id, and from/to (RFC 3339 or YYYY-MM-DD; from is inclusive, to is exclusive). Needs the inventory:read scope.

Parameters

item_idstring · query · optional

One item

location_idstring · query · optional

Movements from or to one location

kindstring · query · optional

Movement kind

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

source_typestring · query · optional

work_order, connection, meter, stocktake, transfer, receipt or other

source_idstring · query · optional

The source record

work_order_idstring · query · optional

Movements serving a work order's material lines

actor_idstring · query · optional

Who recorded it

fromstring · query · optional

Occurred at or after (RFC 3339 or YYYY-MM-DD)

tostring · query · optional

Occurred before (RFC 3339 or YYYY-MM-DD)

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Movements, newest first

Show attributes
dataarray of InventoryMovement · required
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
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/movements" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "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"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Where a meter or device is

Logs

GET /inventory/serials/{serial}

Where a meter or device is, and its history

Looks up a serial number (trimmed and matched in upper case) and returns its current status and location, its catalogue item, and every movement it took part in. Status is one of in_stock, in_transit, issued, installed, in_testing, scrapped or lost. Returns 404 when the serial is not registered in this tenant. Needs the inventory:read scope.

Parameters

serialstring · path · required

Serial number

Returns

200 Serial and its movements

Show attributes
serialobject · required
Show child attributes
idstring · required

ser_ identifier

tenant_idstring · required
item_idstring · required
serial_numberstring · required
statusstring · required

one of in_stock, in_transit, issued, installed, in_testing, scrapped, lost

location_idstring · optional
meter_idstring · optional
meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

source_typestring · optional
source_idstring · optional
unit_cost_minorinteger (int64) · required
created_atstring (date-time) · required
updated_atstring (date-time) · required
itemobject · 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
movementsarray of InventoryMovement · required
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

Errors 401 · 403 · 404

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

curl -X GET "$BUSINESS_API/inventory/serials/{serial}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "serial": {
    "id": "inv_2PHY0Z5QMxBeY3tSAjLSArbqe1Z",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
    "serial_number": "SER-2026-000142",
    "status": "in_stock",
    "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
    "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
    "meter_serial": "meter serial",
    "meter_holder_name": "Ana Matsinhe",
    "source_type": "source type",
    "source_id": "sou_2fjWEpPCsLRCQBV64hz26xd8MF9",
    "unit_cost_minor": 1,
    "created_at": "2026-11-19T09:30:00Z",
    "updated_at": "2026-11-19T09:30:00Z"
  },
  "item": {
    "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"
  },
  "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"
    }
  ]
}

Open holds and their ageing

Logs

GET /inventory/reservations

Pages the stock reservations, mostly ones work orders hold for their materials, with limit (default 20, max 100) and the after cursor. Filter by status (held, issued or released), location_id, item_id and work_order_id. Needs the inventory:read scope.

Parameters

statusstring · query · optional

held, issued or released

one of held, issued, released

location_idstring · query · optional

One location

item_idstring · query · optional

One item

work_order_idstring · query · optional

One work order

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Reservations

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

rsv_ identifier

tenant_idstring · required
item_idstring · required
location_idstring · required
quantitynumber · required

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

serial_idstring · optional
work_order_idstring · optional
material_line_idstring · optional

wml_ work-order material line

statusstring · required

one of held, issued, released

expires_atstring (date-time) · optional
created_bystring · required
release_reasonstring · optional
released_atstring (date-time) · optional
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/reservations" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "inv_25h0mvVwm3z0UVLyavt0YBZ6URl",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
      "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
      "material_line_id": "mat_2OqLrIeBheCpraGrhAOfvCsXF2k",
      "status": "held",
      "expires_at": "2026-11-19T09:30:00Z",
      "created_by": "created by",
      "release_reason": "release reason",
      "released_at": "2026-11-19T09:30:00Z",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Release a stale hold

Logs

POST /inventory/reservations/{id}/release

Frees a held reservation so its quantity counts as available again, and records the reason (required) and the release time. Only a reservation in status held can be released: an issued or already released one returns 409. Callers with only the inventory:van:write scope can release holds only in a van whose members include them. Send an Idempotency-Key header to make retries safe.

Parameters

idstring · path · required

Reservation ID (rsv_)

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

reasonstring · required

Returns

200 Reservation released

Show attributes
idstring · required

rsv_ identifier

tenant_idstring · required
item_idstring · required
location_idstring · required
quantitynumber · required

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

serial_idstring · optional
work_order_idstring · optional
material_line_idstring · optional

wml_ work-order material line

statusstring · required

one of held, issued, released

expires_atstring (date-time) · optional
created_bystring · required
release_reasonstring · optional
released_atstring (date-time) · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 401 · 403 · 404 · 409

Permissions inventory:van:write · Roles: admin, field_reader, owner

curl -X POST "$BUSINESS_API/inventory/reservations/{id}/release" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Leitura confirmada no local."
}'
Response 200
{
  "id": "inv_25h0mvVwm3z0UVLyavt0YBZ6URl",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "quantity": 1,
  "serial_id": "ser_2egPTiAVdkWtzeuzj8ALN2ybh0E",
  "work_order_id": "wko_2ecrvKOzr4kPhwgtrQAD7gM53yk",
  "material_line_id": "mat_2OqLrIeBheCpraGrhAOfvCsXF2k",
  "status": "held",
  "expires_at": "2026-11-19T09:30:00Z",
  "created_by": "created by",
  "release_reason": "release reason",
  "released_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

The stores work queue

Logs

GET /inventory/alerts

The stores work queue: negative balances and items below their reorder level

Returns the open and resolved stock alerts for the tenant, newest work first, paged with limit (default 20, max 100) and the after cursor. An alert has kind negative_balance (raised when a movement takes a location that allows negative stock below zero), below_reorder (raised by the daily reorder scan) or short_for_planned (planned work orders need more than is available). Filter with kind and status (open or resolved). Needs the inventory:read scope.

Parameters

kindstring · query · optional

negative_balance, below_reorder or short_for_planned

one of negative_balance, below_reorder, short_for_planned

statusstring · query · optional

open or resolved

one of open, resolved

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Alerts

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

sal_ identifier

tenant_idstring · required
kindstring · required

one of negative_balance, below_reorder, short_for_planned

item_idstring · required
location_idstring · required
quantitynumber · required

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

levelnumber · optional

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

statusstring · required

one of open, resolved

movement_idstring · optional
created_atstring (date-time) · required
resolved_atstring (date-time) · optional
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/alerts" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "inv_2H3QUvtWWV98WDVE0D7m29HSOlh",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "kind": "negative_balance",
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
      "quantity": 1,
      "level": 1,
      "status": "open",
      "movement_id": "mov_2xXIgdXcMfHmUBNcWnVo85VUmtl",
      "created_at": "2026-11-19T09:30:00Z",
      "resolved_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Import an opening stock or a delivery note from CSV

Logs

POST /inventory/receipts/import

Import an opening stock or a delivery note from CSV, with a dry run

Columns item_code (or item_id), quantity, unit_cost_minor, serials (serialised items, separated by | or spaces), location_code (or the location_id parameter) and reference; commas or semicolons, with a header row. Every row is checked first: a dry run, or a file with any row in error, writes nothing and answers with each row's errors. A commit receives one receipt per location; the same file imported again records once (the key is the Idempotency-Key, or the file's digest). Meter rows also register each meter.

Parameters

dry_runboolean · query · optional

Check every row and report errors without writing anything

location_idstring · query · optional

Receiving location for rows that name none

referencestring · query · optional

Delivery note reference for rows that name none

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 · 404 · 409 · 413 · 422

Permissions inventory:write · Roles: admin, field_supervisor, operations, owner

curl -X POST "$BUSINESS_API/inventory/receipts/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 movement ledger as plain CSV, for an ERP

Logs

GET /inventory/movements/export

Oldest first within the filters; at most 100000 movements per export, so narrow the dates for more. The last two columns tie each row to the ledger: stock_value_change_minor is what the movement posted to the stock on hand account, and ledger_source_reference is the source reference of its journal entry (empty for a transfer, which posts nothing).

Parameters

item_idstring · query · optional

Only movements of this catalogue item ID.

location_idstring · query · optional

Only movements into or out of this location ID; it matches either the source or the destination location.

kindstring · query · optional

Only movements of this kind: receipt, issue, return, transfer_out, transfer_in, adjustment or scrap.

source_typestring · query · optional

Only movements pointing at this kind of source, such as work_order, connection, meter, stocktake, transfer, receipt or other.

source_idstring · query · optional

Only movements pointing at this source record ID, usually combined with source_type.

work_order_idstring · query · optional

Only movements tied to this work order ID.

actor_idstring · query · optional

Only movements recorded by this user ID.

fromstring (date-time) · query · optional

Inclusive lower bound on the time the movement occurred, as an RFC 3339 timestamp or a YYYY-MM-DD date (midnight UTC); any other format returns 400.

tostring (date-time) · query · optional

Exclusive upper bound on the time the movement occurred, as an RFC 3339 timestamp or a YYYY-MM-DD date (midnight UTC, so that day is left out); any other format returns 400.

Returns

200 text/csv: occurred_at, movement_id, kind, item_code, item_name, unit, quantity, from_location_code, to_location_code, serial_number, unit_cost_minor, total_cost_minor, reason, source_type, source_id, work_order_id, material_line_id, reference, actor_id

Errors 400 · 401 · 403

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

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

text/csv: occurred_at, movement_id, kind, item_code, item_name, unit, quantity, from_location_code, to_location_code, serial_number, unit_cost_minor, total_cost_minor, reason, source_type, source_id, work_order_id, material_line_id, reference, actor_id

Get inventory settings

Logs

GET /inventory/settings

The utility's inventory settings, such as the re-dispatch hold period

Returns the tenant's inventory settings, currently redispatch_hold_days: how long reservations stay held after a work order fails because access was denied, waiting for it to be dispatched again. It also shows who last changed the settings and when. Needs the inventory:read scope.

Returns

200 Settings

Show attributes
tenant_idstring · required
redispatch_hold_daysinteger · required

Days a failed_access_denied order keeps its reservations before they are released

updated_bystring · optional
updated_atstring (date-time) · 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/settings" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "redispatch_hold_days": 1,
  "updated_by": "updated by",
  "updated_at": "2026-11-19T09:30:00Z"
}

Change how long a failed visit keeps its reservations

Logs

PATCH /inventory/settings

Change how long a failed visit keeps its reservations (14 days by default)

Sets redispatch_hold_days, which must be between 1 and 365 (400 otherwise), and records the caller as the last editor. Leaving the field out keeps the current value. Needs the inventory:supervise scope; 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

redispatch_hold_daysinteger · optional

Returns

200 Settings

Show attributes
tenant_idstring · required
redispatch_hold_daysinteger · required

Days a failed_access_denied order keeps its reservations before they are released

updated_bystring · optional
updated_atstring (date-time) · optional

Errors 400 · 401 · 403 · 409

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

curl -X PATCH "$BUSINESS_API/inventory/settings" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "redispatch_hold_days": 1
}'
Response 200
{
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "redispatch_hold_days": 1,
  "updated_by": "updated by",
  "updated_at": "2026-11-19T09:30:00Z"
}