Inventory

Reading stock levels and recording movements.

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

Ordered by name.

json

{
  "data": [
    {
      "id": "cmd8iv3f20008abcdefghijkl",
      "name": "Chickpeas",
      "sku": "CHK-1",
      "category": "dry_goods",
      "unit": "kg",
      "quantityOnHand": "12.5000",
      "costPerUnit": "3.2500",
      "reorderLevel": "5.0000",
      "parLevel": "20.0000",
      "supplier": "Nile Foods",
      "storageLocation": "Dry store",
      "branch": { "id": "cmd8w9k1a0002abcdefghijkl", "slug": "maadi" },
      "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 — 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 the type decides the direction — sending -5 as waste is rejected rather than quietly doubling back.

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 push the balance below zero returns 400. Restro will not hold negative stock — if your count really is negative, something upstream is wrong and this is where you find out.
Movements are recorded against the branch that owns the item, 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 — at confirmation, and back again on cancellation. Do not also post a waste or adjustment for the same sale, or you will double-count.

Use this endpoint for what happens outside the till: deliveries in, spoilage, transfers between branches, and corrections after a physical count.

Did this page miss something? Tell us.