API Reference

Get Inventory Levels

GET /api/v1/inventory_levels

Retrieve current stock levels for all products and variants across locations.

Adjust Inventory

POST /api/v1/inventory_adjustments

Manually adjust inventory for a specific variant at a location (e.g., for shrinkage or stock-in).

Inventory Ledger

GET /api/v1/inventory_ledger

Fetch a history of all inventory movements and changes.

List Products

GET /api/v1/products

Retrieve a list of all products in your inventory.

Create Product

POST /api/v1/products

Create a new product record.

Get Product

GET /api/v1/products/:id

Retrieve details for a specific product.

List Variants

GET /api/v1/products/:product_id/variants

List all variants for a given product.

Lookup Variant by Barcode

GET /api/v1/variants/barcode/:barcode

Find a specific variant using its barcode.

List Orders

GET /api/v1/orders

List sales orders.

Create Order

POST /api/v1/orders

Place a new order, which can include multiple line items.

Get Order

GET /api/v1/orders/:id

Fetch order status and details.

Reserve Order

POST /api/v1/orders/:id/reserve

Allocate inventory for an order without fulfilling it yet.

Fulfill Order

POST /api/v1/orders/:id/fulfill

Process and complete order fulfillment, updating stock levels.

Cancel Order

POST /api/v1/orders/:id/cancel

Cancel a pending or reserved order and release inventory.

List Purchase Orders

GET /api/v1/purchase_orders

List all purchase orders, typically from suppliers.

Create Purchase Order

POST /api/v1/purchase_orders

Place a new purchase order to a supplier.

Get Purchase Order

GET /api/v1/purchase_orders/:id

Retrieve details of a specific purchase order.

Receive Purchase Order

POST /api/v1/purchase_orders/:id/receive

Mark items in a purchase order as received and update stock.

List Stock Transfers

GET /api/v1/stock_transfers

List all inventory transfers between locations.

Create Stock Transfer

POST /api/v1/stock_transfers

Initiate a transfer of inventory between locations.

Get Stock Transfer

GET /api/v1/stock_transfers/:id

Retrieve details and status for a stock transfer.

Ship Stock Transfer

POST /api/v1/stock_transfers/:id/ship

Mark a transfer as shipped, reducing stock from source.

Receive Stock Transfer

POST /api/v1/stock_transfers/:id/receive

Mark a transfer as received, increasing stock at destination.

List Cycle Counts

GET /api/v1/cycle_counts

List physical inventory cycle counts. Optional filters: location_id, status (draft, in_progress, completed).

Create Cycle Count

POST /api/v1/cycle_counts

Create a new cycle count for a location (status defaults to draft).

Get Cycle Count

GET /api/v1/cycle_counts/:id

Retrieve a cycle count with its items (expected, counted, variance).

Update Cycle Count

PATCH /api/v1/cycle_counts/:id

Update cycle count; use cycle_count_items_attributes to submit counted quantities.

Start Cycle Count

POST /api/v1/cycle_counts/:id/start

Transition draft → in_progress and set started_at.

Load Inventory

POST /api/v1/cycle_counts/:id/load_inventory

Populate cycle count items from current snapshots (expected_quantity) for the count's location.

Complete Cycle Count

POST /api/v1/cycle_counts/:id/complete

Apply variances as cycle_count_adjustment ledger entries and mark count completed.

List Return Authorizations

GET /api/v1/return_authorizations

List return authorizations. Optional filters: status (pending, received, cancelled), order_id.

Create Return Authorization

POST /api/v1/return_authorizations

Create an RMA linked to an order. Body: return_authorization with order_id, reason, and items (sku, quantity, condition: sellable | damaged | discarded).

Get Return Authorization

GET /api/v1/return_authorizations/:id

Retrieve a return authorization with its line items.

Update Return Authorization

PATCH /api/v1/return_authorizations/:id

Update reason or items (only when status is pending).

Receive Return

POST /api/v1/return_authorizations/:id/receive

Mark the return as received. Items with sellable condition add stock (return_received); damaged or discarded items are recorded as return_disposed and do not increase inventory.

List Inventory Policies

GET /api/v1/inventory_policies

List reorder policies per variant/location. Optional filters: location_id, sku.

Create Inventory Policy

POST /api/v1/inventory_policies

Create a policy with variant_id, location_id, reorder_point, reorder_quantity, optional lead_time_days and safety_stock. Used by AI reorder recommendations and low-stock logic.

Get Inventory Policy

GET /api/v1/inventory_policies/:id

Retrieve a single policy.

Update Inventory Policy

PATCH /api/v1/inventory_policies/:id

Update reorder point, quantity, lead time, or safety stock.

Delete Inventory Policy

DELETE /api/v1/inventory_policies/:id

Remove the policy; defaults will be used for that variant/location.

List Locations

GET /api/v1/locations

List all storage locations (warehouses, stores).

Create Location

POST /api/v1/locations

Register a new storage location.

List Suppliers

GET /api/v1/suppliers

List all vendors and suppliers.

Create Supplier

POST /api/v1/suppliers

Add a new supplier record.

Analytics Reports

AI & Insights

List Production Batches

GET /api/v1/production_batches

List batches for the current organization. Optional filter: status (planned, in_progress, completed, cancelled). Pagination: page, per_page.

Get Production Batch

GET /api/v1/production_batches/:id

Retrieve a single batch with inputs and outputs.

Create Production Batch

POST /api/v1/production_batches

Create a planned batch. Body: production_batch[recipe_id], production_batch[location_id], production_batch[planned_quantity], optional production_batch[notes]. Requires manufacturing module and sufficient ingredient stock.

Start Production Batch

POST /api/v1/production_batches/:id/start

Transition a planned batch to in_progress and reserve ingredients. Returns the updated batch.

Complete Production Batch

POST /api/v1/production_batches/:id/complete

Complete an in-progress batch. Body: production_batch[actual_quantity_produced], optional inputs array with production_batch_input_id, actual_quantity, waste_quantity per input. Consumes ingredients and creates finished-good stock.

Cancel Production Batch

POST /api/v1/production_batches/:id/cancel

Cancel a planned or in-progress batch. Releases reservations; no inventory is consumed.

List Lots

GET /api/v1/lots

Paginated list of lots. Optional: status (active, quarantine, exhausted, recalled), variant_id. Pagination: page, per_page.

Get Lot

GET /api/v1/lots/:id

Retrieve a single lot (id, lot_number, variant_id, status, expiry_date, quantity_initial, etc.). Returns 404 if the lot does not exist or belongs to another organization.

Forward Trace

GET /api/v1/lots/:id/trace_forward

Returns the lot plus all movements (lot_ledger_entries) and current_stock by location_id. Use for “where has this lot been?”. Returns 404 if the lot does not exist or belongs to another organization.

Backward Trace

GET /api/v1/lots/:id/trace_backward

For lots from production: returns source_batch and input_lots used to produce this lot. Empty for non-production lots. Returns 404 if the lot does not exist or belongs to another organization.

List Waste Records

GET /api/v1/waste_records

Paginated list of waste entries (variant_id, location_id, quantity, reason, recorded_at, lot_record_id). Pagination: page, per_page.

Record Waste

POST /api/v1/waste_records

Body (JSON): variant_id, location_id, quantity, reason (expired, damaged, production, spoilage, contamination, other). Optional: lot_record_id, notes. Reduces on-hand inventory; returns 422 if insufficient stock.

Expiry Alerts

GET /api/v1/expiry/alerts

Lots expiring within N days. Query: days (default 30, 1–365). Response: array of { id, lot_number, variant_id, expiry_date, days_until_expiry }.