Inventory: Transfers

Base URL: $BUSINESS_API

List transfers

Logs

GET /inventory/transfers

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

Parameters

statusstring · query · optional

in_transit or received

one of in_transit, received

location_idstring · query · optional

Transfers from or to one location

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Transfers

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

Send stock to another location

Logs

POST /inventory/transfers

Send stock to another location; it stays in transit until received

Takes stock out of one active location with transfer_out movements and creates a transfer in status in_transit to another location, responding with status 201. The two locations must differ, and serialised lines must list serials in stock at the source. The reason defaults to a standard stock-transfer text. Returns 409 when the source lacks available stock. Callers with only the inventory:van:write scope can send only from 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

from_location_idstring · required
to_location_idstring · required
reasonstring · 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 Transfer in transit

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/transfers" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "from_location_id": "fro_2sm5hEQzXUAJ1CYZtw8N5CCTD2C",
  "to_location_id": "tol_23fOE93yijRwmVXyGxTMyDdgE5L",
  "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"
    }
  ]
}

Get a transfer

Logs

GET /inventory/transfers/{id}

Returns one transfer with its source and destination, its lines and serials, its status, and who created and received it. Returns 404 when the transfer does not exist in this tenant. Needs the inventory:read scope.

Parameters

idstring · path · required

Transfer ID (xfr_)

Returns

200 Transfer

Show 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

Errors 401 · 403 · 404

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

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

Confirm a transfer at the receiving location

Logs

POST /inventory/transfers/{id}/receive

Books the transfer's lines into the destination location as transfer_in movements, puts its serials back in stock there, and marks the transfer received by the caller. The request takes no body. A transfer that was already received returns 409. Callers with only the inventory:van:write scope can receive only into a van whose members include them. Send an Idempotency-Key header to make retries safe.

Parameters

idstring · path · required

Transfer ID (xfr_)

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.

Returns

200 Transfer received

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 401 · 403 · 404 · 409

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

curl -X POST "$BUSINESS_API/inventory/transfers/{id}/receive" \
  -H "Authorization: Bearer sk_test_..."
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"
    }
  ]
}