Inventory

The inventory module tracks physical stock for a project (one or more stores sharing store.projectId). Everything lives under /v1/inventory; all endpoints require a bearer token except the public storefront availability check.

• Permissions. The store owner can do everything. Members need inventory.read for lists and inventory.write for mutations. The inventory module must be enabled for the store (billing entitlement — the public endpoint returns 402 when it isn't).
• Lists accept page, limit, search and the filterator; batch endpoints return the partial-success envelope.

Concepts

Inventory objects are stock buckets keyed by (namespace, sku, batch) inside a project. Each object tracks quantityOnHand and quantityReserved (available = on hand − reserved), plus a storageClass (HOT, WARM, COLD, QUARANTINE), optional warehouseId, priority, expiresAt and free-form metadata (receipt stock-in stores unit_cost there).

Products map to inventory by scoped SKU. The product's sku is the root scope; variant options and addons may carry their own SKUs, conventionally nested as paths:

When an order line resolves its SKU, the leaf variant option wins, then parent options, then the product root. Availability lookups accept a trailing * wildcard — tshirt* aggregates the whole scope subtree, tshirt matches only the exact SKU. Aliases map external codes (supplier refs, barcodes) onto a target SKU.

How orders touch inventory

Orders drive reservations automatically via the order-inventory bridge. Defaults per store (overridable in store.configs.inventory_integration):

Additional knobs: missing_bucket_policy (ignore skips untracked SKUs — the default — while reject fails the order), allow_backorder (default true: reservations may exceed on-hand, availability goes negative), and lifecycle *_rules for conditional matching. Every stock change — receive, reserve, release, consume, adjustment, receipt void — is an immutable movement with delta, reason, correlationRef and balanceAfter, so GET /v1/inventory/movements is the full audit trail. Order events themselves are also pushed via webhooks.

At a glance

Projects & public availability

Objects

Availability & movements

Reservations

Reservations are created by the system (order flow or receipt posting) — there is no create endpoint. Release is the only mutation.

Aliases & warehouses

Reset

Examples

Receive stock into a batch bucket:

curl -X POST "https://api.feeef.org/v1/inventory/objects" \
  -H "Authorization: Bearer $FEEEF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "PROJECT_ID",
    "sku": "tshirt/red/m",
    "batch": "B-2026-08",
    "quantity": 100
  }'

Check availability for a SKU scope (wildcard aggregates variants):

curl -H "Authorization: Bearer $FEEEF_TOKEN" \
  "https://api.feeef.org/v1/inventory/availability?projectId=PROJECT_ID&skus=tshirt*,mug"

Adjust quantities (stock count correction) — on hand can never go negative or below reserved:

curl -X POST "https://api.feeef.org/v1/inventory/objects/apply-deltas" \
  -H "Authorization: Bearer $FEEEF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "PROJECT_ID",
    "deltas": [{ "objectId": "OBJECT_ID", "quantityDelta": -3 }],
    "reason": "damaged"
  }'

Inspect an order's hold and release it manually:

curl -H "Authorization: Bearer $FEEEF_TOKEN" \
  "https://api.feeef.org/v1/inventory/reservations/holder/ORDER_ID?projectId=PROJECT_ID"

curl -X POST -H "Authorization: Bearer $FEEEF_TOKEN" \
  "https://api.feeef.org/v1/inventory/reservations/RESERVATION_ID:release?projectId=PROJECT_ID"

Storefront availability (no token — safe to call from the browser):

curl -X POST "https://api.feeef.org/v1/inventory/public/availability" \
  -H "Content-Type: application/json" \
  -d '{ "storeId": "STORE_ID", "skus": ["tshirt*", "mug"] }'

Notes

• Receiving via POST /v1/inventory/objects tops up an existing (namespace, sku, batch) bucket instead of duplicating it. Purchase receipts are the finance-side way to stock in — they also enforce a per-batch unit cost.
• Batch updates use updateMask to whitelist fields: { projectId, names, updateMask: ["storageClass"], storageClass: "QUARANTINE" }.
• Availability responses are cached (~15 s) and invalidated on stock mutations; the public endpoint additionally caps requests at 250 SKUs.
• Movements and reservations are immutable audit records — there are no update or delete endpoints for them.