Skip to content

Inventory Management

Vectis tracks stock at the variant level per warehouse. The inventory system handles reservations at order time, manual adjustments, and publishes events on every stock change.

Core Concepts

Warehouses

A warehouse represents any physical or logical stock location. Each warehouse has a name, address, and active/inactive status. You can have one warehouse or dozens.

Stock Levels

Stock is tracked per variant per warehouse with these fields:

Field Description
on_hand Total physical units in the warehouse
reserved Units allocated to open orders
available Computed: on_hand - reserved

Note

The available quantity is what the storefront displays and what checkout validates against. A variant with 50 on-hand and 12 reserved shows 38 available.

Stock Adjustments

Stock levels change through adjustments. Each adjustment records:

  • Variant and warehouse — which stock record to modify.
  • Quantity delta — positive (stock received) or negative (stock removed).
  • Reason — freeform text for audit (e.g., "Received PO #4421", "Damaged goods write-off").

Manual Adjustments

Admins adjust stock directly from the admin panel:

  1. Navigate to Inventory → Stock Levels.
  2. Find the variant/warehouse combination.
  3. Enter the adjustment quantity and reason.

Integration Adjustments

External systems (WMS, ERP) adjust stock by publishing events to Redpanda on the vectis.inventory topic. The event consumer processes adjustments and updates stock levels.

Reservations

When a buyer completes checkout:

  1. The system creates a reservation for each line item, incrementing reserved on the matching stock record.
  2. available decreases accordingly — other buyers see the reduced availability immediately.
  3. When the order is fulfilled and shipped, the reservation converts to a stock decrease (on_hand reduced, reserved released).
  4. If the order is cancelled, the reservation is released — reserved decreases and available recovers.
graph LR
    CO[Checkout] -->|reserve| R[reserved +5]
    R -->|ship| S["on_hand -5, reserved -5"]
    R -->|cancel| C["reserved -5 (released)"]

Warning

Reservations are tied to the order lifecycle. Manually adjusting reserved without going through the order system can create mismatches.

Backorder Support

Variants can be configured to allow orders even when available is zero or negative:

  • backorder_enabled = true — checkout proceeds regardless of stock. The order is created with a backorder flag.
  • backorder_enabled = false (default) — checkout rejects the line item if quantity exceeds available stock.

Backordered items appear in a dedicated admin filter so fulfillment teams can prioritize restocking.

Inventory Events

Every stock change publishes an inventory.adjusted event to Redpanda containing:

Field Description
variant_id The affected variant
warehouse_id The affected warehouse
adjustment The quantity delta
new_on_hand Updated on-hand quantity
new_available Updated available quantity
reason Adjustment reason

External systems (ERP, analytics, alerting) can consume these events to stay in sync.

Tip

Use inventory events to trigger low-stock alerts. Subscribe to vectis.inventory and filter for new_available < threshold.

Multi-Warehouse Fulfillment

When multiple warehouses have stock for a variant, the system currently uses the default warehouse for availability checks. Future versions will support warehouse selection strategies (closest warehouse, least-cost routing).

Admin Panel

From Inventory in the admin:

  • Warehouses — create and manage warehouse locations.
  • Stock Levels — view and filter stock by variant, warehouse, or availability status.
  • Adjustments — make manual adjustments with audit reasons.
  • Backorders — filter orders with backordered items for restocking priority.
  • Low Stock — view variants below configurable threshold levels.