openapi: 3.0.1 info: title: Carriyo Inventory API description: $ref: inventory/index.md contact: name: Carriyo Support url: 'https://help.carriyo.com' email: support@carriyo.com version: '' servers: - url: 'https://api.carriyo.com' description: 'Production Server' - url: 'https://demo-api.carriyo.com' description: 'Demo Server' security: - OAuth2-Production: [] - OAuth2-Demo: [] tags: - name: Inventory description: $ref: inventory/inventory.md - name: Inventory Events description: $ref: inventory/inventory-events.md paths: '/inventory/product-id/{product-id}': get: tags: - Inventory summary: Get Inventory by Product ID operationId: get-inventory-by-product-id description: |- Retrieves the current inventory levels for a specific product across all locations. The response includes stock information for each location where the product has inventory, including: - **On Hand**: Total physical quantity available - **Reserved**: Quantity allocated to orders - **Unavailable**: Quantity not available for sale Use this endpoint to check real-time stock availability before allocating orders or to sync inventory data with external systems. parameters: - name: x-api-key in: header required: true schema: type: string description: Your Carriyo API key for authentication. - name: tenant-id in: header required: true schema: type: string description: Your unique tenant identifier in Carriyo. - name: Content-Type in: header schema: type: string default: application/json - name: product-id in: path required: true schema: type: string description: The unique identifier of the product to retrieve inventory for. responses: '200': description: Successfully retrieved inventory for the product. content: application/json: schema: $ref: '#/components/schemas/inventory-response' '404': description: No inventory found for the specified product ID. content: application/json: schema: $ref: '#/components/schemas/error-response' security: - OAuth2-Production: [] - OAuth2-Demo: [] '/inventory/product-id/{product-id}/location-id/{location-id}': delete: tags: - Inventory summary: Delete Inventory operationId: delete-inventory description: |- Permanently deletes the inventory record for a specific product at a specific location. **Warning**: This action cannot be undone. Use this endpoint when: - A product is discontinued at a location - Correcting data by removing incorrect inventory records - Cleaning up test data After deletion, the inventory for this product-location combination will need to be recreated through new inventory events. parameters: - name: x-api-key in: header required: true schema: type: string description: Your Carriyo API key for authentication. - name: tenant-id in: header required: true schema: type: string description: Your unique tenant identifier in Carriyo. - name: Content-Type in: header schema: type: string default: application/json - name: product-id in: path required: true schema: type: string description: The unique identifier of the product. - name: location-id in: path required: true schema: type: string description: The unique identifier of the location. responses: '200': description: Successfully deleted the inventory record. '404': description: Inventory not found for the specified product and location. content: application/json: schema: $ref: '#/components/schemas/error-response' security: - OAuth2-Production: [] - OAuth2-Demo: [] '/inventory-events/bulk/import': post: tags: - Inventory Events summary: Bulk Import Inventory Events operationId: bulk-import-inventory-events description: |- 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**: `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 parameters: - name: x-api-key in: header required: true schema: type: string description: Your Carriyo API key for authentication. - name: tenant-id in: header required: true schema: type: string description: Your unique tenant identifier in Carriyo. - name: request-id in: header required: true schema: type: string description: |- 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 - name: Content-Type in: header schema: type: string default: application/json requestBody: required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/inventory-event-request' responses: '200': description: Successfully processed inventory events. content: application/json: schema: $ref: '#/components/schemas/inventory-event-bulk-response' '400': description: Invalid request payload. content: application/json: schema: $ref: '#/components/schemas/error-response' security: - OAuth2-Production: [] - OAuth2-Demo: [] x-codegen-request-body-name: body '/inventory-events/request-id/{request-id}': get: tags: - Inventory Events summary: Get Inventory Events by Request ID operationId: get-inventory-events-by-request-id description: |- Retrieves all inventory events that were submitted as part of a specific bulk import request. Use this endpoint to: - Verify that all events in a batch were processed successfully - Check the overall batch status (`COMPLETED` or `PROCESSING`) - Troubleshoot individual events ### Response The response includes: - `status`: Overall batch status - `COMPLETED` - All events have been processed - `PROCESSING` - Some events are still being processed - `inventory_events`: List of events sorted by sequence number parameters: - name: x-api-key in: header required: true schema: type: string description: Your Carriyo API key for authentication. - name: Content-Type in: header schema: type: string default: application/json - name: request-id in: path required: true schema: type: string description: The request ID returned from the bulk import operation. responses: '200': description: Successfully retrieved inventory events for the request. content: application/json: schema: $ref: '#/components/schemas/get-inventory-events-response' '404': description: No events found for the specified request ID. content: application/json: schema: $ref: '#/components/schemas/error-response' security: - OAuth2-Production: [] - OAuth2-Demo: [] '/inventory-events/product-id/{product-id}': get: tags: - Inventory Events summary: Get Inventory Events by Product ID operationId: get-inventory-events-by-product-id description: |- Retrieves the history of inventory events for a specific product. Use this endpoint to: - Audit inventory changes over time - Debug unexpected inventory levels - Track the source and timing of inventory updates Events are returned in chronological order with full details including timestamps, quantities, and processing status. parameters: - name: x-api-key in: header required: true schema: type: string description: Your Carriyo API key for authentication. - name: tenant-id in: header required: true schema: type: string description: Your unique tenant identifier in Carriyo. - name: Content-Type in: header schema: type: string default: application/json - name: product-id in: path required: true schema: type: string description: The unique identifier of the product to retrieve events for. responses: '200': description: Successfully retrieved inventory events for the product. content: application/json: schema: type: array items: $ref: '#/components/schemas/inventory-event' '404': description: No events found for the specified product ID. content: application/json: schema: $ref: '#/components/schemas/error-response' security: - OAuth2-Production: [] - OAuth2-Demo: [] components: schemas: error-response: title: Error Response type: object properties: error: type: string description: Error message describing what went wrong. code: type: string description: Error code for programmatic handling. inventory-response: title: Inventory Response type: object properties: tenant: type: string description: The tenant identifier. product_id: type: string description: The unique identifier of the product. stock_by_location: type: object additionalProperties: $ref: '#/components/schemas/stock-info' description: Stock information keyed by location ID. creation_date: type: string format: date-time description: The date and time when the inventory record was created (ISO 8601 format). update_date: type: string format: date-time description: The date and time when the inventory record was last updated (ISO 8601 format). creation_source: $ref: '#/components/schemas/request-source' update_source: $ref: '#/components/schemas/request-source' stock-info: title: Stock Info type: object properties: on_hand: type: integer format: int64 description: The total physical quantity available at the location. reserved: type: integer format: int64 description: The quantity allocated to orders but not yet shipped. unavailable: type: integer format: int64 description: The quantity not available for sale (damaged, expired, etc.). update_date: type: string format: date-time description: The date and time when the stock info was last updated. reservations: type: array items: $ref: '#/components/schemas/reservation' description: List of active reservations against this stock. reservation: title: Reservation type: object properties: order_id: type: string description: The order ID that created this reservation. reserved_quantity: type: integer format: int64 description: The quantity reserved for this order. date: type: string format: date-time description: The date and time when the reservation was created. request-source: title: Request Source type: object properties: source: type: string description: The source system that made the request (e.g., API, UI, CONNECTOR). user_id: type: string description: The user or system identifier that made the request. ip_address: type: string description: The IP address from which the request originated. inventory-event-request: title: Inventory Event Request type: object required: - product_id - location_id - event_type - event_timestamp properties: product_id: type: string description: The unique identifier of the product. Must exist in your tenant. location_id: type: string description: The unique identifier of the location. Must be an inventory-enabled location. on_hand: type: integer format: int64 minimum: -1000000 maximum: 1000000 description: |- 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: type: integer format: int64 minimum: -1000000 maximum: 1000000 description: |- 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: type: string enum: - SNAPSHOT - SNAPSHOT_ONHAND - SNAPSHOT_UNAVAILABLE - INVENTORY_ADJUSTMENT_ONHAND - INVENTORY_ADJUSTMENT_UNAVAILABLE - RETURN - TRANSFER_IN - TRANSFER_OUT - SALE - PO_RECEIPT description: |- 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 reason: type: string description: Optional reason or note for the inventory change. event_timestamp: type: string format: date-time description: |- The timestamp when the event occurred (ISO 8601 format). Required. - Must be within the last 14 days - Cannot be in the future inventory-event-bulk-response: title: Inventory Event Bulk Response type: object properties: request_id: type: string description: The unique identifier for this bulk import request. Use this to track event status. results: type: array items: $ref: '#/components/schemas/inventory-event-bulk-response-item' description: Processing results for each event in the request. inventory-event-bulk-response-item: title: Inventory Event Bulk Response Item type: object properties: product_id: type: string description: The product ID from the request. location_id: type: string description: The location ID from the request. result: type: string enum: - PROCESSING - REJECTED description: |- The processing result of this event: - `PROCESSING` - Event accepted and queued for processing - `REJECTED` - Event failed validation reason: type: string description: Reason for rejection if result is `REJECTED`. get-inventory-events-response: title: Get Inventory Events Response type: object properties: status: type: string enum: - COMPLETED - PROCESSING description: |- Overall status of the batch: - `COMPLETED` - All events in the batch have been processed - `PROCESSING` - Some events are still being processed inventory_events: type: array items: $ref: '#/components/schemas/inventory-event' description: List of inventory events for this request, sorted by sequence number. inventory-event: title: Inventory Event type: object properties: tenant: type: string description: The tenant identifier. product_id: type: string description: The unique identifier of the product. location_id: type: string description: The unique identifier of the location. request_id: type: string description: The request ID from the bulk import. event_type: type: string enum: - SNAPSHOT - SNAPSHOT_ONHAND - SNAPSHOT_UNAVAILABLE - INVENTORY_ADJUSTMENT_ONHAND - INVENTORY_ADJUSTMENT_UNAVAILABLE - ORDER_RESERVATION - ORDER_UPDATE - ORDER_CANCELLATION - ORDER_FULFILLMENT - ORDER_UNFULFILLED - ORDER_RETURN - SHIPMENT_SHIPPED - RETURN_REQUEST_REVERSE_SHIPMENT_DELIVERED - RETURN_REQUEST_MARKED_AS_RECEIVED - RETURN - TRANSFER_IN - TRANSFER_OUT - SALE - PO_RECEIPT description: The type of inventory event. on_hand: type: integer format: int64 description: The on-hand quantity delta applied. unavailable: type: integer format: int64 description: The unavailable quantity delta applied. reserved: type: integer format: int64 description: The reserved quantity delta applied (for order-related events). event_timestamp: type: string format: date-time description: The timestamp when the event occurred. total_events_in_batch: type: integer description: Total number of events in the batch. sequence_number_in_batch: type: integer description: This event's sequence number within the batch. creation_date: type: string format: date-time description: The timestamp when the event record was created. source: $ref: '#/components/schemas/request-source' securitySchemes: OAuth2-Production: type: oauth2 flows: clientCredentials: tokenUrl: 'https://api.carriyo.com/oauth/token' scopes: {} OAuth2-Demo: type: oauth2 flows: clientCredentials: tokenUrl: 'https://demo-api.carriyo.com/oauth/token' scopes: {}