Inventory API

The Inventory resource provides a centralized view of stock levels across your fulfillment locations. Inventory records are automatically created and updated when you submit inventory events through the Inventory Events API.

Key concepts

Stock levels

Inventory in Carriyo tracks three types of stock quantities for each product at each location:

• On hand: total physical quantity of the product available at the location.
• Reserved: quantity allocated to orders but not yet shipped.
• Unavailable: quantity not available for sale (for example, damaged or expired).

The available quantity is calculated as: on_hand - reserved - unavailable.

Location-based tracking

Inventory is tracked per product per location, allowing you to:

• Monitor stock levels across multiple warehouses or stores
• Allocate orders to locations with available inventory
• Enable store-to-door or ship-from-store fulfillment

Integration with orders

When orders are created and allocated to fulfillment locations, Carriyo automatically reserves inventory. This ensures accurate available quantities are reflected in real-time.

Inventory events are the mechanism through which stock levels are updated in Carriyo. Instead of directly setting inventory quantities, you submit events that describe changes to your inventory.

Event types

The event_type field controls how the submitted quantities are applied. Each type is either a Set (overwrites the position to the absolute value you send) or an Adjust (applies a signed delta to the current position):

Bulk import

The Inventory Events API supports bulk import, allowing you to submit multiple inventory events in a single request. This is useful for:

• Syncing inventory from your ERP or WMS systems
• Processing inventory adjustments in batch
• Initial inventory setup

Each bulk import request is identified by a unique request_id that you supply and can use to track the status of all events in the batch.

Idempotency and retries

The request_id you supply must be unique — re-using one is rejected (requestId already exists), so it guards against an accidental duplicate submission rather than acting as a replay token. Within a single batch you may submit at most one event per product_id and location_id.

Whether a failed batch is safe to resubmit (under a new request_id) depends on the write mode:

• Set events (SNAPSHOT, SNAPSHOT_ONHAND, SNAPSHOT_UNAVAILABLE) write an absolute position and are applied in event_timestamp order — a stale snapshot is ignored if a newer one has already been applied — so resubmitting the same values converges to the same result. Safe to retry.
• Adjust events apply a signed delta, so resubmitting double-counts. If an adjust batch fails or times out, confirm whether it landed by retrieving the batch by its request_id before resubmitting.

Event tracking

Retrieve the status and results of inventory events using either:

• Request ID: get all events from a specific bulk import.
• Product ID: get all events for a specific product.

This lets you verify that inventory updates were processed correctly and troubleshoot any failures.