Inventory

List product inventory

get

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

Query

• search (optional) — case-insensitive substring match on the product 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_name, cell_name, warehouse_status, warehouse_purpose), product identity (product_name, product_configuration, product_variants, sku, barcode), quantity + status (number_of_items, product_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 product 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/products

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

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

Add product 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).

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.

• products[] — each item:

  • product_variant_id — product variant id (not product id and not product-meta id). The server resolves the parent product-meta automatically.

  • quantity — positive number.

  • 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/products

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

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

{
  "document_id": "123e4567-e89b-12d3-a456-426614174000",
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "inventory_key": "text",
      "product_variant_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 product 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, product_variant_id, quantity, status, warehouse_id, cell_id (division id), and production_key when the batch was created from a workflow.

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".

product_variant_idstring · uuid · nullableOptional

Product variant id.

quantitynumberRequired

Current on-hand quantity.

statusstring · enumRequiredPossible values:

warehouse_idstring · uuid · nullableOptional

cell_idstring · uuid · nullableOptional

Warehouse division id (aliased "cell_id" in older docs).

production_keystring · nullableOptional

Source production workflow key, if the batch was produced by one.

429

Returned when the rate limit is exceeded

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

GET /api/v1/public/inventory/products/{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",
    "product_variant_id": "123e4567-e89b-12d3-a456-426614174000",
    "quantity": 1,
    "status": "pending",
    "warehouse_id": "123e4567-e89b-12d3-a456-426614174000",
    "cell_id": "123e4567-e89b-12d3-a456-426614174000",
    "production_key": "text"
  }
]

Move product 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.

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.

• products[] — each item: inventory_key, quantity, destination warehouse_id, optional division_id.

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/products/move

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

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

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

Write off product stock

post

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

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 attributes the write-off to a production workflow (400 if the key is unknown).

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.

• products[] — each item: inventory_key, quantity, optional production_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/products/write-off

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

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

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