Inventory

Read stock levels per branch, filter to low stock, and record purchases, waste, transfers, and adjustments.

Public API1 min read

#List stock

http

GET /v1/inventory/items

Scope: inventory:read.

Parameter	Description
`page`, `limit`	Pagination
`branchId`	One branch. Must be within the key's branch scope
`search`	Matches name or SKU
`lowStock`	`true` returns only items at or below their reorder level

Results are ordered by name.

json

{
  "data": [
    {
      "id": "cmd8iv3f20008abcdefghijkl",
      "name": "Mozzarella",
      "sku": "SS-004",
      "category": "dairy",
      "unit": "kg",
      "quantityOnHand": "12.5000",
      "costPerUnit": "9.2500",
      "reorderLevel": "5.0000",
      "parLevel": "20.0000",
      "supplier": "Union Square Dairy",
      "storageLocation": "Walk-in",
      "branch": { "id": "cmd8w9k1a0002abcdefghijkl", "slug": "soho" },
      "createdAt": "2026-02-01T09:00:00.000Z",
      "updatedAt": "2026-07-28T06:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 25, "total": 84, "totalPages": 4, "hasMore": true }
}

Quantities are decimal strings with four decimal places. Stock is per branch, so the same ingredient at three branches is three items with three ids.

#Fetch one item

http

GET /v1/inventory/items/{itemId}

Scope: inventory:read.

#Record a movement

http

POST /v1/inventory/items/{itemId}/transactions

Scope: inventory:write.

json

{
  "type": "received",
  "quantity": 25,
  "notes": "PO 8841"
}

Type	Effect on stock	Quantity
`purchase`	Increase	Must be positive
`received`	Increase	Must be positive
`adjustment`	Signed, increases or decreases	Any non-zero value
`waste`	Decrease	Must be positive
`transfer`	Decrease	Must be positive
`return`	Increase	Must be positive

Only adjustment accepts a negative quantity. For the others, send the magnitude and let the type decide the direction. Sending -5 as waste is rejected.

bash

curl -X POST https://api.tryrestro.com/v1/inventory/items/cmd8iv3f20008abcdefghijkl/transactions \
  -H "Authorization: Bearer $RESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"received","quantity":25,"notes":"PO 8841"}'

Returns the item with its new balance.

#Rules

A movement that would take the balance below zero is rejected with 400. Recount and record the true figure as an adjustment.
Movements are recorded against the branch that owns the item and attributed to your API key.
This endpoint is not idempotent. Every call records a movement. On a timeout, re-read the item and check the balance before retrying.

#Working with recipes

Selling a menu item with a recipe already moves stock automatically: ingredients are deducted at confirmation and returned on cancellation. Do not also post a waste or adjustment for the same sale, or the movement is counted twice.

Use this endpoint for movements that happen outside a sale: deliveries in, spoilage, transfers between branches, and corrections after a physical count.

Did this page miss something? Tell us.