Bulk Import Inventory Events

Submits multiple inventory events in a single request to update stock levels across your locations.

Request Header Requirements

  • request-id (required): A unique ID for this batch. Must not have been used before.

Supported Event Types

Only these event types are supported for bulk import:

Event Type Description Required Fields
SNAPSHOT Set absolute values for both on_hand and unavailable on_hand AND unavailable
SNAPSHOT_ONHAND Set absolute value for on_hand only on_hand only
SNAPSHOT_UNAVAILABLE Set absolute value for unavailable only unavailable only
INVENTORY_ADJUSTMENT_ONHAND Adjust on_hand by delta (+/-) on_hand only
INVENTORY_ADJUSTMENT_UNAVAILABLE Adjust unavailable by delta (+/-) unavailable only
RETURN Record returned items unavailable only
TRANSFER_IN Record stock transfer into location on_hand or unavailable
TRANSFER_OUT Record stock transfer out of location on_hand or unavailable
SALE Record sales (usually negative adjustment) on_hand or unavailable
PO_RECEIPT Record purchase order receipt on_hand or unavailable

Not supported (Internal Events): ORDER_RESERVATION, ORDER_UPDATE, ORDER_CANCELLATION, ORDER_FULFILLMENT, ORDER_UNFULFILLED, ORDER_RETURN, SHIPMENT_SHIPPED

Validation Rules

  • Quantity range: Values must be between -1,000,000 and 1,000,000
  • Timestamp: Must be within the last 14 days and not in the future
  • No duplicates: Each product_id + location_id combination must be unique in the batch
  • Product/Location: Must exist in your tenant
  • Location type: Must be an inventory-enabled location

Processing

Events are processed asynchronously via a queue. The response indicates:

  • PROCESSING: Event accepted and queued
  • REJECTED: Event failed validation with a reason

Best Practices

  • Use the request-id header to provide your own correlation ID
  • Include event_timestamp to ensure events are processed in the correct order
  • Check results for any REJECTED items
SecurityOAuth2-Production or OAuth2-Demo
Request
header Parameters
x-api-key
required
string

Your Carriyo API key for authentication.

tenant-id
required
string

Your unique tenant identifier in Carriyo.

request-id
required
string

A unique request ID for this batch (required).

  • Must be unique across all previous requests
  • Use this to track processing status via the Get Events by Request ID endpoint
  • Cannot be reused - if you need to retry, use a new request ID
Content-Type
string
Default: application/json
Request Body schema: application/json
required
Array
product_id
required
string

The unique identifier of the product. Must exist in your tenant.

location_id
required
string

The unique identifier of the location. Must be an inventory-enabled location.

on_hand
integer <int64> [ -1000000 .. 1000000 ]

The on-hand quantity value. Required for some event types:

  • Required: SNAPSHOT, SNAPSHOT_ONHAND, INVENTORY_ADJUSTMENT_ONHAND
  • Not allowed: INVENTORY_ADJUSTMENT_UNAVAILABLE, RETURN, SNAPSHOT_UNAVAILABLE
unavailable
integer <int64> [ -1000000 .. 1000000 ]

The unavailable quantity value. Required for some event types:

  • Required: SNAPSHOT, SNAPSHOT_UNAVAILABLE, INVENTORY_ADJUSTMENT_UNAVAILABLE, RETURN
  • Not allowed: SNAPSHOT_ONHAND, INVENTORY_ADJUSTMENT_ONHAND
event_type
required
string

The type of inventory event:

  • SNAPSHOT - Set absolute values for both on_hand and unavailable
  • SNAPSHOT_ONHAND - Set absolute value for on_hand only
  • SNAPSHOT_UNAVAILABLE - Set absolute value for unavailable only
  • INVENTORY_ADJUSTMENT_ONHAND - Adjust on_hand by delta (+/-)
  • INVENTORY_ADJUSTMENT_UNAVAILABLE - Adjust unavailable by delta (+/-)
  • RETURN - Record returned items (unavailable only)
  • TRANSFER_IN - Stock transfer into location
  • TRANSFER_OUT - Stock transfer out of location
  • SALE - Record sales
  • PO_RECEIPT - Purchase order receipt
Enum: "SNAPSHOT" "SNAPSHOT_ONHAND" "SNAPSHOT_UNAVAILABLE" "INVENTORY_ADJUSTMENT_ONHAND" "INVENTORY_ADJUSTMENT_UNAVAILABLE" "RETURN" "TRANSFER_IN" "TRANSFER_OUT" "SALE" "PO_RECEIPT"
reason
string

Optional reason or note for the inventory change.

event_timestamp
required
string <date-time>

The timestamp when the event occurred (ISO 8601 format). Required.

  • Must be within the last 14 days
  • Cannot be in the future
Responses
200

Successfully processed inventory events.

400

Invalid request payload.

post/inventory-events/bulk/import
Request samples
application/json
[
  • {
    }
]
Response samples
application/json
{
  • "request_id": "string",
  • "results": [
    ]
}