Inventory

Use Carriyo's Inventory module to give Carriyo the stock visibility it needs for smart allocation and click-and-collect filtering. Your WMS, ERP, or commerce platform remains the source of truth. Carriyo holds an operational mirror, not a master record.

If you skip inventory entirely, Carriyo still works (orders allocate, shipments book, returns process), but several features operate blind. Allocation rules can't be inventory-aware, click-and-collect can't filter by stock, and reports lose the "available vs sold" lens.

What Carriyo's inventory does

• Per-location stock visibility. Track quantity-on-hand per SKU per location.
• Inventory events. Events come in (adjustments, receipts, shipments out, returns in) and Carriyo updates the per-location position.
• Reservations. When an order allocates, the chosen location reserves the stock until the order is fulfilled or shipped, whichever the tenant's stock reduction timing names, or until it is cancelled.
• Inputs to allocation. Allocation rules can match on "location has stock", falling through to a different location when the primary is empty.
• Click-and-collect filtering. When a shopper picks collection as the delivery method, only stores with stock appear.
• Stock reporting. Aggregate stock metrics, turnover by SKU, trapped inventory.

The inventory key

Stock is not held against a product record. It is held against an inventory key, the string an inventory event carries in inventory_key. Every stock position in Carriyo is a row for one inventory key at one location.

A product joins that stock by carrying the same value in its own inventory_key field. Carriyo never derives it: you set it when you create the product, or patch it later. A barcode such as a GTIN is the usual choice, because the point of the key is to group listings that draw on the same physical stock. Two listings of one item that share a key sell from the same stock and can never drift apart.

A product with no inventory_key has nothing to join to. Stock can exist under a matching key and the product still reads as out of stock everywhere that consults inventory. Order allocation skips the location, and the storefront delivery-option lookups return availability: NONE with fulfillable_quantity: 0. That is a real answer, not a "not evaluated" one, so it is easy to mistake for a genuine stock-out. If availability looks wrong for one product, check its inventory_key first.

How an event changes stock

Every event either sets a position to the absolute value you send, or adjusts it by a signed delta. The event_type alone decides which.

Carriyo writes further event types itself as orders move through their lifecycle, covering reservations, fulfillment, cancellation, and returns. Those are not accepted from a feed: a batch that sends one has that row rejected.

Retrying a batch safely

The request-id you send with a batch must be new. Carriyo rejects a reused one outright, so it guards against sending the same batch twice by accident rather than acting as a replay token. The one exception is a batch that could not be queued: its rows come back rejected and the id is released for reuse.

Whether a failed batch is safe to resend under a fresh id depends on the write mode:

• Set events converge. They write an absolute position and are applied in event_timestamp order, so a stale snapshot loses to a newer one already applied. Resending the same values lands on the same answer. When two rows in one batch name the same record and snapshot type, the later one wins and Carriyo discards the earlier.
• Adjust events double-count. Each one applies a delta, so resending adds the movement twice. If an adjust batch fails or times out, read the batch back by its request id and confirm what landed before resending.

What it doesn't do

• Master record. Carriyo doesn't replace your WMS or ERP. Inventory data flows in; Carriyo doesn't write back to your source.
• Receiving / counting workflows. Stock counting, receiving POs, cycle counts: your WMS manages those. Carriyo consumes the resulting numbers.
• Forecasting / reordering. Carriyo doesn't predict stock needs or trigger replenishment.

Data flow shapes

Two common shapes:

Push from your WMS / ERP

Your inventory system pushes events to Carriyo:

WMS / ERP  ──events──▶  Carriyo inventory  ──used by──▶  Allocation, Click-and-collect, Reports

Events typically include receipts (stock arrived), shipments out (stock dispatched), adjustments (counts), transfers (stock moved between locations).

Pull / sync via connector

Connectors (Shopify, Magento, etc.) sync inventory on a schedule. The connector handles the push for you; Carriyo's data lags slightly behind the source but stays close enough for operational decisions.

Reservations

When an order allocates to a location, Carriyo reserves the quantity. Reservations:

• Reduce available stock for subsequent allocation decisions.
• Don't change quantity-on-hand. The parcel hasn't shipped yet; physical stock is still there.
• Release on shipment. When the parcel ships out, quantity-on-hand decreases and the reservation clears.
• Release on cancellation. When an order or fulfillment order is cancelled before booking, the reservation clears without affecting on-hand.

Reservations are why allocation can be inventory-aware without double-allocating: the second order looking for the same SKU sees available (on-hand minus reserved), not raw on-hand.

How it fits with other modules

• Orders. Allocation rules can be inventory-aware.
• Locations. Inventory is per-location.
• Click and collect. Inventory drives store availability at checkout.
• Products. SKUs in inventory map to product catalog entries.