Inventory Materials

List material inventory

get

Returns material-inventory rows across every warehouse on the tenant, cursor-paginated.

Query

• search (optional) — case-insensitive substring match on the material name.

• warehouse_id (optional) — restrict to a single warehouse.

• status (optional) — restrict to batches in a given status (in_stock, reserved, shipped, etc.).

• cursor (optional) — opaque cursor from the previous response's pagination.cursor; omit for the first page.

• take (optional) — page size; defaults to 25, capped at 100.

Response

Each row carries the batch's identity (id, inventory_key), location (warehouse_id, warehouse_name, warehouse_status, warehouse_purpose, division_id, cell_name), material identity (material_name, material_external_id, category, subcategory, actual_price_per_unit, uom), quantity + status (quantity, material_status), and provenance (production_key, task_key, number_of_actions, comment).

Follow pagination.cursor for the next page; pagination.hasNextPage = false signals the end of the stream.

Authorizations

x-api-keystringRequired

Query parameters

searchstring · max: 255Optional

Case-insensitive substring match on material name.

warehouse_idstring · uuidOptional

Filter by warehouse UUID.

statusstring · enumOptional

Filter by batch status.

Possible values:

cursorstringOptional

Cursor from a previous response for the next page. Omit for the first page.

takenumber · min: 1 · max: 100Optional

Page size. Defaults to 25.

Default: 25

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Responses

200Success

application/json

429

Returned when the rate limit is exceeded

get/api/v1/public/inventory/materials

GET /api/v1/public/inventory/materials HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Accept: */*

{
  "pagination": {
    "hasNextPage": true,
    "cursor": "text"
  }
}

Add material stock

post

Creates one receipt document and one batch per line item — a single request adds N rows to the same warehouse. Every batch gets a freshly generated inventory_key (server-side; you don't supply it). Decimal quantities are allowed for materials.

Body

• warehouse_id — destination warehouse. Required.

• division_id — destination division. Required when the warehouse's storage_type is not default; ignored otherwise. Applied to every item in the request.

• comment — attached to the receipt document.

• materials[] — each item:

  • material_id — material id.

  • quantity — positive number, decimals allowed.

  • actual_purchase_price — optional per-unit purchase price recorded on the receipt.

  • production_key — optional. When present, the batch is linked to that workflow as its source (400 if the key is unknown).

Response

Returns { document_id, data: [...] } — document_id is the receipt document that groups the batches, data mirrors each request line with the created id + generated inventory_key.

Authorizations

x-api-keystringRequired

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Body

warehouse_idstring · uuidRequired

Destination warehouse id.

division_idstring · uuidOptional

Destination division id. Required for warehouses whose storage_type is not "default".

commentstring · max: 1000Optional

Free-form comment attached to the receipt document.

Responses

201Success

application/json

document_idstring · uuidRequired

Id of the receipt document that groups the created batches.

429

Returned when the rate limit is exceeded

post/api/v1/public/inventory/materials

POST /api/v1/public/inventory/materials HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 257

{
  "warehouse_id": "123e4567-e89b-12d3-a456-426614174000",
  "division_id": "123e4567-e89b-12d3-a456-426614174000",
  "comment": "text",
  "materials": [
    {
      "material_id": "123e4567-e89b-12d3-a456-426614174000",
      "quantity": 1,
      "actual_purchase_price": 1,
      "production_key": "text"
    }
  ]
}

{
  "document_id": "123e4567-e89b-12d3-a456-426614174000",
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "inventory_key": "text",
      "material_id": "123e4567-e89b-12d3-a456-426614174000",
      "quantity": 1,
      "status": "pending",
      "warehouse_id": "123e4567-e89b-12d3-a456-426614174000",
      "division_id": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}

Get material inventory rows by inventory_key

get

Returns every batch row that carries the given inventory_key (internal batch_number). Multiple rows can share an inventory_key after splits — e.g. a partial transfer creates a child row in the destination warehouse but the parent row keeps the same key. The response is a flat array (no pagination), typically 1–3 entries.

Each entry surfaces the row's id, inventory_key, material_id, material_name, quantity, uom, status, warehouse_id, and division_id.

Authorizations

x-api-keystringRequired

Path parameters

keystringRequired

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Responses

200Success

application/json

idstring · uuidRequired

Internal batch id.

inventory_keystringRequired

Batch number — the public "inventory_key".

material_idstring · uuid · nullableOptional

material_namestring · nullableOptional

quantitynumberRequired

Current on-hand quantity.

uomstring · nullableOptional

Measurement unit name.

statusstring · enumRequiredPossible values:

warehouse_idstring · uuid · nullableOptional

division_idstring · uuid · nullableOptional

429

Returned when the rate limit is exceeded

get/api/v1/public/inventory/materials/{key}

GET /api/v1/public/inventory/materials/{key} HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Accept: */*

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "inventory_key": "text",
    "material_id": "123e4567-e89b-12d3-a456-426614174000",
    "material_name": "text",
    "quantity": 1,
    "uom": "text",
    "status": "pending",
    "warehouse_id": "123e4567-e89b-12d3-a456-426614174000",
    "division_id": "123e4567-e89b-12d3-a456-426614174000"
  }
]

Move material stock between warehouses

post

Moves stock from the batch's current location to a destination warehouse (and optionally division). Creates one change-log document per request, capturing source, destination, quantity, and comment. Decimal quantities are allowed.

Behavior

• Partial moves (quantity < batch.current qty) split the row: the source batch keeps the remainder, a new child batch is created at the destination with the transferred quantity. The child inherits the parent's inventory_key.

• Full moves (quantity === batch.current qty) change the batch's warehouse_id in-place — no split.

• Rejected when quantity <= 0 or quantity > batch.current qty.

inventory_key disambiguation

The public inventory_key maps to the internal batch_number. In rare cases (post-split scenarios) multiple batches can share the same inventory_key. This endpoint requires inventory_key to resolve to exactly one batch with status in_stock:

• Zero matches → 404.

• Multiple matches → 400 with a message listing candidate batches.

Body

• comment — attached to the change-log document.

• materials[] — each item: inventory_key, quantity, destination warehouse_id, optional cell_id (destination division).

Response

{ message, document_id }. Follow document_id on a future changelog endpoint to inspect the per-batch effects.

Authorizations

x-api-keystringRequired

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Body

commentstring · max: 1000Optional

Free-form comment attached to the change-log document.

Responses

200Success

application/json

messagestringRequired

Human-readable confirmation message.

document_idstring · uuidRequired

Id of the change-log document created by this operation.

429

Returned when the rate limit is exceeded

post/api/v1/public/inventory/materials/move

POST /api/v1/public/inventory/materials/move HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 173

{
  "comment": "text",
  "materials": [
    {
      "inventory_key": "text",
      "quantity": 1,
      "warehouse_id": "123e4567-e89b-12d3-a456-426614174000",
      "cell_id": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}

{
  "message": "text",
  "document_id": "123e4567-e89b-12d3-a456-426614174000"
}

Write off material stock

post

Writes stock off from an in-stock batch. Creates one change-log document per request. Decimal quantities are allowed.

Behavior

• Only batches with status in_stock can be written off. Batches already shipped / written_off are rejected with 400.

• Partial write-offs (quantity < batch.current qty) split the row: the source keeps the remainder, a new child batch is created carrying the written-off quantity and moved into the written_off state.

• Full write-offs (quantity === batch.current qty) flip the batch's status in-place.

• Optional production_key / task_key attribute the write-off. Rules:

  • If task_key is provided without production_key, the workflow is auto-populated from the task.

  • If both are provided, the task must belong to the resolved production (400 on mismatch).

  • Unknown production_key or task_key → 400.

inventory_key disambiguation

The public inventory_key maps to the internal batch_number. In rare cases (post-split scenarios) multiple batches can share the same inventory_key. This endpoint requires inventory_key to resolve to exactly one batch with status in_stock:

• Zero matches → 404.

• Multiple matches → 400 with a message listing candidate batches.

Body

• comment — attached to the change-log document.

• materials[] — each item: inventory_key, quantity, optional production_key, optional task_key.

Response

{ message, document_id }.

Authorizations

x-api-keystringRequired

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Body

commentstring · max: 1000Optional

Free-form comment attached to the change-log document.

Responses

200Success

application/json

messagestringRequired

Human-readable confirmation message.

document_idstring · uuidRequired

Id of the change-log document created by this operation.

429

Returned when the rate limit is exceeded

post/api/v1/public/inventory/materials/write-off

POST /api/v1/public/inventory/materials/write-off HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 112

{
  "comment": "text",
  "materials": [
    {
      "inventory_key": "text",
      "quantity": 1,
      "production_key": "text",
      "task_key": "text"
    }
  ]
}

{
  "message": "text",
  "document_id": "123e4567-e89b-12d3-a456-426614174000"
}