Inventory: Locations

Base URL: $BUSINESS_API

List warehouses, shelf areas and vans

Logs

GET /inventory/locations

Pages the tenant's stock locations with limit (default 20, max 100) and the after cursor. Filter by kind (warehouse, area or van), crew_id and active, and search with q. Needs the inventory:read scope.

Parameters

kindstring · query · optional

warehouse, area or van

one of warehouse, area, van

crew_idstring · query · optional

Vans of one crew

activeboolean · query · optional

Only active or inactive locations

qstring · query · optional

Resource-specific text search.

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Locations

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

loc_ identifier

tenant_idstring · required
codestring · required
namestring · required
kindstring · required

one of warehouse, area, van

parent_idstring · optional
crew_idstring · optional
service_area_idstring · optional
member_user_idsarray of string · required

People who may move stock at this van with inventory:van:write.

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

Errors 400 · 401 · 403

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

curl -X GET "$BUSINESS_API/inventory/locations" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "inv_2WehDooBVEGDrYkt5EGLxWsLPWG",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "code": "COD-2026-000142",
      "name": "Ana Matsinhe",
      "kind": "warehouse",
      "parent_id": "par_2AuL9gszLEORhAwTnkAPpacTF66",
      "crew_id": "crw_2l1wOJtgejFoQBJcG9bsknLKyxp",
      "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
      "member_user_ids": [
        "mem_2uI9XcKnDo2tFQmRNWcXt0CLT4K"
      ],
      "allow_negative": true,
      "is_default": true,
      "active": true,
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Create a warehouse, shelf area or van

Logs

POST /inventory/locations

Creates a stock location, returned with status 201. code (stored upper case, unique per tenant) and name are required; kind defaults to warehouse, and an area needs parent_id naming a warehouse. A crew_id must name an existing crew. member_user_ids list the users who may move stock in a van with only the inventory:van:write scope, and allow_negative lets the balance go below zero (raising an alert) instead of refusing the movement. Needs the inventory:supervise scope; a duplicate code returns 409. Send an Idempotency-Key header to make retries safe.

Parameters

Idempotency-Keystring · header · optional

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

Body application/json

codestring · required
namestring · required
kindstring · optional · default warehouse

one of warehouse, area, van

parent_idstring · optional

Parent warehouse of a shelf area

crew_idstring · optional
service_area_idstring · optional
member_user_idsarray of string · optional
allow_negativeboolean · optional

Returns

201 Location created

Show attributes
idstring · required

loc_ identifier

tenant_idstring · required
codestring · required
namestring · required
kindstring · required

one of warehouse, area, van

parent_idstring · optional
crew_idstring · optional
service_area_idstring · optional
member_user_idsarray of string · required

People who may move stock at this van with inventory:van:write.

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

Errors 400 · 401 · 403 · 409

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

curl -X POST "$BUSINESS_API/inventory/locations" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "kind": "warehouse",
  "parent_id": "par_2AuL9gszLEORhAwTnkAPpacTF66",
  "crew_id": "crw_2l1wOJtgejFoQBJcG9bsknLKyxp",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "member_user_ids": [
    "mem_2uI9XcKnDo2tFQmRNWcXt0CLT4K"
  ],
  "allow_negative": true
}'
Response 201
{
  "id": "inv_2WehDooBVEGDrYkt5EGLxWsLPWG",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "kind": "warehouse",
  "parent_id": "par_2AuL9gszLEORhAwTnkAPpacTF66",
  "crew_id": "crw_2l1wOJtgejFoQBJcG9bsknLKyxp",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "member_user_ids": [
    "mem_2uI9XcKnDo2tFQmRNWcXt0CLT4K"
  ],
  "allow_negative": true,
  "is_default": true,
  "active": true,
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Get a location

Logs

GET /inventory/locations/{id}

Returns one location of the caller's tenant: its kind, parent warehouse, crew, service area, van members and whether it allows negative stock. Returns 404 when the location does not exist in this tenant. Needs the inventory:read scope.

Parameters

idstring · path · required

Location ID (loc_)

Returns

200 Location

Show attributes
idstring · required

loc_ identifier

tenant_idstring · required
codestring · required
namestring · required
kindstring · required

one of warehouse, area, van

parent_idstring · optional
crew_idstring · optional
service_area_idstring · optional
member_user_idsarray of string · required

People who may move stock at this van with inventory:van:write.

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

Errors 401 · 403 · 404

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

curl -X GET "$BUSINESS_API/inventory/locations/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "inv_2WehDooBVEGDrYkt5EGLxWsLPWG",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "kind": "warehouse",
  "parent_id": "par_2AuL9gszLEORhAwTnkAPpacTF66",
  "crew_id": "crw_2l1wOJtgejFoQBJcG9bsknLKyxp",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "member_user_ids": [
    "mem_2uI9XcKnDo2tFQmRNWcXt0CLT4K"
  ],
  "allow_negative": true,
  "is_default": true,
  "active": true,
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

Change a location, its crew and van members

Logs

PATCH /inventory/locations/{id}

Changes only the fields you send: name, crew_id (must name an existing crew), service_area_id, member_user_ids (replaces the list), allow_negative and active. The default warehouse cannot be deactivated (409). Code, kind and parent cannot be changed. Needs the inventory:supervise scope; send an Idempotency-Key header to make retries safe.

Parameters

idstring · path · required

Location ID (loc_)

Idempotency-Keystring · header · optional

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

Body application/json

namestring · optional
crew_idstring · optional
service_area_idstring · optional
member_user_idsarray of string · optional
allow_negativeboolean · optional
activeboolean · optional

Returns

200 Location updated

Show attributes
idstring · required

loc_ identifier

tenant_idstring · required
codestring · required
namestring · required
kindstring · required

one of warehouse, area, van

parent_idstring · optional
crew_idstring · optional
service_area_idstring · optional
member_user_idsarray of string · required

People who may move stock at this van with inventory:van:write.

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

Errors 400 · 401 · 403 · 404 · 409

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

curl -X PATCH "$BUSINESS_API/inventory/locations/{id}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "crew_id": "crw_2l1wOJtgejFoQBJcG9bsknLKyxp",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "member_user_ids": [
    "mem_2uI9XcKnDo2tFQmRNWcXt0CLT4K"
  ],
  "allow_negative": true,
  "active": true
}'
Response 200
{
  "id": "inv_2WehDooBVEGDrYkt5EGLxWsLPWG",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "kind": "warehouse",
  "parent_id": "par_2AuL9gszLEORhAwTnkAPpacTF66",
  "crew_id": "crw_2l1wOJtgejFoQBJcG9bsknLKyxp",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "member_user_ids": [
    "mem_2uI9XcKnDo2tFQmRNWcXt0CLT4K"
  ],
  "allow_negative": true,
  "is_default": true,
  "active": true,
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}