Saltar al contenido

Inventory

Inventory & stock movements

Inventory items hold the current stock level; stock_movements are an append-only ledger of changes. Every movement atomically updates the linked item — there is no second source of truth.

List inventory items

GET /v1/inventory_items Scope: inventory:read

Returns inventory items for the restaurant.

Query parameters

limitintegerOptional

Page size.

starting_afterstringOptional

Cursor.

categorystringOptional

Filter by free-form category.

low_stockbooleanOptional

true returns only items at or below min_stock.

is_activebooleanOptional

false includes soft-deleted items.

Request

curl 'https://api.tablezio.com/v1/inventory_items?low_stock=true' -H 'X-API-Key: tbz_…'

Response

application/json
{ "object": "list", "data": [ /* inventory_item */ ], "has_more": false, "next_cursor": null, "previous_cursor": null, "url": "/v1/inventory_items" }

Retrieve an inventory item

GET /v1/inventory_items/{id} Scope: inventory:read

Fetch a single inventory item.

Path parameters

idstringRequired

Item ID (inv_…).

Request

curl https://api.tablezio.com/v1/inventory_items/inv_… -H 'X-API-Key: tbz_…'

Response

application/json
{
  "id": "inv_8b2c3d4e5f6a7b8c9d0e1f20",
  "object": "inventory_item",
  "created": 1716730000,
  "updated": 1716730000,
  "name": "Beef patties (8oz)",
  "category": "meat",
  "sku": "BEEF-8OZ",
  "unit": "kg",
  "current_stock": 12.5,
  "min_stock": 5,
  "max_stock": 30,
  "cost_per_unit": 1350,
  "storage_location": "Walk-in cooler A",
  "expires_at": 1717340000,
  "is_active": true,
  "is_low_stock": false,
  "supplier": null
}

Create an inventory item

POST /v1/inventory_items Scope: inventory:write

Adds a new tracked item to the storeroom.

Body parameters

namestringRequired

Display name.

unitstringRequired

Unit of measurement (kg, l, pcs…).

categorystringOptional

Free-form category.

skustringOptional

Optional SKU.

current_stocknumberOptional

Current on-hand quantity.

min_stocknumberOptional

Triggers low_stock once reached.

max_stocknumberOptional

Cap for auto-reorder logic.

cost_per_unitinteger (cents)Optional

Latest unit cost.

storage_locationstringOptional

Free-form location string.

expires_atstring (ISO 8601)Optional

Expiration date if applicable.

Request

curl -X POST https://api.tablezio.com/v1/inventory_items \
  -H 'X-API-Key: tbz_…' -H 'Content-Type: application/json' \
  -d '{ "name": "Beef patties (8oz)", "unit": "kg", "min_stock": 5, "cost_per_unit": 1350 }'

Response

application/json
{
  "id": "inv_8b2c3d4e5f6a7b8c9d0e1f20",
  "object": "inventory_item",
  "created": 1716730000,
  "updated": 1716730000,
  "name": "Beef patties (8oz)",
  "category": "meat",
  "sku": "BEEF-8OZ",
  "unit": "kg",
  "current_stock": 12.5,
  "min_stock": 5,
  "max_stock": 30,
  "cost_per_unit": 1350,
  "storage_location": "Walk-in cooler A",
  "expires_at": 1717340000,
  "is_active": true,
  "is_low_stock": false,
  "supplier": null
}

List stock movements

GET /v1/stock_movements Scope: inventory:read

Returns the full audit trail of stock changes (purchases, usage, waste, adjustments, transfers, returns).

Query parameters

inventory_itemstringOptional

Filter to a specific item (inv_…).

typestringOptional

Filter by movement type.

purchaseusagewasteadjustmenttransferreturn

Request

curl 'https://api.tablezio.com/v1/stock_movements?type=waste' -H 'X-API-Key: tbz_…'

Response

application/json
{ "object": "list", "data": [ /* stock_movement */ ], "has_more": false, "next_cursor": null, "previous_cursor": null, "url": "/v1/stock_movements" }

Record a stock movement

POST /v1/stock_movements Scope: inventory:write

Atomically adjusts the linked inventory item and records the movement. Use a positive quantity for purchases and returns; negative for usage and waste.

Body parameters

inventory_itemstringRequired

Linked inventory item id (inv_…).

typestringRequired

Movement type.

purchaseusagewasteadjustmenttransferreturn
quantitynumberRequired

Signed quantity, in the item's unit.

unit_costinteger (cents)Optional

Per-unit cost; used to compute total_cost.

reasonstringOptional

Free-form reason.

referencestringOptional

External reference id (PO number, invoice ref…).

Request

curl -X POST https://api.tablezio.com/v1/stock_movements \
  -H 'X-API-Key: tbz_…' -H 'Content-Type: application/json' \
  -d '{ "inventory_item": "inv_…", "type": "purchase", "quantity": 10, "unit_cost": 1350 }'

Response

application/json
{
  "id": "sm_8b2c3d4e5f6a7b8c9d0e1f20",
  "object": "stock_movement",
  "created": 1716730000,
  "inventory_item": "inv_…",
  "type": "purchase",
  "quantity": 10,
  "unit_cost": 1350,
  "total_cost": 13500,
  "reason": "Weekly delivery",
  "reference": "PO-0123",
  "performed_at": 1716730000
}