Warehouses

Warehouses and stock — the Warehouse object, stock levels with valuation, batches, manual adjustments, goods receipts, movement history and returns of order products.

A warehouse keeps stock of materials and finished products. Stock changes through:

  • manual adjustments, see Adjust Stock;
  • receipts, which bring several items in at once, see Create Receipt;
  • automations on order status changes, which write off materials or put finished products into stock (see Automations);
  • returns, which roll back production for an order, see Return Order Products.

Every change is recorded in the warehouse's history. Stock can never go below zero; a movement that would do so is rejected as a whole.

Stock is kept in batches, see Batches: every income is a batch with its own unit cost and number, and spending takes from the oldest batch first.

A project always has exactly one default warehouse. Automations configured with "default warehouse" use it.

Field types follow the field notation.

Access

Every endpoint on this page requires both the projects and warehouses OAuth scopes. The user must be a member of the project, and the owner's subscription must be active. Otherwise the endpoint returns 404 RES_NOT_FOUND. The project owner bypasses permission checks.

Permission Grants
can_view_warehouses Read warehouses, stock, receipts, history and return candidates
can_edit_warehouses Everything else on this page
can_view_purchase_price See stock valuation (value, total_value)

Warehouse Object

Warehouse Structure

Field Type Description
uuid uuid Warehouse ID
name string Name, 1–255 characters
is_default boolean Whether this is the project's default warehouse
address string Address
phone string Phone, up to 32 characters
note string Free text
created_at ISO8601 datetime When the warehouse was created
updated_at ISO8601 datetime When the warehouse was last changed

Example Warehouse

{
  "uuid": "0199a0b1-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
  "name": "Main warehouse",
  "is_default": true,
  "address": "12 Industrial Rd, Springfield",
  "phone": "",
  "note": "",
  "created_at": "2026-07-20T09:00:00.000Z",
  "updated_at": "2026-07-20T09:00:00.000Z"
}

List Warehouses

GET /api/v1/projects/{project.uuid}/warehouses

Returns the project's warehouses, the default first, then oldest first.

Requires can_view_warehouses.

Get Warehouse

GET /api/v1/projects/{project.uuid}/warehouses/{warehouse.uuid}

Requires can_view_warehouses.

Create Warehouse

POST /api/v1/projects/{project.uuid}/warehouses

The project's first warehouse always becomes the default.

Requires can_edit_warehouses.

JSON Params

Field Type Description
name string 1–255 characters
is_default? boolean Make this the default warehouse. Default false
address? string Default ""
phone? string Up to 32 characters. Default ""
note? string Default ""

Response

201 Created

{
  "uuid": "0199a0b1-3c4d-7e5f-8a9b-0c1d2e3f4a5b"
}

Modify Warehouse

PATCH /api/v1/projects/{project.uuid}/warehouses/{warehouse.uuid}

Updates any of name, is_default, address, phone, note. At least one must be present. is_default: true moves the default here. Sending is_default: false to the default warehouse is rejected; make another warehouse the default instead.

Requires can_edit_warehouses.

Response

204 No Content

Replace Warehouse

PUT /api/v1/projects/{project.uuid}/warehouses/{warehouse.uuid}

Same as Modify Warehouse, but every field is required.

Delete Warehouse

DELETE /api/v1/projects/{project.uuid}/warehouses/{warehouse.uuid}

Deletes the warehouse with all its stock, receipts and history. Automations that referred to it are switched to the default warehouse. Deleting the default warehouse makes the oldest remaining one the default.

Requires can_edit_warehouses.

Response

204 No Content

Stock

Stock Item Structure

Field Type Description
uuid uuid Stock row ID
item_type string material or product
item_uuid uuid The material or product
name ?string Its name; null if it was deleted
unit ?string Its unit
quantity decimal Quantity in stock, never negative
min_stock decimal Threshold for the low-stock report; 0 disables it
batch_count integer Number of non-empty batches
value? decimal Σ batch quantity × batch unit cost. Present only with can_view_purchase_price
updated_at ISO8601 datetime When the row last changed

List Stock

GET /api/v1/projects/{project.uuid}/warehouses/{warehouse.uuid}/stocks

Returns a page of stock items: materials first, then products, each by name.

Requires can_view_warehouses.

Query String Params

Field Type Description
page? integer Page number, from 1. Default 1
limit? integer Page size, 1–100. Default 50
filters? string A URL-encoded JSON array of {"field", "operator", "value"}; all combine with AND
field operator Matches
name equal, include, starts_with, is_empty (case-sensitive) Item name
item_type — material or product
quantity, min_stock equal, greater, less Numeric comparison

Response

200 OK

{
  "data": [
    {
      "uuid": "0199a0d0-0000-7000-8000-000000000001",
      "item_type": "material",
      "item_uuid": "0199a2c0-7a1b-7c2d-8e3f-a0b1c2d3e4f5",
      "name": "Blackout 605",
      "unit": "sm",
      "quantity": 120.5,
      "min_stock": 20,
      "batch_count": 2,
      "value": 506.1,
      "updated_at": "2026-09-30T14:00:00.000Z"
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 1,
  "total_pages": 1,
  "total_value": 506.1
}

total_value is the value of all stock matching the filters, not just this page; null without can_view_purchase_price.

Adjust Stock

POST /api/v1/projects/{project.uuid}/warehouses/{warehouse.uuid}/stocks

Adds to or subtracts from one item's stock. Recorded in the history as a manual movement.

Without batch_uuid, adding creates a new batch and subtracting takes from the oldest batches first (a cut_whole material: the whole amount from the smallest batch that fits). With it, the amount is added to or taken from that batch only.

Requires can_edit_warehouses.

JSON Params

Field Type Description
item_type string material or product
item_uuid uuid The material or product
amount decimal Positive to add, negative to subtract; not 0
note? string Reason for the adjustment, up to 500 characters. Default ""
batch_uuid? ?uuid A batch of this item in this warehouse
batch_number? string Adding without batch_uuid: the new batch's number, up to 64 characters
unit_cost? ?decimal Adding without batch_uuid: the new batch's unit cost, ≥ 0. Default: the item's current purchase price

Example Request

{
  "item_type": "material",
  "item_uuid": "0199a2c0-7a1b-7c2d-8e3f-a0b1c2d3e4f5",
  "amount": -2.5,
  "note": "Offcut damaged"
}

Response

204 No Content. Subtracting more than is in stock, or in the given batch, fails with 409 WAREHOUSE_INSUFFICIENT_STOCK.

Set Minimum Stock

PATCH /api/v1/projects/{project.uuid}/warehouses/{warehouse.uuid}/stocks

Sets the low-stock threshold for an item that already has a stock row.

Requires can_edit_warehouses.

Field Type Description
item_type string material or product
item_uuid uuid The material or product
min_stock decimal ≥ 0

204 No Content, or 404 RES_NOT_FOUND if the item has never been in this warehouse.

Batches

A batch is one income of an item into a warehouse: a receipt line, a manual addition or finished products put into stock by an automation. It keeps its unit cost, so a later change of the purchase price doesn't revalue what is already in stock. Spending takes from the oldest batch first (FIFO) unless a batch is chosen; a return puts materials back into the batches they were spent from.

A material with cut_whole (fabric, film — see Materials) is never assembled from pieces of several batches: each cut is taken whole from the smallest batch it fits in, so offcuts are used up before a fresh roll is started. With 2 m, 3.5 m and 10 m left in three batches, a 4 m cut comes from the 10 m batch. If no batch fits a cut, the spend fails with insufficient stock even when the batches add up to enough.

Batch Structure

Field Type Description
uuid uuid Batch ID
number string Lot or roll number; "" if none
quantity decimal What is left
quantity_initial decimal What came in
unit_cost? decimal Cost per unit. Present only with can_view_purchase_price
receipt_uuid ?uuid The receipt it came with
receipt_number ?string That receipt's number
created_at ISO8601 datetime When it came in

List Batches

GET /api/v1/projects/{project.uuid}/warehouses/{warehouse.uuid}/batches

Returns one item's batches in the order they are spent, oldest first. The response is a plain array.

Requires can_view_warehouses.

Query String Params

Field Type Description
item_type string material or product
item_uuid uuid The material or product
all? string 1 to include empty batches. Default 0

Receipts

A receipt brings several items into a warehouse in one document, e.g. a supplier's delivery note. All its items are added in one transaction. Receipts cannot be edited or deleted. A receipt whose stock hasn't moved since can be canceled as a whole; otherwise correct a mistake with Adjust Stock.

Receipt Structure

Field Type Description
uuid uuid Receipt ID
number ?string Document number, up to 64 characters
company_uuid ?uuid Supplier company
company_name ?string Supplier's name
contact_uuid ?uuid Legacy. Supplier contact; prefer company_uuid
contact_name ?string Legacy. The name of that contact
file_uuid ?uuid Scanned document, a file
note string Free text
item_count integer Number of items. Only in List Receipts
items array {item_type, item_uuid, name, unit, amount, batch_uuid, batch_number, unit_cost?}. Only in Get Receipt; unit_cost only with can_view_purchase_price
created_at ISO8601 datetime When the receipt was created
canceled_at ?ISO8601 datetime When the receipt was canceled; null if it wasn't
can_cancel boolean Whether it can be canceled now. Only in Get Receipt

List Receipts

GET /api/v1/projects/{project.uuid}/warehouses/{warehouse.uuid}/receipts

Returns receipts newest first, 50 per page. Query param page? (integer, from 1). The response is a plain array.

Requires can_view_warehouses.

Get Receipt

GET /api/v1/projects/{project.uuid}/warehouses/{warehouse.uuid}/receipts/{receipt.uuid}

Returns a receipt with its items.

Requires can_view_warehouses.

Create Receipt

POST /api/v1/projects/{project.uuid}/warehouses/{warehouse.uuid}/receipts

Requires can_edit_warehouses.

JSON Params

Field Type Description
items array 1–150 items: {item_type, item_uuid, amount, unit_cost?, batch_number?}, amount > 0. Each item becomes a batch; unit_cost defaults to the current purchase price
number? ?string Up to 64 characters
company_uuid? ?uuid Supplier company
contact_uuid? ?uuid Legacy supplier contact; prefer company_uuid
file_uuid? ?uuid Attached file
note? string Default ""

Example Request

{
  "number": "DN-2026-0912",
  "company_uuid": "0199a5b1-3c4d-7e5f-8061-728394a5b6c7",
  "items": [
    {
      "item_type": "material",
      "item_uuid": "0199a2c0-7a1b-7c2d-8e3f-a0b1c2d3e4f5",
      "amount": 100,
      "unit_cost": 4.2,
      "batch_number": "R-1187"
    },
    {
      "item_type": "material",
      "item_uuid": "0199a2c1-5d6e-7f70-8182-93a4b5c6d7e8",
      "amount": 40
    }
  ]
}

Response

201 Created

{
  "uuid": "0199ac38-5f60-7172-8384-950617283940"
}

Cancel Receipt

POST /api/v1/projects/{project.uuid}/warehouses/{warehouse.uuid}/receipts/{receipt.uuid}/cancel

Takes everything the receipt brought in back out of stock — each of its batches whole — recorded as receipt_cancel movements, and marks the receipt canceled_at. Only while nothing has moved the receipt's stock since: no write-off, adjustment or return has touched its batches, and none was deleted with its item. Receipts created before batches existed can't be canceled.

Requires can_edit_warehouses.

Response

204 No Content. A canceled receipt fails with 409 WAREHOUSE_RECEIPT_CANCELED, a used one with 409 WAREHOUSE_RECEIPT_USED.

Get Warehouse History

GET /api/v1/projects/{project.uuid}/warehouses/{warehouse.uuid}/history

Returns stock movements, newest first, 50 per page.

Requires can_view_warehouses.

Query String Params

Field Type Description
page? integer From 1. Default 1
receipt? uuid Only the movements of this receipt

Movement Structure

Field Type Description
uuid uuid Movement ID
item_type string material or product
item_uuid uuid The material or product
item_name ?string Its name
amount decimal Positive for incoming, negative for outgoing
operation_type string See below
reference_uuid ?uuid The receipt or order the movement belongs to
batch_uuid ?uuid The batch; one movement per batch it touched
batch_number ?string That batch's number
unit_cost? ?decimal The batch's unit cost. Present only with can_view_purchase_price
receipt_number ?string Receipt number, for receipt and receipt_cancel
order_serial ?string Order number, for spend, income and return
user_uuid ?uuid Who made the movement; null for automations and movements made before this field existed
user_name ?string Their name; null if they haven't set one
user_email ?string Their email
note string Comment, set by Adjust Stock
created_at ISO8601 datetime When the movement happened
operation_type Origin
manual Adjust Stock
receipt Create Receipt
spend An automation wrote off materials for an order
income An automation put finished products into stock for an order
return Return Order Products
receipt_cancel Cancel Receipt
deleted The material or product was deleted, its stock removed

Returns

A return rolls back production for some of an order's products: their materials go back into stock (by each product's bill of materials × the returned quantity, into the batches they were spent from), and the finished products still attributed to the order are taken out of stock. A product can be returned in parts, in one or several returns and to any of the project's warehouses, until its whole quantity on the order has been returned. A material never comes back in a larger amount than was actually written off for the order, even if the product's bill of materials has changed since.

Get Return Candidates

GET /api/v1/projects/{project.uuid}/warehouses/{warehouse.uuid}/returns?order={order.uuid}

Lists the order's products with how much of each has been returned and how much can still be returned. already_returned is true once returnable is 0.

Requires can_view_warehouses.

{
  "order_uuid": "0199a4e2-7b1c-7c3e-9d2a-5f4e8b1c0a11",
  "serial": "26274003",
  "products": [
    {
      "product_uuid": "0199a3f1-5c2e-7d40-b1a2-3c4d5e6f7a8b",
      "name": "Roller blind Blackout 605, 1200×1600 mm",
      "unit": "pcs",
      "quantity": 2,
      "returned": 1,
      "returnable": 1,
      "already_returned": false
    }
  ]
}

Return Order Products

POST /api/v1/projects/{project.uuid}/warehouses/{warehouse.uuid}/returns

Returns the given quantities, in one transaction, and writes a warehouse_return entry to the order's journal.

The finished product is taken out of stock only up to what is still attributed to the order in this warehouse. If it was already shipped (written off by another automation), only the materials come back.

Requires can_edit_warehouses.

JSON Params

Field Type Description
order_uuid uuid A non-deleted order of this project
items array 1–100 items: {product_uuid, quantity}, quantity > 0 and not more than its returnable

Response

200 OK with the movements made:

{
  "movements": [
    {
      "item_type": "material",
      "item_uuid": "0199a2c0-7a1b-7c2d-8e3f-a0b1c2d3e4f5",
      "name": "Blackout 605",
      "unit": "sm",
      "amount": 4.536
    },
    {
      "item_type": "product",
      "item_uuid": "0199a3f1-5c2e-7d40-b1a2-3c4d5e6f7a8b",
      "name": "Roller blind Blackout 605, 1200×1600 mm",
      "unit": "pcs",
      "amount": -2
    }
  ]
}

Errors

Status Code When
400 REQ_VALIDATION_FAILED The body does not match the schema; a return quantity exceeds the order; order query param missing
400 RES_NOT_FOUND Adjust Stock, Create Receipt: an item, company_uuid or file_uuid does not belong to this project
400 REQ_NO_DATA_PROVIDED Modify Warehouse: the body has no fields
400 WAREHOUSE_DEFAULT_REQUIRED is_default: false sent to the default warehouse
403 AUTH_INSUFFICIENT_SCOPE The token lacks projects or warehouses
403 AUTH_NO_PROJECT_ACCESS The user's role lacks can_view_warehouses (read) or can_edit_warehouses (write)
404 RES_NOT_FOUND The project, warehouse, receipt, order or an order product does not exist
409 WAREHOUSE_INSUFFICIENT_STOCK A movement would take stock below zero
409 WAREHOUSE_RETURN_ALREADY_DONE A return quantity exceeds what is left to return for that product on the order
409 WAREHOUSE_RECEIPT_CANCELED The receipt has already been canceled
409 WAREHOUSE_RECEIPT_USED Stock from the receipt has already been moved, so it can't be canceled