openapi: 3.0.1 info: title: Carriyo Orders API description: $ref: orders/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: Orders description: $ref: orders/order-object.md - name: Fulfillment Orders description: $ref: orders/fulfillment-orders.md paths: '/orders': post: tags: - Orders summary: Create Order operationId: create-order description: |- Creates a new order in Carriyo with the specified line items and customer details. ### Order Creation Flow When you create an order: 1. Carriyo validates the request and creates the order 2. Fulfillment orders are generated based on your specifications or automatic allocation 3. Inventory is reserved for the allocated items 4. Webhooks are triggered to notify your systems ### Fulfillment Order Allocation You can control how fulfillment orders are created: - **Automatic**: Omit `fulfillment_orders` and Carriyo allocates based on inventory and rules - **Manual**: Specify `fulfillment_orders` to control which items go to which locations ### Line Items Each line item represents a product in the order with: - Product identification (SKU, product ID) - Quantity ordered - Pricing information - Custom attributes ### Response The API returns the complete order object including: - Generated `order_id` for future reference - Fulfillment orders with their allocations - Initial order 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 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/create-order-request' responses: '201': description: Order created successfully. content: application/json: schema: $ref: '#/components/schemas/order' '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 '/orders/{reference}': patch: tags: - Orders summary: Update Order operationId: update-order description: |- Updates an existing order with the specified changes. This endpoint allows partial updates to order details, line items, and fulfillment orders. ### ⚠️ Important Warning This endpoint can be **dangerous if not used correctly**. The fulfillment orders (`fulfillment_orders`) field behaves as a **full replacement** - any fulfillment order not included in the request will be **permanently removed**. --- ### Update Behavior #### Simple Fields (Partial Update) The following fields are updated only if provided in the request: - `partner_order_reference`, `order_date`, `merchant`, `language`, `sales_channel` - `taxes_included`, `duties_included` - `shipping_address`, `billing_address`, `customer` - `payment`, `discount_applications`, `shipping_lines` #### Line Items (Full Replacement) If `line_items` is provided, it **completely replaces** the existing line items. Ensure you include all line items you want to keep. #### Fulfillment Orders (Full Replacement with Preservation Rules) If `fulfillment_orders` is provided: - **Any FO not included will be REMOVED** - Always include all FOs you want to keep - FOs are matched by `fulfillment_order_id` or `partner_fulfillment_order_reference` - New FOs (without matching ID) will be created with a new `fulfillment_order_id` --- ### Fulfillment Order Line Items - Critical Rules When updating FO line items, you must follow these rules: #### What to Include Only pass line items with **pending statuses**: - `open` - Items not yet allocated - `allocated` - Items allocated but not fulfilled #### What is Automatically Preserved The system **automatically preserves** line items with terminal statuses: - `fulfilled` - Items that have been fulfilled (will be added back automatically) - `cancelled` - Items that have been cancelled (will be added back automatically) - `closed` - Items that are closed (will be added back automatically) **You do NOT need to include fulfilled, cancelled, or closed line items in your request** - they will be preserved automatically. --- ### Example Scenarios #### Scenario 1: Adding a new line item to an FO If you have an FO with 2 items (item-1: open, item-2: fulfilled) and want to add item-3: ```json { "fulfillment_orders": [{ "fulfillment_order_id": "FO-123", "line_items": [ { "id": "item-1", "quantity": 1 }, { "id": "item-3", "quantity": 2 } ] }] } ``` Result: FO will have item-1 (open), item-2 (fulfilled - preserved), item-3 (open) #### Scenario 2: Removing a pending line item from an FO If you have an FO with 3 items and want to remove item-2 (which is open): ```json { "fulfillment_orders": [{ "fulfillment_order_id": "FO-123", "line_items": [ { "id": "item-1", "quantity": 1 }, { "id": "item-3", "quantity": 1 } ] }] } ``` #### Scenario 3: Moving a line item between FOs To move item-2 from FO-A to FO-B: ```json { "fulfillment_orders": [ { "fulfillment_order_id": "FO-A", "line_items": [{ "id": "item-1", "quantity": 1 }] }, { "fulfillment_order_id": "FO-B", "line_items": [ { "id": "item-2", "quantity": 1 }, { "id": "item-3", "quantity": 1 } ] } ] } ``` --- ### Common Mistakes to Avoid 1. **Forgetting to include all FOs**: If you only include one FO in the request, all other FOs will be deleted 2. **Including fulfilled/cancelled items**: Don't include them - they're preserved automatically. Including them may cause unexpected behavior 3. **Not matching FO identifiers**: Always use either `fulfillment_order_id` or `partner_fulfillment_order_reference` to match existing FOs 4. **Partial line item updates**: The line_items array replaces all pending items, so include all pending items you want to keep --- ### Order Status Restrictions Orders can only be updated when their status allows it: - ✅ `open`, `partially_allocated`, `allocated`, `partially_fulfilled`, `fulfilled`, `closed` - Can be updated - ❌ `cancelled` - Cannot be updated --- ### Inventory Impact If inventory management is enabled, updating FOs will automatically: - Reserve inventory for new FO allocations - Release inventory for removed FO allocations - Adjust inventory for quantity changes 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: reference in: path required: true schema: type: string description: The order reference (order_id or partner_order_reference based on the key parameter). - name: key in: query required: false schema: type: string enum: - order_id - partner_order_reference default: order_id description: |- Specifies which reference type is being used: - `order_id`: Carriyo's unique order identifier (default) - `partner_order_reference`: Your system's order reference requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/update-order-request' responses: '200': description: Order updated successfully. content: application/json: schema: $ref: '#/components/schemas/order' '400': description: Invalid request or order cannot be updated in current status. content: application/json: schema: $ref: '#/components/schemas/error-response' '404': description: Order not found. content: application/json: schema: $ref: '#/components/schemas/error-response' '409': description: Concurrent update detected. Retry the request. content: application/json: schema: $ref: '#/components/schemas/error-response' security: - OAuth2-Production: [] - OAuth2-Demo: [] x-codegen-request-body-name: body get: tags: - Orders summary: Get Order operationId: get-order description: |- Retrieves the complete details of an order by its reference. ### Reference Types You can retrieve an order using: - **Carriyo Order ID**: The unique identifier generated by Carriyo (default) - **Partner Order Reference**: Your system's order reference by setting `key=partner_order_reference` ### Response Returns the full order object including: - Order details and status - All fulfillment orders and their current states - Line item details and fulfillment status - Customer and address information 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: reference in: path required: true schema: type: string description: The order reference (order_id or partner_order_reference based on the key parameter). - name: key in: query required: false schema: type: string enum: - order_id - partner_order_reference default: order_id description: |- Specifies which reference type is being used: - `order_id`: Carriyo's unique order identifier (default) - `partner_order_reference`: Your system's order reference responses: '200': description: Order retrieved successfully. content: application/json: schema: $ref: '#/components/schemas/order' '404': description: Order not found. content: application/json: schema: $ref: '#/components/schemas/error-response' security: - OAuth2-Production: [] - OAuth2-Demo: [] '/orders/{reference}/cancel': post: tags: - Orders summary: Cancel Order operationId: cancel-order description: |- Cancels an order and all its associated fulfillment orders. ### Status Requirements Orders can **only** be cancelled when in one of these statuses: - ✅ `open` - Order has been created but not yet allocated - ✅ `allocated` - Order is fully allocated to fulfillment locations - ✅ `partially_allocated` - Order is partially allocated Orders **cannot** be cancelled when in these statuses: - ❌ `partially_fulfilled` - Some items have already been shipped - ❌ `fulfilled` - All items have been shipped - ❌ `closed` - Order has been closed - ❌ `cancelled` - Order is already cancelled ### Cancellation Effects When an order is successfully cancelled: - All line items quantities are set to 0 with removed quantities recorded - All fulfillment order line items are marked as `cancelled` - Reserved inventory is released back to stock - Order status is updated to `cancelled` - Webhooks are triggered to notify your systems ### Cancellation Reason You must provide a `cancellation_reason` which is one of the predefined enum values: - `CUSTOMER_CANCELLATION` - Customer requested cancellation - `AUTO_ALLOCATION_FAILED` - Automatic fulfillment allocation failed - `INVENTORY_OUT_OF_STOCK` - Items are out of stock - `STAFF_ERROR` - Staff made an error - `PAYMENT_ISSUE` - Payment problem occurred - `OTHER` - Other reason 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: reference in: path required: true schema: type: string description: The order reference (order_id or partner_order_reference based on the key parameter). - name: key in: query required: false schema: type: string enum: - order_id - partner_order_reference default: order_id description: |- Specifies which reference type is being used: - `order_id`: Carriyo's unique order identifier (default) - `partner_order_reference`: Your system's order reference requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/cancel-order-request' responses: '200': description: Order cancelled successfully. content: application/json: schema: $ref: '#/components/schemas/order' '400': description: Order cannot be cancelled. content: application/json: schema: $ref: '#/components/schemas/error-response' '404': description: Order not found. content: application/json: schema: $ref: '#/components/schemas/error-response' security: - OAuth2-Production: [] - OAuth2-Demo: [] x-codegen-request-body-name: body '/orders/bulk/import': post: tags: - Orders summary: Bulk Import Orders operationId: bulk-import-orders description: |- Creates multiple orders in a single request for efficient batch processing. ### Use Cases - Migrating orders from another system - Processing batch uploads from sales channels - Syncing orders from offline sources ### Processing Each order in the batch is processed independently: - Valid orders are created successfully - Invalid orders return error details - Processing continues even if some orders fail ### Limits - Maximum 20 orders per request - Each order follows the same validation as single order creation ### Response Returns a list of results for each order: - Successfully created orders include the full order object - Failed orders include error details for troubleshooting 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 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/bulk-order-import-request' responses: '200': description: Bulk import processed. content: application/json: schema: type: array items: $ref: '#/components/schemas/bulk-order-import-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 '/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderId}/fulfill': post: tags: - Fulfillment Orders summary: Fulfill Order operationId: fulfill-order description: |- Marks items in a fulfillment order as fulfilled and creates a shipment. ### Line Item Status Requirements Only items in **pending status** (`open` or `allocated`) can be fulfilled: - ✅ `open` - Item awaiting allocation - ✅ `allocated` - Item assigned to a location - ❌ `fulfilled` - Already fulfilled - ❌ `cancelled` - Cannot be fulfilled - ❌ `closed` - Cannot be fulfilled ### Fulfillment Process When you fulfill an order: 1. Validates that requested line items exist and are in pending status 2. Validates that requested quantities don't exceed available quantities 3. Creates a shipment (unless `skip_shipping=true`) 4. Marks line items as `fulfilled` with a unique fulfillment ID 5. Updates order status based on overall fulfillment progress 6. Triggers webhooks ### Line Items (Required) You must provide `line_items` array specifying which items to fulfill: - Each item needs `id` matching an order line item - Each item needs `quantity` to fulfill (must be ≤ pending quantity) ### Shipment Creation Control shipment creation with query parameters: - `create_draft_shipment=true`: Creates a draft shipment for review before carrier booking - `skip_shipping=true`: Fulfills without creating any shipment (items auto-close) ### Inventory Impact If inventory management is enabled with `stock_reduction_timing = ON_ORDER_FULFILLED`: - `on_hand` is reduced by the fulfilled quantity - `reserved` is reduced by the fulfilled quantity If shipping is not required (or `skip_shipping=true`), items are automatically set to `closed` 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: orderReference in: path required: true schema: type: string description: The order reference (order_id or partner_order_reference based on the key parameter). - name: fulfillmentOrderId in: path required: true schema: type: string description: The unique identifier of the fulfillment order. - name: key in: query required: false schema: type: string enum: - order_id - partner_order_reference default: order_id description: Specifies which reference type is being used for the order reference. - name: create_draft_shipment in: query required: false schema: type: boolean default: false description: If true, creates a draft shipment instead of immediately booking with a carrier. - name: skip_shipping in: query required: false schema: type: boolean default: false description: If true, fulfills the order without creating a shipment. requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/create-fulfillment-request' responses: '200': description: Fulfillment order fulfilled successfully. content: application/json: schema: $ref: '#/components/schemas/order' '400': description: Invalid request or fulfillment not possible. content: application/json: schema: $ref: '#/components/schemas/error-response' '404': description: Order or fulfillment order not found. content: application/json: schema: $ref: '#/components/schemas/error-response' security: - OAuth2-Production: [] - OAuth2-Demo: [] x-codegen-request-body-name: body '/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderId}/unfulfill': post: tags: - Fulfillment Orders summary: Unfulfill Order operationId: unfulfill-order description: |- Reverses a previous fulfillment, returning items to `allocated` status. ### When to Unfulfill Use this endpoint when: - Items were fulfilled in error - Stock is discovered to be unavailable after fulfillment - The fulfillment needs to be reassigned to another location - A shipment was cancelled before pickup ### Request Requirements You must provide: - `fulfillment_ids`: Array of fulfillment IDs to reverse (required) - The fulfillment IDs must exist in the fulfillment order's fulfilled line items ### Effects When you unfulfill: 1. Associated shipments are cancelled (if not already cancelled) 2. Line items return to `allocated` status 3. Fulfillment ID, shipment IDs, and partner reference are cleared from items 4. Items with the same ID and status are merged 5. Order status is recalculated 6. Webhooks are triggered ### Inventory Impact If inventory management is enabled: - `on_hand` is increased by the unfulfilled quantity (restoring stock) 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: orderReference in: path required: true schema: type: string description: The order reference (order_id or partner_order_reference based on the key parameter). - name: fulfillmentOrderId in: path required: true schema: type: string description: The unique identifier of the fulfillment order. - name: key in: query required: false schema: type: string enum: - order_id - partner_order_reference default: order_id description: Specifies which reference type is being used for the order reference. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/unfulfill-fulfillment-request' responses: '200': description: Fulfillment reversed successfully. content: application/json: schema: $ref: '#/components/schemas/order' '400': description: Cannot unfulfill - items may already be shipped. content: application/json: schema: $ref: '#/components/schemas/error-response' '404': description: Order or fulfillment order not found. content: application/json: schema: $ref: '#/components/schemas/error-response' security: - OAuth2-Production: [] - OAuth2-Demo: [] x-codegen-request-body-name: body '/orders/{orderReference}/fulfillment-orders/merge': post: tags: - Fulfillment Orders summary: Merge Fulfillment Orders operationId: merge-fulfillment-orders description: |- Combines line items from one fulfillment order into another. ### Use Cases - Consolidating shipments to reduce shipping costs - Combining split orders when inventory becomes available at one location - Optimizing fulfillment operations ### Merge Process Specify: - **Source**: The fulfillment order (with specific line items) to merge from - **Destination**: The fulfillment order to merge into After merging: - Source line items are moved to the destination fulfillment order - If all items are moved, the source fulfillment order is removed - Order status is recalculated - Webhooks are triggered ### Restrictions Both source and destination fulfillment orders: - ❌ Cannot have any fulfilled line items (only pending items can be merged) - ✅ Must have the same `location_id` - ✅ Must have the same `delivery_type` (if specified) - ✅ Must have the same delivery method (from metadata) - ❌ Cannot mix items where some require shipping and some don't ### Inventory Impact No direct inventory changes occur during merge - items are simply reorganized between fulfillment orders. 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: orderReference in: path required: true schema: type: string description: The order reference (order_id or partner_order_reference based on the key parameter). - name: key in: query required: false schema: type: string enum: - order_id - partner_order_reference default: order_id description: Specifies which reference type is being used for the order reference. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/merge-fulfillment-order-request' responses: '200': description: Fulfillment orders merged successfully. content: application/json: schema: $ref: '#/components/schemas/order' '400': description: Cannot merge fulfillment orders. content: application/json: schema: $ref: '#/components/schemas/error-response' '404': description: Order or fulfillment orders not found. content: application/json: schema: $ref: '#/components/schemas/error-response' security: - OAuth2-Production: [] - OAuth2-Demo: [] x-codegen-request-body-name: body '/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderId}/split': post: tags: - Fulfillment Orders summary: Split Fulfillment Order operationId: split-fulfillment-order description: |- Splits selected line items from a fulfillment order into a new fulfillment order. ### Use Cases - Shipping available items immediately while backordered items wait - Fulfilling from multiple locations when partial inventory exists - Separating items with different shipping requirements ### Line Item Status Requirements Only items in **pending status** (`open` or `allocated`) can be split: - ✅ `open` - Can be split - ✅ `allocated` - Can be split - ❌ `fulfilled` - Cannot be split - ❌ `cancelled` - Cannot be split - ❌ `closed` - Cannot be split ### Split Process Specify: - `line_items` (required): Items and quantities to move to the new FO - `location_id` (optional): New location for the split items (defaults to original FO's location) - `partner_fulfillment_order_reference` (optional): Your reference for the new FO After splitting: - A new fulfillment order is created with a new `fulfillment_order_id` - The new FO inherits `delivery` and `carriyo_metadata` from the original - Line items get status `allocated` if location is set, otherwise `open` - Original FO quantities are reduced (items removed if quantity becomes 0) - Order status is recalculated - Webhooks are triggered ### Inventory Impact No direct inventory changes occur during split - items are simply reorganized. 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: orderReference in: path required: true schema: type: string description: The order reference (order_id or partner_order_reference based on the key parameter). - name: fulfillmentOrderId in: path required: true schema: type: string description: The unique identifier of the fulfillment order to split. - name: key in: query required: false schema: type: string enum: - order_id - partner_order_reference default: order_id description: Specifies which reference type is being used for the order reference. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/split-fulfillment-request' responses: '200': description: Fulfillment order split successfully. content: application/json: schema: $ref: '#/components/schemas/order' '400': description: Cannot split fulfillment order. content: application/json: schema: $ref: '#/components/schemas/error-response' '404': description: Order or fulfillment order not found. content: application/json: schema: $ref: '#/components/schemas/error-response' security: - OAuth2-Production: [] - OAuth2-Demo: [] x-codegen-request-body-name: body '/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderId}/cancel': post: tags: - Fulfillment Orders summary: Cancel Fulfillment Order Line Items operationId: cancel-fulfillment-order-line-items description: |- Cancels specific line items within a fulfillment order. ### Line Item Status Requirements Only items in **pending status** (`open` or `allocated`) can be cancelled: - ✅ `open` - Can be cancelled - ✅ `allocated` - Can be cancelled - ❌ `fulfilled` - Cannot be cancelled (use unfulfill first) - ❌ `cancelled` - Already cancelled - ❌ `closed` - Cannot be cancelled ### Request Requirements (All Required) - `cancellation_reason` (required): One of the predefined enum values - `line_items` (required): Array of items to cancel with quantities ### Cancellation Reason Values - `CUSTOMER_CANCELLATION` - Customer requested cancellation - `AUTO_ALLOCATION_FAILED` - Automatic fulfillment allocation failed - `INVENTORY_OUT_OF_STOCK` - Items are out of stock - `STAFF_ERROR` - Staff made an error - `PAYMENT_ISSUE` - Payment problem occurred - `OTHER` - Other reason ### Cancellation Effects When items are cancelled: 1. Item status is updated to `cancelled` with the cancellation reason 2. Order line item's `removed_quantities` is updated 3. Order status is recalculated 4. Webhooks are triggered ### Inventory Impact If inventory management is enabled and the FO has a `location_id`: - `reserved` is decreased by the cancelled quantity (releasing reserved stock) 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: orderReference in: path required: true schema: type: string description: The order reference (order_id or partner_order_reference based on the key parameter). - name: fulfillmentOrderId in: path required: true schema: type: string description: The unique identifier of the fulfillment order. - name: key in: query required: false schema: type: string enum: - order_id - partner_order_reference default: order_id description: Specifies which reference type is being used for the order reference. requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/cancel-fo-line-items-request' responses: '200': description: Line items cancelled successfully. content: application/json: schema: $ref: '#/components/schemas/order' '400': description: Cannot cancel line items. content: application/json: schema: $ref: '#/components/schemas/error-response' '404': description: Order or fulfillment order not found. content: application/json: schema: $ref: '#/components/schemas/error-response' security: - OAuth2-Production: [] - OAuth2-Demo: [] x-codegen-request-body-name: body '/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderId}/ship': post: tags: - Fulfillment Orders summary: Ship Fulfillment Order operationId: ship-fulfillment-order description: |- Creates a shipment for items in a fulfillment order. ### Line Item Status Requirements Items must be in `allocated` or `fulfilled` status: - ✅ `allocated` - Can be shipped - ✅ `fulfilled` - Can be shipped (additional shipment) - ❌ `open` - Must be allocated first - ❌ `cancelled` - Cannot be shipped - ❌ `closed` - Cannot be shipped ### Request Requirements - `line_items` (required): Array of items to ship with quantities ### Shipping Process This endpoint: 1. Validates that requested items exist in `allocated` or `fulfilled` status 2. Validates that requested quantities don't exceed available quantities 3. Creates a draft shipment in the Carriyo Shipping API 4. Confirms the shipment with the carrier (unless `create_draft_shipment=true`) 5. Links the shipment ID to the specified line items 6. Triggers webhooks ### Shipment Configuration Configure the shipment with: - **Carrier Account**: Specify carrier or let automation rules decide - **Parcels**: Dimensions, weights, and contents - **Delivery**: Instructions and scheduling preferences - **Payment**: Cash on delivery and payment details - **Pre-booking**: For externally booked shipments ### Draft Shipments Set `create_draft_shipment=true` to create a draft for review before booking with the carrier. ### Inventory Impact No direct inventory changes occur - inventory is managed during fulfill/cancel operations. 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: orderReference in: path required: true schema: type: string description: The order reference (order_id or partner_order_reference based on the key parameter). - name: fulfillmentOrderId in: path required: true schema: type: string description: The unique identifier of the fulfillment order. - name: key in: query required: false schema: type: string enum: - order_id - partner_order_reference default: order_id description: Specifies which reference type is being used for the order reference. - name: create_draft_shipment in: query required: false schema: type: boolean default: false description: If true, creates a draft shipment instead of immediately booking with a carrier. requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/ship-fo-line-items-request' responses: '200': description: Shipment created successfully. content: application/json: schema: $ref: '#/components/schemas/order' '400': description: Cannot create shipment. content: application/json: schema: $ref: '#/components/schemas/error-response' '404': description: Order or fulfillment order not found. content: application/json: schema: $ref: '#/components/schemas/error-response' security: - OAuth2-Production: [] - OAuth2-Demo: [] x-codegen-request-body-name: body '/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderId}/update-location': patch: tags: - Fulfillment Orders summary: Update Fulfillment Order Location operationId: update-fulfillment-order-location description: |- Updates the assigned location for a fulfillment order. ### Use Cases - Reassigning to a location with available inventory - Optimizing fulfillment based on proximity to customer - Correcting initial allocation decisions ### Request Requirements - `location_id` (required): The new location ID or location code ### Location Resolution The location is resolved in this order: 1. First tries to find by `partner_location_id` 2. If not found, tries to find by `location_code` for the merchant ### Effects When location is updated: - Fulfillment order's `location_id` is updated to the new location - Order status is recalculated - Webhooks are triggered ### Inventory Impact No direct inventory changes occur during location update. If you need to manage inventory reservations when changing locations, you should handle this separately through the Inventory API. 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: orderReference in: path required: true schema: type: string description: The order reference (order_id or partner_order_reference based on the key parameter). - name: fulfillmentOrderId in: path required: true schema: type: string description: The unique identifier of the fulfillment order. - name: key in: query required: false schema: type: string enum: - order_id - partner_order_reference default: order_id description: Specifies which reference type is being used for the order reference. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/update-location-request' responses: '200': description: Location updated successfully. content: application/json: schema: $ref: '#/components/schemas/order' '400': description: Cannot update location. content: application/json: schema: $ref: '#/components/schemas/error-response' '404': description: Order or fulfillment order not found. content: application/json: schema: $ref: '#/components/schemas/error-response' security: - OAuth2-Production: [] - OAuth2-Demo: [] x-codegen-request-body-name: body '/orders/{orderReference}/fulfillment-orders/{fulfillmentOrderId}': patch: tags: - Fulfillment Orders summary: Update Fulfillment Order operationId: update-fulfillment-order description: |- Updates fulfillment order details including references and fulfillment information. ### Updatable Fields You can update one of the following (not both in same request): - **`partner_fulfillment_order_reference`**: Your system's reference for the fulfillment order - **`fulfillments`**: Update `partner_fulfillment_reference` for individual fulfilled items ### Updating Fulfillments When updating fulfillments, you must provide: - `fulfillment_id`: Must match an existing fulfillment ID in the FO's fulfilled items - `partner_fulfillment_reference`: Your new reference for this fulfillment ### Use Cases - Updating references after external system sync - Linking fulfillments to your system's tracking - Correcting fulfillment information ### Inventory Impact No inventory changes occur - this endpoint only updates reference fields. 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: orderReference in: path required: true schema: type: string description: The order reference (order_id or partner_order_reference based on the key parameter). - name: fulfillmentOrderId in: path required: true schema: type: string description: The unique identifier of the fulfillment order. - name: key in: query required: false schema: type: string enum: - order_id - partner_order_reference default: order_id description: Specifies which reference type is being used for the order reference. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/patch-fo-details-request' responses: '200': description: Fulfillment order updated successfully. content: application/json: schema: $ref: '#/components/schemas/order' '400': description: Cannot update fulfillment order. content: application/json: schema: $ref: '#/components/schemas/error-response' '404': description: Order or fulfillment order not found. content: application/json: schema: $ref: '#/components/schemas/error-response' security: - OAuth2-Production: [] - OAuth2-Demo: [] x-codegen-request-body-name: body 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. details: type: array items: type: object properties: field: type: string message: type: string description: Detailed error information for specific fields. create-order-request: title: Create Order Request type: object required: - merchant - line_items properties: merchant: type: string description: The merchant identifier for this order. partner_order_reference: type: string description: Your system's unique order reference for correlation. language: type: string description: Language code for customer communications (e.g., "en", "ar"). order_date: type: string format: date-time description: The date when the order was placed (ISO 8601 format). sales_channel: type: string description: The sales channel where the order originated (e.g., "web", "mobile", "store"). carriyo_metadata: type: array items: $ref: '#/components/schemas/carriyo-metadata' description: Custom key-value metadata for the order. shipping_address: $ref: '#/components/schemas/address' billing_address: $ref: '#/components/schemas/address' customer: $ref: '#/components/schemas/address' payment: $ref: '#/components/schemas/order-payment' taxes_included: type: boolean description: Whether prices include taxes. duties_included: type: boolean description: Whether prices include duties. discount_applications: type: array items: $ref: '#/components/schemas/discount-application' description: Discounts applied to the order. line_items: type: array items: $ref: '#/components/schemas/line-item' description: Products ordered with quantities and prices. fulfillment_orders: type: array items: $ref: '#/components/schemas/fulfillment-order-request' description: Optional explicit fulfillment order specifications. shipping_lines: type: array items: $ref: '#/components/schemas/shipping-line' description: Shipping methods and costs. order: title: Order type: object properties: tenant: type: string description: The tenant identifier. order_id: type: string description: Carriyo's unique identifier for the order. merchant: type: string description: The merchant identifier. partner_order_reference: type: string description: Your system's order reference. language: type: string description: Language code for customer communications. order_date: type: string format: date-time description: The date when the order was placed. sales_channel: type: string description: The sales channel where the order originated. creation_source: $ref: '#/components/schemas/request-source' update_source: $ref: '#/components/schemas/request-source' carriyo_metadata: type: array items: $ref: '#/components/schemas/carriyo-metadata' description: Custom metadata for the order. status: type: string enum: - open - partially_allocated - allocated - cancelled - partially_fulfilled - fulfilled - closed description: |- Current status of the order: - `open` - Order created, not yet allocated - `partially_allocated` - Some items allocated to fulfillment locations - `allocated` - All items allocated to fulfillment locations - `cancelled` - Order has been cancelled - `partially_fulfilled` - Some items have been shipped - `fulfilled` - All items have been shipped - `closed` - Order is complete and closed auto_allocation_failed: type: boolean description: Whether automatic fulfillment allocation failed. cancellation_reason: $ref: '#/components/schemas/cancellation-reason' shipping_address: $ref: '#/components/schemas/address' billing_address: $ref: '#/components/schemas/address' customer: $ref: '#/components/schemas/address' payment: $ref: '#/components/schemas/order-payment' redacted: type: boolean description: Whether personal data has been redacted. taxes_included: type: boolean description: Whether prices include taxes. duties_included: type: boolean description: Whether prices include duties. discount_applications: type: array items: $ref: '#/components/schemas/discount-application' line_items: type: array items: $ref: '#/components/schemas/line-item' fulfillment_orders: type: array items: $ref: '#/components/schemas/fulfillment-order' shipping_lines: type: array items: $ref: '#/components/schemas/shipping-line' error_details: type: array items: $ref: '#/components/schemas/error-detail' description: Any errors that occurred during order processing. creation_date: type: string format: date-time description: When the order was created in Carriyo. update_date: type: string format: date-time description: When the order was last updated. update-order-request: title: Update Order Request type: object description: |- Request body for updating an order. All fields are optional - only include fields you want to update. **Warning**: The `fulfillment_orders` field is a full replacement. Include ALL fulfillment orders you want to keep. properties: partner_order_reference: type: string description: Your system's unique order reference. order_date: type: string format: date-time description: The date when the order was placed (ISO 8601 format). merchant: type: string description: The merchant identifier. language: type: string description: Language code for customer communications. sales_channel: type: string description: The sales channel where the order originated. taxes_included: type: boolean description: Whether prices include taxes. duties_included: type: boolean description: Whether prices include duties. shipping_address: $ref: '#/components/schemas/address' billing_address: $ref: '#/components/schemas/address' customer: $ref: '#/components/schemas/address' payment: $ref: '#/components/schemas/order-payment' discount_applications: type: array items: $ref: '#/components/schemas/discount-application' shipping_lines: type: array items: $ref: '#/components/schemas/shipping-line' line_items: type: array description: |- **Full replacement** - If provided, completely replaces all existing line items. Include all line items you want to keep. items: $ref: '#/components/schemas/update-line-item-request' fulfillment_orders: type: array description: |- **Full replacement with preservation rules**. ⚠️ **Critical**: Any fulfillment order NOT included in this array will be PERMANENTLY REMOVED. For each FO's line_items: - Only include `open` and `allocated` status items - `fulfilled`, `cancelled`, and `closed` items are automatically preserved items: $ref: '#/components/schemas/update-fulfillment-order-request' update-line-item-request: title: Update Line Item Request type: object required: - id - sku - requires_shipping properties: id: type: string description: Unique identifier for the line item. Must match an existing line item ID to update, or be new to add. sku: type: string description: Stock keeping unit. origin_country: type: string description: Country of origin (ISO 3166-1 alpha-2 code). description: type: string description: Product description. barcode: type: string description: Product barcode. requires_shipping: type: boolean description: Whether this item requires shipping. quantity: type: integer description: Quantity ordered. If reduced, the difference is tracked as removed quantity. unit_price: type: number format: double description: Unit price of the item. unit_cost: type: number format: double description: Unit cost of the item. discount_allocations: type: array items: $ref: '#/components/schemas/discount-allocation' taxes: type: array items: $ref: '#/components/schemas/tax' duties: type: array items: $ref: '#/components/schemas/duty' weight: $ref: '#/components/schemas/weight' dimension: $ref: '#/components/schemas/dimension' image_link: type: string description: URL to product image. product_ref: type: string description: Product reference in your system. product_id: type: string description: Product identifier. hs_code: type: string description: Harmonized System code for customs. manufacturer_id: type: string description: Manufacturer identifier. material_composition: type: string description: Material composition of the product. dangerous_goods: type: boolean description: Whether the item contains dangerous goods. battery: $ref: '#/components/schemas/battery' update-fulfillment-order-request: title: Update Fulfillment Order Request type: object description: |- Request to update a fulfillment order. Use either `fulfillment_order_id` or `partner_fulfillment_order_reference` to identify existing FOs. If neither identifier matches an existing FO, a new FO will be created. properties: fulfillment_order_id: type: string description: |- Carriyo's unique identifier for the fulfillment order. Use this to match and update an existing FO. partner_fulfillment_order_reference: type: string description: |- Your system's reference for the fulfillment order. Can be used as an alternative to `fulfillment_order_id` for matching existing FOs. location_id: type: string description: The location ID where items will be fulfilled. delivery: $ref: '#/components/schemas/delivery' line_items: type: array description: |- Line items for this fulfillment order. **Important Rules**: - Only include items with `open` or `allocated` status - Do NOT include `fulfilled`, `cancelled`, or `closed` items - they are preserved automatically - This replaces all pending items in the FO items: $ref: '#/components/schemas/fo-line-item-request' carriyo_metadata: type: array items: $ref: '#/components/schemas/carriyo-metadata' discount-allocation: title: Discount Allocation type: object properties: amount: type: number format: double discount_application_index: type: integer tax: title: Tax type: object properties: title: type: string rate: type: number format: double amount: type: number format: double duty: title: Duty type: object properties: title: type: string amount: type: number format: double weight: title: Weight type: object properties: value: type: number format: double unit: type: string enum: - kg - g - lb - oz dimension: title: Dimension type: object properties: length: type: number format: double width: type: number format: double height: type: number format: double unit: type: string enum: - cm - in battery: title: Battery type: object properties: type: type: string description: Type of battery (e.g., lithium-ion, lithium-metal). packing: type: string description: How the battery is packed. quantity: type: integer description: Number of batteries. cancel-order-request: title: Cancel Order Request type: object properties: cancellation_reason: $ref: '#/components/schemas/cancellation-reason' bulk-order-import-request: title: Bulk Order Import Request type: object properties: order_requests: type: array items: $ref: '#/components/schemas/create-order-request' description: Array of orders to create (maximum 20). bulk-order-import-response: title: Bulk Order Import Response type: object properties: order: $ref: '#/components/schemas/order' error: type: string description: Error message if order creation failed. partner_order_reference: type: string description: The partner reference from the request for correlation. fulfillment-order-request: title: Fulfillment Order Request type: object properties: partner_fulfillment_order_reference: type: string description: Your system's reference for this fulfillment order. location_id: type: string description: The location ID where items will be fulfilled. line_items: type: array items: $ref: '#/components/schemas/fo-line-item-request' description: Line items to include in this fulfillment order. delivery: $ref: '#/components/schemas/delivery' carriyo_metadata: type: array items: $ref: '#/components/schemas/carriyo-metadata' fulfillment-order: title: Fulfillment Order type: object properties: fulfillment_order_id: type: string description: Carriyo's unique identifier for the fulfillment order. partner_fulfillment_order_reference: type: string description: Your system's reference for this fulfillment order. location_id: type: string description: The location ID where items are being fulfilled. delivery: $ref: '#/components/schemas/delivery' line_items: type: array items: $ref: '#/components/schemas/fo-line-item' carriyo_metadata: type: array items: $ref: '#/components/schemas/carriyo-metadata' create-fulfillment-request: title: Create Fulfillment Request type: object properties: partner_fulfillment_reference: type: string description: Your system's reference for this fulfillment. line_items: type: array items: $ref: '#/components/schemas/fo-line-item-request' description: Specific line items to fulfill. Omit to fulfill all pending items. carrier_account: $ref: '#/components/schemas/carrier-account-request' parcels: type: array items: $ref: '#/components/schemas/parcel-request' description: Parcel details for the shipment. delivery: $ref: '#/components/schemas/fulfillment-delivery' payment: $ref: '#/components/schemas/fulfillment-payment' pre_booking_info: $ref: '#/components/schemas/pre-booking-info' unfulfill-fulfillment-request: title: Unfulfill Fulfillment Request type: object properties: fulfillment_ids: type: array items: type: string description: List of fulfillment IDs to reverse. partner_fulfillment_order_reference: type: string description: Partner reference to identify the fulfillment to reverse. merge-fulfillment-order-request: title: Merge Fulfillment Order Request type: object required: - source - destination properties: source: type: object properties: fulfillment_order_id: type: string description: The source fulfillment order ID. partner_fulfillment_order_reference: type: string description: Alternative source identification by partner reference. line_items: type: array items: $ref: '#/components/schemas/fo-line-item-request' description: Specific items to merge. Omit to merge all. description: The fulfillment order to merge from. destination: type: object properties: fulfillment_order_id: type: string description: The destination fulfillment order ID. partner_fulfillment_order_reference: type: string description: Alternative destination identification by partner reference. description: The fulfillment order to merge into. split-fulfillment-request: title: Split Fulfillment Request type: object required: - line_items properties: line_items: type: array items: $ref: '#/components/schemas/fo-line-item-request' description: Line items to move to the new fulfillment order. partner_fulfillment_order_reference: type: string description: Partner reference for the new fulfillment order. location_id: type: string description: Optional new location for the split fulfillment order. cancel-fo-line-items-request: title: Cancel Fulfillment Order Line Items Request type: object properties: cancellation_reason: $ref: '#/components/schemas/cancellation-reason' line_items: type: array items: $ref: '#/components/schemas/fo-line-item-request' description: Specific line items to cancel. Omit to cancel all pending items. ship-fo-line-items-request: title: Ship Fulfillment Order Line Items Request type: object properties: line_items: type: array items: $ref: '#/components/schemas/fo-line-item-request' description: Specific fulfilled items to ship. Omit to ship all fulfilled items. carrier_account: $ref: '#/components/schemas/carrier-account-request' parcels: type: array items: $ref: '#/components/schemas/parcel-request' delivery: $ref: '#/components/schemas/fulfillment-delivery' payment: $ref: '#/components/schemas/fulfillment-payment' pre_booking_info: $ref: '#/components/schemas/pre-booking-info' update-location-request: title: Update Location Request type: object required: - location_id properties: location_id: type: string description: The new location ID for the fulfillment order. patch-fo-details-request: title: Patch Fulfillment Order Details Request type: object description: Request body for PATCH /orders/{orderReference}/fulfillment-orders/{fulfillmentOrderId} endpoint. properties: partner_fulfillment_order_reference: type: string description: Updated partner reference for the fulfillment order. fulfillments: type: array items: $ref: '#/components/schemas/update-fulfillment-request' description: Updates to existing fulfillments. update-fulfillment-request: title: Update Fulfillment Request type: object properties: fulfillment_id: type: string description: The fulfillment ID to update. partner_fulfillment_reference: type: string description: Updated partner reference. address: title: Address type: object properties: name: type: string description: Full name of the contact. company: type: string description: Company name. email: type: string format: email description: Email address. phone: type: string description: Primary phone number. alternate_phone: type: string description: Alternative phone number. address1: type: string description: Street address line 1. address2: type: string description: Street address line 2. city: type: string description: City name. state: type: string description: State or province. postcode: type: string description: Postal or ZIP code. country: type: string description: Country code (ISO 3166-1 alpha-2). coords: type: string description: Geographic coordinates (latitude,longitude). what3words: type: string description: what3words address. carriyo-metadata: title: Carriyo Metadata type: object properties: key: type: string description: Metadata key. value: type: string description: Metadata value. order-payment: title: Order Payment type: object properties: payment_mode: type: string enum: - prepaid - cash_on_delivery - card_on_delivery description: The payment method for the order. pending_amount: type: number format: double description: Amount pending to be collected. currency: type: string description: Currency code (ISO 4217). discount-application: title: Discount Application type: object properties: code: type: string description: Discount code applied. type: type: string description: Type of discount (e.g., percentage, fixed). value: type: number format: double description: Discount value. description: type: string description: Description of the discount. line-item: title: Line Item type: object properties: line_item_id: type: string description: Unique identifier for the line item. sku: type: string description: Stock keeping unit. product_id: type: string description: Product identifier in your system. name: type: string description: Product name. description: type: string description: Product description. quantity: type: integer description: Quantity ordered. price: type: number format: double description: Unit price. currency: type: string description: Currency code. weight: type: number format: double description: Weight of the item. weight_unit: type: string enum: - kg - g - lb - oz description: Unit of weight measurement. image_url: type: string description: URL to product image. properties: type: object additionalProperties: type: string description: Custom properties for the line item. fo-line-item-request: title: Fulfillment Order Line Item Request type: object properties: line_item_id: type: string description: Reference to the order line item. quantity: type: integer description: Quantity to fulfill. fo-line-item: title: Fulfillment Order Line Item type: object properties: line_item_id: type: string description: Reference to the order line item. quantity: type: integer description: Quantity in this fulfillment order. status: type: string enum: - open - allocated - cancelled - fulfilled - closed description: |- Current status of the line item: - `open` - Item is pending allocation - `allocated` - Item is allocated and ready for fulfillment - `cancelled` - Item has been cancelled - `fulfilled` - Item has been fulfilled/shipped - `closed` - Item is complete and closed fulfillment_id: type: string description: ID of the fulfillment if fulfilled. shipment_ids: type: array items: type: string description: IDs of shipments containing this item. shipping-line: title: Shipping Line type: object properties: code: type: string description: Shipping method code. title: type: string description: Display name for the shipping method. price: type: number format: double description: Shipping cost. currency: type: string description: Currency code. delivery: title: Delivery type: object properties: delivery_type: type: string description: Type of delivery. time_slot: $ref: '#/components/schemas/time-slot' instructions: type: string description: Delivery instructions. time-slot: title: Time Slot type: object properties: date: type: string format: date description: Delivery date. from: type: string description: Start time (HH:mm format). to: type: string description: End time (HH:mm format). fulfillment-delivery: title: Fulfillment Delivery type: object properties: delivery_type: type: string description: Type of delivery. time_slot: $ref: '#/components/schemas/time-slot' instructions: type: string description: Delivery instructions. fulfillment-payment: title: Fulfillment Payment type: object properties: payment_mode: type: string enum: - prepaid - cash_on_delivery - card_on_delivery pending_amount: type: number format: double currency: type: string carrier-account-request: title: Carrier Account Request type: object properties: carrier: type: string description: Carrier code. carrier_account_id: type: string description: Specific carrier account ID to use. parcel-request: title: Parcel Request type: object properties: length: type: number format: double description: Length of the parcel. width: type: number format: double description: Width of the parcel. height: type: number format: double description: Height of the parcel. dimension_unit: type: string enum: - cm - in description: Unit of dimension measurement. weight: type: number format: double description: Weight of the parcel. weight_unit: type: string enum: - kg - g - lb - oz description: Unit of weight measurement. description: type: string description: Description of parcel contents. pre-booking-info: title: Pre-Booking Info type: object properties: input_carrier: type: string description: Carrier used for pre-booking. carrier_tracking_no: type: string description: Tracking number from the carrier. awb_pdf_link: type: string description: URL to the AWB PDF. cancellation-reason: title: Cancellation Reason type: string description: |- The reason for cancellation. Must be one of the following values: - `CUSTOMER_CANCELLATION` - Customer requested cancellation - `AUTO_ALLOCATION_FAILED` - Automatic fulfillment allocation failed - `INVENTORY_OUT_OF_STOCK` - Items are out of stock - `STAFF_ERROR` - Staff made an error - `PAYMENT_ISSUE` - Payment problem occurred - `OTHER` - Other reason enum: - CUSTOMER_CANCELLATION - AUTO_ALLOCATION_FAILED - INVENTORY_OUT_OF_STOCK - STAFF_ERROR - PAYMENT_ISSUE - OTHER example: CUSTOMER_CANCELLATION request-source: title: Request Source type: object properties: source: type: string description: The source system (e.g., API, UI, CONNECTOR). user_id: type: string description: User or system identifier. ip_address: type: string description: IP address of the request origin. error-detail: title: Error Detail type: object properties: code: type: string description: Error code. message: type: string description: Error message. field: type: string description: Field that caused the error. 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: {}