Inventory: Stocktakes

Base URL: $BUSINESS_API

List stocktakes

Logs

GET /inventory/stocktakes

Pages the stocktakes with limit (default 20, max 100) and the after cursor. Filter by location_id and by status (counting or approved). Needs the inventory:read scope.

Parameters

location_idstring · query · optional

One location

statusstring · query · optional

counting or approved

one of counting, approved

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Stocktakes

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

Open a count, freezing the expected quantities of a location

Logs

POST /inventory/stocktakes

Opens a stocktake in status counting at an active location, returned with status 201. It records a line for every item with a non-zero balance there, holding the expected quantity, the expected serials for serialised items, and the item's average cost. A reason is optional. Callers with only the inventory:van:write scope can open one only in 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
reasonstring · optional

Returns

201 Stocktake opened

Show 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

Errors 400 · 401 · 403 · 404 · 409

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

curl -X POST "$BUSINESS_API/inventory/stocktakes" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "location_id": "loc_2NbCeVvmOLLm0vFE4ZvkGRtMsrx",
  "reason": "Leitura confirmada no local."
}'
Response 201
{
  "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"
}

Get a stocktake with expected, counted and differences

Logs

GET /inventory/stocktakes/{id}

Returns one stocktake with its status, its lines with the expected and counted quantities and serials, who counted each line, and the approval details once approved. Returns 404 when the stocktake does not exist in this tenant. Needs the inventory:read scope.

Parameters

idstring · path · required

Stocktake ID (stk_)

Returns

200 Stocktake

Show 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

Errors 401 · 403 · 404

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

curl -X GET "$BUSINESS_API/inventory/stocktakes/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "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"
}

Record counted lines

Logs

POST /inventory/stocktakes/{id}/lines

Records 1 to 500 counted lines on a stocktake still in status counting (409 once approved) and returns the updated stocktake. Count bulk items with a quantity of zero or more. Count serialised items by scanning their serials, where the quantity is the number of distinct serials. An item may appear only once per request, and counting it again later replaces the earlier count. The caller is recorded as the counter of each line. Send an Idempotency-Key header to make retries safe.

Parameters

idstring · path · required

Stocktake ID (stk_)

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

linesarray of object · required
Show child attributes
item_idstring · required
countednumber · optional

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

serialsarray of string · optional

Scanned serials; for a serialised item they are the count.

Returns

200 Stocktake with the counts

Show 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

Errors 400 · 401 · 403 · 404 · 409

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

curl -X POST "$BUSINESS_API/inventory/stocktakes/{id}/lines" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "lines": [
    {
      "item_id": "itm_2vLmKDHWenXi6Pxs8hv8WJHGW53",
      "counted": 1,
      "serials": [
        "serial"
      ]
    }
  ]
}'
Response 200
{
  "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"
}

Approve the differences as adjustment movements

Logs

POST /inventory/stocktakes/{id}/approve

Turns each counted line's difference from the expected quantity into adjustment movements and marks the stocktake approved. Needs the inventory:supervise scope and a reason. The approver must be someone other than whoever opened the stocktake or counted any line (403). Returns 409 when the stocktake is already approved, when nothing was counted, when expected meters are missing (scrap or locate them first), or when a found serial is registered elsewhere. Send an Idempotency-Key header to make retries safe.

Parameters

idstring · path · required

Stocktake ID (stk_)

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 Stocktake approved

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/stocktakes/{id}/approve" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Leitura confirmada no local."
}'
Response 200
{
  "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"
    }
  ]
}