Inventory API

Retrieves the current stock levels of an inventory key across all locations, keyed by location ID.

Errors

• 404 — the inventory key has no inventory position at any location.

Retrieves the current stock levels of the product's inventory key across all locations, keyed by location ID.

Errors

• 404 — the product has no inventory_key.
• 404 — the inventory key has no inventory position at any location.

Retrieves the current stock levels of the inventory key of the product you reference, across all locations, keyed by location ID.

Behavior

Product references are unique per merchant, so merchant is required.

Errors

• 400 — merchant missing.
• 404 — the product has no inventory_key.
• 404 — the inventory key has no inventory position at any location.

Retrieves the open reservations held against an inventory key.

Behavior

Reservations are held per location and order, and back each position's reserved counter. A reservation is open while it holds a non-zero quantity: fulfillment and cancellation reduce it and then delete the row, and there is no status field. Rows are oldest first, paged with page_num and rows_per_page (10 per page by default); only the oldest 500 are reachable. location_id narrows the read to one location.

Retrieves the open reservations held against the product's inventory key.

Behavior

Reservations are held per location and order, and back each position's reserved counter. A reservation is open while it holds a non-zero quantity: fulfillment and cancellation reduce it and then delete the row, and there is no status field. Rows are oldest first, paged with page_num and rows_per_page (10 per page by default); only the oldest 500 are reachable. location_id narrows the read to one location.

Retrieves the open reservations held against the inventory key of the product you reference.

Behavior

Product references are unique per merchant, so merchant is required.

Reservations are held per location and order, and back each position's reserved counter. A reservation is open while it holds a non-zero quantity: fulfillment and cancellation reduce it and then delete the row, and there is no status field. Rows are oldest first, paged with page_num and rows_per_page (10 per page by default); only the oldest 500 are reachable. location_id narrows the read to one location.

Permanently deletes the inventory position of an inventory key at one location, along with its reservations.

Behavior

Position. The position is gone: reading it returns 404 until the next inventory event for that inventory key and location recreates it. The event history is not deleted, so the history for the inventory key still returns the events that preceded the deletion.

Reservations. Every reservation held at that location is deleted with the position. The orders holding them are not updated.

Webhook. An inventory webhook with operation: DELETE fires when the tenant has an active inventory webhook.

Returns the events submitted under one bulk import request, in sequence order.

Behavior

status reports the batch as a whole:

• processing while any row is still queued.
• completed once every row is accounted for.

Rows are in sequence order within the batch. APPLIED, REJECTED and UNCHANGED rows are all included; rows left out of the event history by skip_unchanged=true are not. A REJECTED row carries its reason in error_message.

Rows the import call rejected on validation never reach the event history; they are reported only in the import response. Once the status is completed, an accepted row with no event was unchanged and imported with skip_unchanged=true.

Retrieves the event history of an inventory key, newest first.

Behavior

Rows are newest first, paged with page_num and rows_per_page (10 per page by default); only the newest 500 events are reachable. APPLIED, REJECTED and UNCHANGED rows are all included; rows left out of the event history by skip_unchanged=true are not. location_id narrows the read to one location.

Errors

• 404 — the inventory key has no events.

Retrieves the event history of the product's inventory key, newest first.

Behavior

Rows are newest first, paged with page_num and rows_per_page (10 per page by default); only the newest 500 events are reachable. APPLIED, REJECTED and UNCHANGED rows are all included; rows left out of the event history by skip_unchanged=true are not. location_id narrows the read to one location.

Errors

• 404 — the product has no inventory_key.
• 404 — the inventory key has no events.

Submits a batch of inventory events that set or adjust stock at your locations.

Behavior

What to send

Every batch needs a request-id header that has not been used before. Send an Idempotency-Key as well: a retry that repeats both headers returns the stored response instead of a refusal. Each event addresses one inventory position: one inventory key at one location.

• inventory_key names the key. Product keys are refused here; they stay on the read endpoints.
• location_id or location_code names the location, and at least one is required. A code must match exactly one location, and when both keys are sent they must name the same location.
• The location must be inventory-enabled.

Resolution never guesses: an ambiguous or conflicting key rejects the event rather than applying it to a position you did not name.

Event types

Only the snapshot, adjustment and movement types may be sent.

Snapshot. Sets absolute values:

• SNAPSHOT sets both counts; requires on_hand and unavailable.
• SNAPSHOT_ONHAND sets on_hand only; requires on_hand.
• SNAPSHOT_UNAVAILABLE sets unavailable only; requires unavailable.

Adjustment. Applies a signed delta:

• INVENTORY_ADJUSTMENT_ONHAND adjusts on_hand; requires on_hand.
• INVENTORY_ADJUSTMENT_UNAVAILABLE adjusts unavailable; requires unavailable.

Movement. Applies a signed delta for a stock movement:

• RETURN adjusts unavailable for returned items; requires unavailable.
• TRANSFER_IN, TRANSFER_OUT, SALE and PO_RECEIPT adjust on_hand, unavailable or both; each requires at least one of them.

The movement types apply the value exactly as sent, so a SALE or TRANSFER_OUT that reduces stock must carry a negative number.

The order, shipment and return-request types (ORDER_RESERVATION, ORDER_UPDATE, ORDER_CANCELLATION, ORDER_FULFILLMENT, ORDER_UNFULFILLED, ORDER_RETURN, SHIPMENT_SHIPPED, RETURN_REQUEST_REVERSE_SHIPMENT_DELIVERED, RETURN_REQUEST_MARKED_AS_RECEIVED) are written by Carriyo as orders move. A row sending one is rejected; the rest of the batch continues.

Validation

A row that fails validation is rejected on its own and the batch continues; a problem with the request itself refuses the whole batch, as listed under Errors.

• A quantity outside -1,000,000 to 1,000,000, or neither quantity supplied, rejects the row.
• event_timestamp missing, older than 14 days, or more than two minutes ahead of the Carriyo server clock rejects the row.
• A missing inventory_key, or any product_id, product_ref or merchant present, rejects the row.
• A missing or unsupported event_type, or a field combination wrong for the type, rejects the row.
• An unknown location, a disagreeing location_id and location_code, an ambiguous code, or a location that is not inventory-enabled rejects the row.

Processing

Rows are queued and applied asynchronously, in event_timestamp order. Each comes back processing (accepted and queued) or rejected with a reason, and the batch's progress is readable by request id. If queuing fails, accepted rows flip to rejected and the request-id is released for reuse.

• Snapshot rows for the same position and type are collapsed to the one with the newest event_timestamp; the others are rejected as older snapshots.
• Snapshot rows naming the same position with different snapshot types are all rejected.
• Movement rows are never collapsed: each one applies.

An inventory key and location with no position yet gets one from its first event, with every counter at 0, so a movement on a new position applies its delta from 0. Across batches, a snapshot older than a count already applied to the position is rejected; a snapshot older than movements applied after it is re-based on those movements and applied; a movement older than a count already applied is rejected as already included.

Each row that changes a counter fires one inventory webhook, with operation CREATE when the row created the position and UPDATE otherwise, when the tenant has an active inventory webhook.

Resubmitting a snapshot batch converges on the same counts. Resubmitting adjustment or movement rows applies them again, so read a failed batch by its request id before resending it.

Unchanged rows

A row leaves the position unchanged when it is a snapshot equal to the stored counts or a zero movement. Such a row is recorded with status UNCHANGED and never fires a webhook. With skip_unchanged=true it is left out of the event history as well; the row is still counted and the request still completes.

Errors

• 400 — the request-id header is missing.
• 400 — the request-id has been used before; the whole request is lost, valid rows included.
• 400 — the body is empty.
• 400 — the body is malformed JSON.
• 400 — the batch exceeds 500 rows; the message is bulk import cannot exceed 500 rows.