openapi: 3.0.1
info:
  title: Carriyo Orders API
  description: |-
    The Carriyo Orders API manages the customer order lifecycle from creation through fulfillment handoff. Create orders with line items and delivery details, split across multiple fulfillment locations, and cancel or update orders before they ship.
  contact:
    name: Carriyo Support
    url: https://help.carriyo.com
    email: support@carriyo.com
  version: '1.0'
servers:
  - url: https://api.carriyo.com
    description: Production Server
  - url: https://demo-api.carriyo.com
    description: Demo Server
security:
  - OAuth2-Production: []
    ApiKey: []
    TenantId: []
  - OAuth2-Demo: []
    ApiKey: []
    TenantId: []
tags:
  - name: Orders
    description: |-
      The order object represents a customer order containing one or more items to be fulfilled. Orders serve as the foundation for the fulfillment process in Carriyo.

      ## Key concepts

      ### Order structure

      Each order contains:
      - **Customer information**: shipping address, billing address, and customer details.
      - **Line items**: products ordered with quantities and prices.
      - **Fulfillment orders**: groups of line items assigned to specific locations for fulfillment.
      - **Payment information**: payment status and method details.

      ### Order status

      Orders progress through the following statuses:
      - **open**: order created, not yet allocated.
      - **partially_allocated**: some items allocated to fulfillment locations.
      - **allocated**: all items allocated to fulfillment locations.
      - **processing**: one or more fulfillment orders are being picked, packed, or shipped.
      - **fulfilled**: all items have been fulfilled.
      - **cancelled**: order has been cancelled.
      - **closed**: order is complete and closed.

      ### Reference keys

      Orders can be retrieved using:
      - **`order_id`**: Carriyo's unique identifier for the order.
      - **`partner_order_reference`**: your system's order reference (with `key=partner_order_reference`).

      This allows flexible integration with your existing order management systems.

      ### Fulfillment orders

      When an order is created, Carriyo automatically generates fulfillment orders based on:
      - Inventory availability across locations
      - Location-based allocation rules
      - Explicit fulfillment order specifications in the request

      Each fulfillment order represents items to be shipped from a single location.

      Lifecycle: orders move from `open` (created, awaiting allocation) to `partially_allocated` or `allocated` (fulfillment orders assigned to locations), then `processing` (items being picked, packed, or shipped), `fulfilled`, and `closed`. An order can be `cancelled` before its items are in transit.
  - name: Fulfillment Orders
    description: |-
      Fulfillment orders represent groups of line items from an order that are assigned to a specific location for fulfillment. They enable split-shipment workflows and multi-location fulfillment.

      ## Key concepts

      ### Fulfillment order lifecycle

      1. **Created**: when an order is created, fulfillment orders are generated automatically or based on your specifications.
      2. **Pending**: items are awaiting fulfillment at the assigned location.
      3. **Fulfilled**: items have been picked, packed, and are ready for shipping.
      4. **Shipped**: shipments have been created and items are in transit.
      5. **Completed**: all items have been delivered.

      ### Operations

      #### Fulfill
      Mark items as fulfilled and ready for shipping. This operation:
      - Updates line item statuses to fulfilled
      - Optionally creates a draft shipment automatically
      - Triggers inventory updates

      #### Unfulfill
      Reverse a fulfillment when items cannot be shipped. This allows:
      - Correcting fulfillment errors
      - Handling out-of-stock situations discovered after fulfillment
      - Reallocating items to different locations

      #### Split
      Divide a fulfillment order when items need to ship from different sources:
      - Create a new fulfillment order with selected line items
      - Assign to a different location if needed
      - Maintain order integrity across splits

      #### Merge
      Combine fulfillment orders when consolidation makes sense:
      - Reduce shipping costs by combining shipments
      - Improve customer experience with fewer deliveries
      - Optimize fulfillment operations

      #### Ship
      Create shipments for fulfilled items:
      - Specify carrier account and parcel details
      - Include delivery preferences
      - Generate shipping labels through the Carriyo Shipping API

      #### Cancel
      Cancel specific line items within a fulfillment order:
      - Provide cancellation reason
      - Automatically updates inventory
      - Triggers order status recalculation

      ### Location management

      Fulfillment orders are tied to locations. You can:
      - Update the assigned location before fulfillment
      - Move items between locations using split and merge operations
      - Track inventory across all fulfillment locations
  - name: Order Allocation Rules
    description: |-
      Order allocation rules determine how orders are routed to fulfillment locations based on order
      attributes and constraints.
    x-internal: true
paths:
  /orders:
    post:
      tags:
        - Orders
      summary: Create order
      operationId: create-order
      description: |-
        Creates a new order in Carriyo with the specified line items, customer details, and delivery method.

        ### 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. If inventory management is enabled, inventory is reserved for the allocated items
        4. Webhooks are triggered to notify your systems

        ### Delivery Method

        Each fulfillment order can have one of three delivery methods:
        - **`DELIVERY`**: standard delivery to the customer's address (`delivery_address` + `delivery_schedule`).
        - **`COLLECTION`**: customer collects from a pickup point (`customer_collection_address` + `customer_collection_schedule`).
        - **`DIGITAL`**: no physical delivery; fulfilled digitally.

        The top-level `delivery_method`, `delivery_type`, `delivery_address`, `delivery_schedule`, `customer_collection_address`, and `customer_collection_schedule` are **request-only** convenience fields. They are propagated to each auto-allocated fulfillment order and persisted there, but are **not stored on the `Order` itself**. To set them per fulfillment order, provide them inside each entry of the `fulfillment_orders` array.

        ### 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 (`id`, `sku`, `product_id`, `barcode`)
        - Quantity ordered
        - Pricing information (`unit_price`, `unit_cost`, taxes, duties, discount allocations)
        - Physical attributes (`weight`, `dimension`, `dangerous_goods`, `battery`)

        ### Response

        The API returns the complete order object including:
        - Generated `order_id` for future reference
        - Fulfillment orders with their allocations
        - Initial order status
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-order-request'
            examples:
              basic-order:
                summary: Pre-paid order with delivery option
                value:
                  merchant: acme-electronics
                  partner_order_reference: ORD-UK-2026-0001
                  delivery_option:
                    code: EXPRESS_DELIVERY
                  order_date: '2026-06-10T09:15:00.000Z'
                  sales_channel: web
                  payment:
                    currency: GBP
                    order_total: 763.74
                  customer:
                    contact_name: Oliver Bennett
                    contact_email: oliver.bennett@example.co.uk
                    contact_phone: '+44 7700 900123'
                  delivery_address:
                    contact_name: Oliver Bennett
                    contact_email: oliver.bennett@example.co.uk
                    contact_phone: '+44 7700 900123'
                    address1: 45 Gloucester Place
                    address2: Marylebone
                    city: London
                    country: GB
                    postcode: W1U 8HU
                  billing_address:
                    contact_name: Oliver Bennett
                    contact_email: oliver.bennett@example.co.uk
                    contact_phone: '+44 7700 900123'
                    address1: 45 Gloucester Place
                    address2: Marylebone
                    city: London
                    country: GB
                    postcode: W1U 8HU
                  line_items:
                    - product_id: PDT9FA016Y2ND9VJ6
                      sku: PDT9FA016Y2ND9VJ6
                      name: Action Camera
                      quantity: 1
                      unit_price: 309.29
                    - product_id: PDTYPM1M13G9COS3G
                      sku: PDTYPM1M13G9COS3G
                      name: Laptop 14-inch
                      quantity: 1
                      unit_price: 454.45
      responses:
        '201':
          description: Order created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order'
              examples:
                created-order:
                  summary: Order created in `open` status, awaiting allocation
                  value:
                    tenant: acme-electronics
                    order_id: O9F1A8B7C2D
                    merchant: acme-electronics
                    partner_order_reference: ORD-UK-2026-0001
                    delivery_option:
                      code: EXPRESS_DELIVERY
                    order_date: '2026-06-10T09:15:00.000Z'
                    sales_channel: web
                    status: open
                    payment:
                      currency: GBP
                      order_total: 763.74
                    customer:
                      contact_name: Oliver Bennett
                      contact_email: oliver.bennett@example.co.uk
                      contact_phone: '+44 7700 900123'
                    delivery_address:
                      contact_name: Oliver Bennett
                      contact_email: oliver.bennett@example.co.uk
                      contact_phone: '+44 7700 900123'
                      address1: 45 Gloucester Place
                      address2: Marylebone
                      city: London
                      country: GB
                      postcode: W1U 8HU
                    billing_address:
                      contact_name: Oliver Bennett
                      contact_email: oliver.bennett@example.co.uk
                      contact_phone: '+44 7700 900123'
                      address1: 45 Gloucester Place
                      address2: Marylebone
                      city: London
                      country: GB
                      postcode: W1U 8HU
                    line_items:
                      - product_id: PDT9FA016Y2ND9VJ6
                        sku: PDT9FA016Y2ND9VJ6
                        name: Action Camera
                        quantity: 1
                        unit_price: 309.29
                      - product_id: PDTYPM1M13G9COS3G
                        sku: PDTYPM1M13G9COS3G
                        name: Laptop 14-inch
                        quantity: 1
                        unit_price: 454.45
                    fulfillment_orders: []
                    creation_date: '2026-06-10T09:15:01.234Z'
                    update_date: '2026-06-10T09:15:01.234Z'
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
  /orders/{reference}:
    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: 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: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
    patch:
      tags:
        - Orders
      summary: Update order
      operationId: update-order
      description: |-
        Apply partial updates to an order's details, line items, and fulfillment orders.

        ### Important warning

        Used incorrectly, this endpoint can destroy data. The `fulfillment_orders` field is a **full replacement**: any fulfillment order not included in the request is **permanently removed**.

        ### Update behaviour

        #### 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`
        - `delivery_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. Include every line item you want to keep.

        #### Fulfillment orders (full replacement with preservation rules)
        If `fulfillment_orders` is provided:
        - **Any FO not included is removed.** Always include every FO you want to keep.
        - FOs are matched by `fulfillment_order_id` or `partner_fulfillment_order_reference`.
        - An FO without a matching ID is created with a new `fulfillment_order_id`.

        ### Fulfillment order line items: critical rules

        When updating FO line items:

        #### What to include
        Only pass line items with **pending statuses**:
        - `open`: items not yet allocated.
        - `allocated`: items allocated but not fulfilled.

        #### What is preserved automatically
        Line items with terminal statuses are preserved without you re-sending them:
        - `fulfilled`: items that have been fulfilled.
        - `cancelled`: items that have been cancelled.
        - `closed`: items that are closed.

        Don't include fulfilled, cancelled, or closed line items in your request; they're preserved automatically and including them may cause unexpected behaviour.

        ### 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: the FO has 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 include only one FO in the request, every other FO is deleted.
        2. **Including fulfilled or cancelled items.** They're preserved automatically; re-sending them may cause unexpected behaviour.
        3. **Not matching FO identifiers.** Use `fulfillment_order_id` or `partner_fulfillment_order_reference` to match existing FOs.
        4. **Treating line items as a partial update.** The `line_items` array replaces all pending items, so include every pending item you want to keep.

        ### Order status restrictions

        An order can be updated in any status except `cancelled`. That covers `open`, `partially_allocated`, `allocated`, `processing`, `fulfilled`, and `closed`.

        ### Inventory impact

        If inventory management is enabled, updating FOs automatically:
        - Reserves inventory for new FO allocations.
        - Releases inventory for removed FO allocations.
        - Adjusts inventory for quantity changes.
      parameters:
        - 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'
            examples:
              update-phone:
                summary: Update the customer contact phone number
                value:
                  customer:
                    contact_name: Oliver Bennett
                    contact_email: oliver.bennett@example.co.uk
                    contact_phone: '+44 7700 900999'
      responses:
        '200':
          description: Order updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order'
              examples:
                updated-order:
                  summary: Order returned with updated customer phone
                  value:
                    tenant: acme-electronics
                    order_id: O9F1A8B7C2D
                    merchant: acme-electronics
                    partner_order_reference: ORD-UK-2026-0001
                    status: open
                    payment:
                      currency: GBP
                      order_total: 763.74
                    customer:
                      contact_name: Oliver Bennett
                      contact_email: oliver.bennett@example.co.uk
                      contact_phone: '+44 7700 900999'
                    delivery_address:
                      contact_name: Oliver Bennett
                      contact_email: oliver.bennett@example.co.uk
                      contact_phone: '+44 7700 900123'
                      address1: 45 Gloucester Place
                      address2: Marylebone
                      city: London
                      country: GB
                      postcode: W1U 8HU
                    line_items:
                      - product_id: PDT9FA016Y2ND9VJ6
                        sku: PDT9FA016Y2ND9VJ6
                        name: Action Camera
                        quantity: 1
                        unit_price: 309.29
                      - product_id: PDTYPM1M13G9COS3G
                        sku: PDTYPM1M13G9COS3G
                        name: Laptop 14-inch
                        quantity: 1
                        unit_price: 454.45
                    fulfillment_orders: []
                    creation_date: '2026-06-10T09:15:01.234Z'
                    update_date: '2026-06-10T10:02:30.000Z'
        '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: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
  /orders/{reference}/cancel:
    post:
      tags:
        - Orders
      summary: Cancel order
      operationId: cancel-order
      description: |-
        Cancels an order and all its associated fulfillment orders.

        ### Status requirements

        An order can be cancelled only while it is still in an allocation phase:
        - ✅ `open`: created but not yet allocated.
        - ✅ `partially_allocated`: some items allocated to fulfillment locations.
        - ✅ `allocated`: all items allocated to fulfillment locations.

        Once fulfillment is under way or finished, cancellation is no longer allowed:
        - ❌ `processing`: one or more fulfillment orders are being picked, packed, or shipped.
        - ❌ `fulfilled`: all items have been fulfilled.
        - ❌ `closed`: order is complete and closed.
        - ❌ `cancelled`: order is already cancelled.

        ### Cancellation effects

        When an order is successfully cancelled:
        - Every line item's quantity is set to 0 and its removed quantity is recorded.
        - Every fulfillment order line item is marked `cancelled`.
        - Reserved inventory is released back to stock.
        - The order status is updated to `cancelled`.
        - Webhooks fire to notify your systems.

        ### Cancellation reason

        Provide a `cancellation_reason`, one of:
        - `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`: a payment problem occurred.
        - `OTHER`: any other reason.
      parameters:
        - 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'
            examples:
              cancel-by-customer:
                summary: Cancel an order at the customer's request
                value:
                  cancellation_reason: CUSTOMER_CANCELLATION
      responses:
        '200':
          description: Order cancelled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order'
              examples:
                cancelled-order:
                  summary: Order returned in `cancelled` status
                  value:
                    tenant: acme-electronics
                    order_id: O9F1A8B7C2D
                    merchant: acme-electronics
                    partner_order_reference: ORD-UK-2026-0001
                    status: cancelled
                    cancellation_reason: CUSTOMER_CANCELLATION
                    payment:
                      currency: GBP
                      order_total: 763.74
                    customer:
                      contact_name: Oliver Bennett
                      contact_email: oliver.bennett@example.co.uk
                      contact_phone: '+44 7700 900123'
                    line_items:
                      - product_id: PDT9FA016Y2ND9VJ6
                        sku: PDT9FA016Y2ND9VJ6
                        name: Action Camera
                        quantity: 1
                        unit_price: 309.29
                      - product_id: PDTYPM1M13G9COS3G
                        sku: PDTYPM1M13G9COS3G
                        name: Laptop 14-inch
                        quantity: 1
                        unit_price: 454.45
                    fulfillment_orders: []
                    creation_date: '2026-06-10T09:15:01.234Z'
                    update_date: '2026-06-10T11:05:00.000Z'
        '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: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
  /orders/{reference}/redact:
    post:
      tags:
        - Orders
      summary: Redact order
      operationId: redact-order
      description: |-
        Anonymises the personal data on an order and propagates the redaction to dropoff fields
        on every linked shipment. This action is irreversible.

        **See also:** Data Redaction, the full feature page covering
        order and shipment redaction scope, downstream sync, and GDPR compliance guidance.
      parameters:
        - 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 redacted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order'
              examples:
                redacted-order:
                  summary: Order returned with anonymised customer fields
                  value:
                    tenant: acme-electronics
                    order_id: O9F1A8B7C2D
                    merchant: acme-electronics
                    partner_order_reference: ORD-UK-2026-0001
                    status: fulfilled
                    redacted: true
                    customer:
                      contact_name: '[REDACTED]'
                      contact_email: '[REDACTED]'
                      contact_phone: '[REDACTED]'
                    delivery_address:
                      contact_name: '[REDACTED]'
                      contact_email: '[REDACTED]'
                      contact_phone: '[REDACTED]'
                      address1: '[REDACTED]'
                      city: London
                      country: GB
                      postcode: '[REDACTED]'
                    creation_date: '2026-06-10T09:15:01.234Z'
                    update_date: '2026-06-30T00:00:00.000Z'
        '400':
          description: Order cannot be redacted.
          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: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
  /orders/bulk/import:
    post:
      tags:
        - Orders
      summary: Bulk import orders
      operationId: bulk-import-orders
      description: |-
        Create multiple orders in a single request for batch processing.

        ### Processing

        Each order in the batch is processed independently:
        - Valid orders are created.
        - Invalid orders return error details.
        - Processing continues even if some orders fail.

        ### Limits

        - **Up to 20 orders per request by default** (configurable per tenant). Chunk larger imports client-side.
        - Each order follows the same validation as single order creation.

        ### Duplicates

        Bulk import is create-only; it does not upsert. A row whose `partner_order_reference` already exists in Carriyo, or that appears more than once within the batch, is rejected rather than updated. The successful rows in the same batch are unaffected.

        ### Response

        Returns one entry per input row, in the same order as the request. Each entry carries:

        - `result`: `SUCCESS` when the order was created; otherwise an error code such as `DUPLICATE` or `VALIDATION_ERROR`.
        - `reason`: human-readable detail when `result` is not `SUCCESS`.
        - The full order object when `result` is `SUCCESS`.

        Treat `DUPLICATE` as a no-op (the order is already in Carriyo) rather than a retryable failure.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bulk-order-import-request'
            examples:
              two-orders:
                summary: Two orders, one succeeds and one fails as a duplicate
                value:
                  order_requests:
                    - merchant: acme-electronics
                      partner_order_reference: ORD-UK-2026-0010
                      order_date: '2026-06-10T08:00:00.000Z'
                      sales_channel: web
                      payment:
                        currency: GBP
                        order_total: 309.29
                      customer:
                        contact_name: Oliver Bennett
                        contact_email: oliver.bennett@example.co.uk
                        contact_phone: '+44 7700 900123'
                      delivery_address:
                        contact_name: Oliver Bennett
                        contact_email: oliver.bennett@example.co.uk
                        contact_phone: '+44 7700 900123'
                        address1: 45 Gloucester Place
                        address2: Marylebone
                        city: London
                        country: GB
                        postcode: W1U 8HU
                      line_items:
                        - product_id: PDT9FA016Y2ND9VJ6
                          sku: PDT9FA016Y2ND9VJ6
                          name: Action Camera
                          quantity: 1
                          unit_price: 309.29
                    - merchant: acme-electronics
                      partner_order_reference: ORD-UK-2026-0001
                      order_date: '2026-06-10T08:05:00.000Z'
                      sales_channel: web
                      payment:
                        currency: GBP
                        order_total: 49.99
                      customer:
                        contact_name: Sophie Carter
                        contact_email: sophie.carter@example.co.uk
                        contact_phone: '+44 7700 900456'
                      delivery_address:
                        contact_name: Sophie Carter
                        contact_email: sophie.carter@example.co.uk
                        contact_phone: '+44 7700 900456'
                        address1: 12 Lavender Gardens
                        address2: Battersea
                        city: London
                        country: GB
                        postcode: SW11 1DJ
                      line_items:
                        - product_id: WIRELESS-EARBUDS
                          sku: WIRELESS-EARBUDS
                          name: Wireless Earbuds
                          quantity: 1
                          unit_price: 49.99
      responses:
        '200':
          description: Bulk import processed.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/bulk-order-import-response'
              examples:
                bulk-result:
                  summary: First row succeeded; second row rejected as duplicate
                  value:
                    - partner_order_reference: ORD-UK-2026-0010
                      result: SUCCESS
                      order:
                        tenant: acme-electronics
                        order_id: OA1B2C3D4E5
                        merchant: acme-electronics
                        partner_order_reference: ORD-UK-2026-0010
                        status: open
                        payment:
                          currency: GBP
                          order_total: 309.29
                        customer:
                          contact_name: Oliver Bennett
                          contact_email: oliver.bennett@example.co.uk
                          contact_phone: '+44 7700 900123'
                        line_items:
                          - product_id: PDT9FA016Y2ND9VJ6
                            sku: PDT9FA016Y2ND9VJ6
                            name: Action Camera
                            quantity: 1
                            unit_price: 309.29
                        fulfillment_orders: []
                        creation_date: '2026-06-10T08:00:05.000Z'
                        update_date: '2026-06-10T08:00:05.000Z'
                    - partner_order_reference: ORD-UK-2026-0001
                      result: DUPLICATE
                      reason: Order with partner_order_reference ORD-UK-2026-0001 already exists
        '400':
          description: Invalid request payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error-response'
      security:
        - OAuth2-Production: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      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, Carriyo:
        1. Validates that the requested line items exist and are in a pending status.
        2. Validates that the 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 the order status based on overall fulfillment progress.
        6. Fires webhooks.

        ### Line items (required)

        Provide a `line_items` array specifying which items to fulfill. Each entry needs:
        - `id`: matching an order line item.
        - `quantity`: the quantity to fulfill, which must be ≤ the 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`, both `on_hand` and `reserved` are reduced by the fulfilled quantity.

        If shipping is not required (or `skip_shipping=true`), items are automatically set to `closed`.
      parameters:
        - 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'
            examples:
              fulfill-all-draft:
                summary: Fulfill all line items in the FO with a draft shipment
                value:
                  line_items:
                    - line_item_id: LI-001
                      quantity: 1
                    - line_item_id: LI-002
                      quantity: 1
      responses:
        '200':
          description: Fulfillment order fulfilled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order'
              examples:
                fulfilled-order:
                  summary: FO transitioned to `fulfilled` with fulfillment_ids assigned
                  value:
                    tenant: acme-electronics
                    order_id: O9F1A8B7C2D
                    merchant: acme-electronics
                    partner_order_reference: ORD-UK-2026-0001
                    status: fulfilled
                    fulfillment_orders:
                      - fulfillment_order_id: FO9F1A8B7C2D-1
                        location_id: LOC-LDN-WAREHOUSE-01
                        line_items:
                          - line_item_id: LI-001
                            quantity: 1
                            status: fulfilled
                            fulfillment_id: FUL-A1B2C3D4
                          - line_item_id: LI-002
                            quantity: 1
                            status: fulfilled
                            fulfillment_id: FUL-A1B2C3D4
                    creation_date: '2026-06-10T09:15:01.234Z'
                    update_date: '2026-06-11T08:30:00.000Z'
        '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: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
  /orders/{orderReference}/fulfillment-orders/{fulfillmentOrderId}/unfulfill:
    post:
      tags:
        - Fulfillment Orders
      summary: Unfulfill order
      operationId: unfulfill-order
      description: |-
        Reverse a previous fulfillment, returning items to `allocated` status.

        ### When to unfulfill

        Use this endpoint when items were fulfilled in error, stock turns out to be unavailable after fulfillment, the fulfillment needs to move to another location, or a shipment was cancelled before pickup.

        ### Request requirements

        Provide `fulfillment_ids`, an array of the fulfillment IDs to reverse. Each must exist among the fulfillment order's fulfilled line items.

        ### Effects

        When you unfulfill, Carriyo:
        1. Cancels associated shipments, if not already cancelled.
        2. Returns line items to `allocated` status.
        3. Clears the fulfillment ID, shipment IDs, and partner reference from the items.
        4. Merges items that share the same ID and status.
        5. Recalculates the order status.
        6. Fires webhooks.

        ### Inventory impact

        If inventory management is enabled, `on_hand` is increased by the unfulfilled quantity, restoring stock.
      parameters:
        - 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'
            examples:
              reverse-one-fulfillment:
                summary: Reverse a single fulfillment by its fulfillment_id
                value:
                  fulfillment_ids:
                    - FUL-A1B2C3D4
      responses:
        '200':
          description: Fulfillment reversed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order'
              examples:
                unfulfilled-order:
                  summary: Lines back to `allocated`, fulfillment_id cleared
                  value:
                    tenant: acme-electronics
                    order_id: O9F1A8B7C2D
                    merchant: acme-electronics
                    partner_order_reference: ORD-UK-2026-0001
                    status: allocated
                    fulfillment_orders:
                      - fulfillment_order_id: FO9F1A8B7C2D-1
                        location_id: LOC-LDN-WAREHOUSE-01
                        line_items:
                          - line_item_id: LI-001
                            quantity: 1
                            status: allocated
                          - line_item_id: LI-002
                            quantity: 1
                            status: allocated
                    creation_date: '2026-06-10T09:15:01.234Z'
                    update_date: '2026-06-11T09:00:00.000Z'
        '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: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
  /orders/{orderReference}/fulfillment-orders/merge:
    post:
      tags:
        - Fulfillment Orders
      summary: Merge fulfillment orders
      operationId: merge-fulfillment-orders
      description: |-
        Combine line items from one fulfillment order into another.

        ### 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 move to the destination fulfillment order. If all items are moved, the source fulfillment order is removed. The order status is recalculated and webhooks fire.

        ### Restrictions

        The source and destination fulfillment orders:
        - ❌ Cannot contain any fulfilled line items; only pending items can be merged.
        - ✅ Must share the same `location_id`.
        - ✅ Must share the same `delivery_type` (when specified).
        - ✅ Must share the same delivery method.
        - ❌ Cannot mix items where some require shipping and some don't.

        ### Inventory impact

        No inventory changes occur during a merge; items are only reorganised between fulfillment orders.
      parameters:
        - 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'
            examples:
              merge-two-fos:
                summary: Merge all items from source FO into destination FO
                value:
                  source:
                    fulfillment_order_id: FO9F1A8B7C2D-2
                  destination:
                    fulfillment_order_id: FO9F1A8B7C2D-1
      responses:
        '200':
          description: Fulfillment orders merged successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order'
              examples:
                merged-order:
                  summary: Order returned with source FO removed and its line items in destination FO
                  value:
                    tenant: acme-electronics
                    order_id: O9F1A8B7C2D
                    merchant: acme-electronics
                    partner_order_reference: ORD-UK-2026-0001
                    status: allocated
                    payment:
                      currency: GBP
                      order_total: 763.74
                    customer:
                      contact_name: Oliver Bennett
                      contact_email: oliver.bennett@example.co.uk
                      contact_phone: '+44 7700 900123'
                    line_items:
                      - product_id: PDT9FA016Y2ND9VJ6
                        sku: PDT9FA016Y2ND9VJ6
                        name: Action Camera
                        quantity: 1
                        unit_price: 309.29
                      - product_id: PDTYPM1M13G9COS3G
                        sku: PDTYPM1M13G9COS3G
                        name: Laptop 14-inch
                        quantity: 1
                        unit_price: 454.45
                    fulfillment_orders:
                      - fulfillment_order_id: FO9F1A8B7C2D-1
                        location_id: LOC-LDN-WAREHOUSE-01
                        line_items:
                          - line_item_id: LI-001
                            quantity: 1
                            status: allocated
                          - line_item_id: LI-002
                            quantity: 1
                            status: allocated
                    creation_date: '2026-06-10T09:15:01.234Z'
                    update_date: '2026-06-10T12:00:00.000Z'
        '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: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      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: |-
        Split selected line items from a fulfillment order into a new fulfillment order. Use it to ship available items immediately while backordered items wait, to fulfill from multiple locations when only partial inventory exists, or to separate items with different shipping requirements.

        ### Line item status requirements

        Only items in a pending status can be split:
        - ✅ `open`: can be split.
        - ✅ `allocated`: can be split.
        - ❌ `fulfilled`, `cancelled`, `closed`: cannot be split.

        ### Split process

        Specify:
        - `line_items` (required): the items and quantities to move to the new FO.
        - `location_id` (optional): a location for the split items. Defaults to the 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`, inheriting `delivery` from the original. Split line items get status `allocated` when a location is set, otherwise `open`. The original FO's quantities are reduced (items are removed if their quantity reaches 0). The order status is recalculated and webhooks fire.

        ### Inventory impact

        No inventory changes occur during a split; items are only reorganised.
      parameters:
        - 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'
            examples:
              split-one-item:
                summary: Move one line item to a new FO at a different location
                value:
                  line_items:
                    - line_item_id: LI-002
                      quantity: 1
                  location_id: LOC-LDN-STORE-MARYLEBONE
      responses:
        '200':
          description: Fulfillment order split successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order'
              examples:
                split-order:
                  summary: Two FOs, original with one item and new FO with the split item
                  value:
                    tenant: acme-electronics
                    order_id: O9F1A8B7C2D
                    merchant: acme-electronics
                    partner_order_reference: ORD-UK-2026-0001
                    status: allocated
                    fulfillment_orders:
                      - fulfillment_order_id: FO9F1A8B7C2D-1
                        location_id: LOC-LDN-WAREHOUSE-01
                        line_items:
                          - line_item_id: LI-001
                            quantity: 1
                            status: allocated
                      - fulfillment_order_id: FO9F1A8B7C2D-2
                        location_id: LOC-LDN-STORE-MARYLEBONE
                        line_items:
                          - line_item_id: LI-002
                            quantity: 1
                            status: allocated
                    creation_date: '2026-06-10T09:15:01.234Z'
                    update_date: '2026-06-11T10:00:00.000Z'
        '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: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      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: |-
        Create 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 (as an additional shipment).
        - ❌ `open`: must be allocated first.
        - ❌ `cancelled`, `closed`: cannot be shipped.

        ### Request requirements

        Provide `line_items`, the items to ship with their quantities.

        ### Shipping process

        When you ship, Carriyo:
        1. Validates that the requested items are in `allocated` or `fulfilled` status.
        2. Validates that the 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. Fires webhooks.

        ### Shipment configuration

        The request mirrors the Shipping API's create-shipment body. You can set the carrier account (or let automation rules decide), parcels, delivery instructions and scheduling, payment details including cash on delivery, and pre-booking information 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 inventory changes occur here; inventory is managed during the fulfill and cancel operations.
      parameters:
        - 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'
            examples:
              ship-all-items:
                summary: Ship all fulfilled items in the FO, no draft
                value:
                  line_items:
                    - line_item_id: LI-001
                      quantity: 1
                    - line_item_id: LI-002
                      quantity: 1
                  carrier_account:
                    carrier: EVRI
                  parcels:
                    - weight: 2.5
                      weight_unit: kg
                      length: 35
                      width: 25
                      height: 15
                      dimension_unit: cm
      responses:
        '200':
          description: Shipment created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order'
              examples:
                shipped-order:
                  summary: FO returned with shipment_id populated on line items
                  value:
                    tenant: acme-electronics
                    order_id: O9F1A8B7C2D
                    merchant: acme-electronics
                    partner_order_reference: ORD-UK-2026-0001
                    status: fulfilled
                    fulfillment_orders:
                      - fulfillment_order_id: FO9F1A8B7C2D-1
                        location_id: LOC-LDN-WAREHOUSE-01
                        line_items:
                          - line_item_id: LI-001
                            quantity: 1
                            status: fulfilled
                            fulfillment_id: FUL-A1B2C3D4
                            shipment_ids:
                              - SHP-X9Y8Z7W6
                          - line_item_id: LI-002
                            quantity: 1
                            status: fulfilled
                            fulfillment_id: FUL-A1B2C3D4
                            shipment_ids:
                              - SHP-X9Y8Z7W6
                    creation_date: '2026-06-10T09:15:01.234Z'
                    update_date: '2026-06-11T13:00:00.000Z'
        '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: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      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: |-
        Reassign a fulfillment order to a different location, for example to a location with available inventory or one closer to the customer.

        ### Request requirements

        Provide `location_id`, the new location's ID or code.

        ### Location resolution

        The value is resolved first by `partner_location_id`, then, if not found, by `location_code` for the merchant.

        ### Effects

        The fulfillment order's `location_id` is updated, the order status is recalculated, and webhooks fire.

        ### Inventory impact

        No inventory changes occur during a location update. Manage inventory reservations across the location change separately through the Inventory API if you need to.
      parameters:
        - 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'
            examples:
              change-location:
                summary: Reassign FO from warehouse to marylebone store
                value:
                  location_id: LOC-LDN-STORE-MARYLEBONE
      responses:
        '200':
          description: Location updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order'
              examples:
                location-updated:
                  summary: FO returned with new location and allocation history entry
                  value:
                    tenant: acme-electronics
                    order_id: O9F1A8B7C2D
                    merchant: acme-electronics
                    partner_order_reference: ORD-UK-2026-0001
                    status: allocated
                    fulfillment_orders:
                      - fulfillment_order_id: FO9F1A8B7C2D-1
                        location_id: LOC-LDN-STORE-MARYLEBONE
                        allocation_history:
                          - date: '2026-06-10T09:15:01.234Z'
                            location_id: LOC-LDN-WAREHOUSE-01
                            reason: initial allocation
                          - date: '2026-06-11T14:00:00.000Z'
                            location_id: LOC-LDN-STORE-MARYLEBONE
                            reason: location updated via API
                        line_items:
                          - line_item_id: LI-001
                            quantity: 1
                            status: allocated
                          - line_item_id: LI-002
                            quantity: 1
                            status: allocated
                    creation_date: '2026-06-10T09:15:01.234Z'
                    update_date: '2026-06-11T14:00:00.000Z'
        '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: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
  /orders/{orderReference}/fulfillment-orders/{fulfillmentOrderId}/update-delivery-method:
    patch:
      tags:
        - Fulfillment Orders
      summary: Update fulfillment order delivery method
      operationId: update-fulfillment-order-delivery-method
      description: |-
        Switches the delivery method of a fulfillment order between `DELIVERY`, `COLLECTION`, and `DIGITAL`, and updates the corresponding address and schedule in a single call.

        ### Behaviour

        Depending on the new `delivery_method`, the request body fields are interpreted as follows:

        | New `delivery_method` | `address` is set as | `scheduled_from`/`scheduled_to` are set as |
        |---|---|---|
        | `DELIVERY` | `delivery_address` | `delivery_schedule` |
        | `COLLECTION` | `customer_collection_address` | `customer_collection_schedule` |
        | `DIGITAL` | not used | not used |

        Switching to a new delivery method clears the address and schedule fields associated with the previous method.

        ### Use cases

        - Convert an online order from home delivery to a click-and-collect pickup at a store.
        - Switch a fulfillment order from `COLLECTION` back to `DELIVERY` if the customer changes their mind.
        - Mark a fulfillment order as `DIGITAL` when no physical delivery is required.

        ### Constraints

        This endpoint cannot be called on fulfillment orders that have already started processing (e.g., shipments created, items fulfilled). Use unfulfill or cancel flows first if you need to change the method on an in-progress FO.
      parameters:
        - 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-fulfillment-order-delivery-method-request'
            examples:
              change-to-collection:
                summary: Switch delivery method to in-store collection with a schedule
                value:
                  delivery_method: COLLECTION
                  address:
                    contact_name: Oliver Bennett
                    contact_email: oliver.bennett@example.co.uk
                    contact_phone: '+44 7700 900123'
                    address1: 45 Gloucester Place
                    address2: Marylebone
                    city: London
                    country: GB
                    postcode: W1U 8HU
                  scheduled_from: '2026-06-12T10:00:00.000Z'
                  scheduled_to: '2026-06-12T18:00:00.000Z'
      responses:
        '200':
          description: Delivery method updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order'
              examples:
                delivery-method-updated:
                  summary: FO returned with updated delivery method
                  value:
                    tenant: acme-electronics
                    order_id: O9F1A8B7C2D
                    merchant: acme-electronics
                    partner_order_reference: ORD-UK-2026-0001
                    status: allocated
                    fulfillment_orders:
                      - fulfillment_order_id: FO9F1A8B7C2D-1
                        location_id: LOC-LDN-STORE-MARYLEBONE
                        delivery_method: COLLECTION
                        delivery_address:
                          contact_name: Oliver Bennett
                          contact_email: oliver.bennett@example.co.uk
                          contact_phone: '+44 7700 900123'
                          address1: 45 Gloucester Place
                          address2: Marylebone
                          city: London
                          country: GB
                          postcode: W1U 8HU
                        delivery_schedule:
                          scheduled_from: '2026-06-12T10:00:00.000Z'
                          scheduled_to: '2026-06-12T18:00:00.000Z'
                        line_items:
                          - line_item_id: LI-001
                            quantity: 1
                            status: allocated
                          - line_item_id: LI-002
                            quantity: 1
                            status: allocated
                    creation_date: '2026-06-10T09:15:01.234Z'
                    update_date: '2026-06-11T15:00:00.000Z'
        '400':
          description: Invalid request.
          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: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
  /orders/{orderReference}/fulfillment-orders/{fulfillmentOrderId}/update-address:
    patch:
      tags:
        - Fulfillment Orders
      summary: Update fulfillment order address
      operationId: update-fulfillment-order-address
      description: |-
        Updates the address on the fulfillment order according to its current `delivery_method`:

        | `delivery_method` | `address` updates |
        |---|---|
        | `DELIVERY` | `delivery_address` |
        | `COLLECTION` | `customer_collection_address` |

        Use Update Delivery Method first if you need to switch between delivery and collection before setting the correct address type.

        Not applicable when `delivery_method` is `DIGITAL`.
      parameters:
        - 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-fulfillment-order-address-request'
            examples:
              update-address:
                summary: Update delivery address to a new UK address
                value:
                  address:
                    contact_name: Oliver Bennett
                    contact_email: oliver.bennett@example.co.uk
                    contact_phone: '+44 7700 900123'
                    address1: 45 Gloucester Place
                    address2: Marylebone
                    city: London
                    country: GB
                    postcode: W1U 8HU
      responses:
        '200':
          description: Address updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order'
              examples:
                address-updated:
                  summary: Order returned with updated FO delivery address
                  value:
                    tenant: acme-electronics
                    order_id: O9F1A8B7C2D
                    merchant: acme-electronics
                    partner_order_reference: ORD-UK-2026-0001
                    status: allocated
                    fulfillment_orders:
                      - fulfillment_order_id: FO9F1A8B7C2D-1
                        location_id: LOC-LDN-WAREHOUSE-01
                        delivery_address:
                          contact_name: Oliver Bennett
                          contact_email: oliver.bennett@example.co.uk
                          contact_phone: '+44 7700 900123'
                          address1: 45 Gloucester Place
                          address2: Marylebone
                          city: London
                          country: GB
                          postcode: W1U 8HU
                        line_items:
                          - line_item_id: LI-001
                            quantity: 1
                            status: allocated
                    creation_date: '2026-06-10T09:15:01.234Z'
                    update_date: '2026-06-11T16:00:00.000Z'
        '400':
          description: Invalid request.
          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: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
  /orders/{orderReference}/fulfillment-orders/{fulfillmentOrderId}/update-schedule:
    patch:
      tags:
        - Fulfillment Orders
      summary: Update fulfillment order schedule
      operationId: update-fulfillment-order-schedule
      description: |-
        Update the delivery schedule window for a fulfillment order, for example when the customer changes their preferred window or a missed delivery needs rescheduling.

        Replaces the FO's `scheduled_from` and `scheduled_to`, then fires webhooks.
      parameters:
        - 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-fulfillment-order-schedule-request'
            examples:
              reschedule:
                summary: Reschedule delivery to a morning window
                value:
                  scheduled_from: '2026-06-13T08:00:00.000Z'
                  scheduled_to: '2026-06-13T12:00:00.000Z'
      responses:
        '200':
          description: Schedule updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order'
              examples:
                schedule-updated:
                  summary: Order returned with updated delivery schedule
                  value:
                    tenant: acme-electronics
                    order_id: O9F1A8B7C2D
                    merchant: acme-electronics
                    partner_order_reference: ORD-UK-2026-0001
                    status: allocated
                    fulfillment_orders:
                      - fulfillment_order_id: FO9F1A8B7C2D-1
                        location_id: LOC-LDN-WAREHOUSE-01
                        delivery_schedule:
                          scheduled_from: '2026-06-13T08:00:00.000Z'
                          scheduled_to: '2026-06-13T12:00:00.000Z'
                        line_items:
                          - line_item_id: LI-001
                            quantity: 1
                            status: allocated
                    creation_date: '2026-06-10T09:15:01.234Z'
                    update_date: '2026-06-11T17:00:00.000Z'
        '400':
          description: Invalid request.
          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: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
  /orders/{orderReference}/fulfillment-orders/{fulfillmentOrderId}/update-partner-references:
    patch:
      tags:
        - Fulfillment Orders
      summary: Update fulfillment order partner references
      operationId: update-fulfillment-order-partner-references
      description: |-
        Update partner references on a fulfillment order or its individual fulfillments.

        ### Updatable fields

        Provide one of the following per request:
        - `partner_fulfillment_order_reference`: your external reference for the FO.
        - `fulfillments`: an array of `{ fulfillment_id, partner_fulfillment_reference }` pairs that set references on already-fulfilled line items.

        If both are present, only `partner_fulfillment_order_reference` is applied.

        ### Constraints

        The fulfillment order must not have active picks. This endpoint only updates reference fields and makes no inventory changes.
      parameters:
        - 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-fulfillment-order-partner-references-request'
            examples:
              set-fo-and-fulfillment-refs:
                summary: Set FO partner reference and update a fulfillment reference
                value:
                  partner_fulfillment_order_reference: EXT-FO-88001
                  fulfillments:
                    - fulfillment_id: FUL-A1B2C3D4
                      partner_fulfillment_reference: EXT-FULFIL-99001
      responses:
        '200':
          description: Partner references updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order'
              examples:
                refs-updated:
                  summary: Order returned with partner references set on the FO
                  value:
                    tenant: acme-electronics
                    order_id: O9F1A8B7C2D
                    merchant: acme-electronics
                    partner_order_reference: ORD-UK-2026-0001
                    status: fulfilled
                    fulfillment_orders:
                      - fulfillment_order_id: FO9F1A8B7C2D-1
                        partner_fulfillment_order_reference: EXT-FO-88001
                        location_id: LOC-LDN-WAREHOUSE-01
                        line_items:
                          - line_item_id: LI-001
                            quantity: 1
                            status: fulfilled
                            fulfillment_id: FUL-A1B2C3D4
                    creation_date: '2026-06-10T09:15:01.234Z'
                    update_date: '2026-06-11T18:00:00.000Z'
        '400':
          description: Invalid request.
          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: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      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: |-
        Cancel specific line items within a fulfillment order.

        ### Line item status requirements

        Only items in a pending status can be cancelled:
        - ✅ `open`: can be cancelled.
        - ✅ `allocated`: can be cancelled.
        - ❌ `fulfilled`: cannot be cancelled directly; unfulfill it first.
        - ❌ `cancelled`: already cancelled.
        - ❌ `closed`: cannot be cancelled.

        ### Request requirements

        Both fields are required:
        - `cancellation_reason`: one of the values below.
        - `line_items`: the 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`: a payment problem occurred.
        - `OTHER`: any other reason.

        ### Cancellation effects

        When items are cancelled, Carriyo updates each item's status to `cancelled` with the reason, updates the order line item's `removed_quantities`, recalculates the order status, and fires webhooks.

        ### Inventory impact

        If inventory management is enabled and the FO has a `location_id`, `reserved` is decreased by the cancelled quantity, releasing the reserved stock.
      parameters:
        - 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'
            examples:
              cancel-one-item:
                summary: Cancel a single line item due to out of stock
                value:
                  cancellation_reason: INVENTORY_OUT_OF_STOCK
                  line_items:
                    - line_item_id: LI-002
                      quantity: 1
      responses:
        '200':
          description: Line items cancelled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order'
              examples:
                item-cancelled:
                  summary: FO returned with the cancelled line item in `cancelled` status
                  value:
                    tenant: acme-electronics
                    order_id: O9F1A8B7C2D
                    merchant: acme-electronics
                    partner_order_reference: ORD-UK-2026-0001
                    status: partially_fulfilled
                    fulfillment_orders:
                      - fulfillment_order_id: FO9F1A8B7C2D-1
                        location_id: LOC-LDN-WAREHOUSE-01
                        line_items:
                          - line_item_id: LI-001
                            quantity: 1
                            status: allocated
                          - line_item_id: LI-002
                            quantity: 1
                            status: cancelled
                    creation_date: '2026-06-10T09:15:01.234Z'
                    update_date: '2026-06-11T11:00:00.000Z'
        '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: []
          ApiKey: []
          TenantId: []
        - OAuth2-Demo: []
          ApiKey: []
          TenantId: []
      x-codegen-request-body-name: body
  /order-allocation-rules:
    post:
      tags:
        - Order Allocation Rules
      x-internal: true
      summary: Create order allocation rule
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Create an order allocation rule. Allocation rules determine how an order is split into
        one or more fulfillment orders across your fulfillment locations. New rules are
        ordered by sequence; use **Update rule sequence** to set their evaluation priority.
      operationId: create-order-allocation-rule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: |-
                OrderAllocationRuleDto. See the schema below or download the spec for the full
                shape.
              additionalProperties: true
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                type: object
                description: |-
                  OrderAllocationRuleDto. See the schema below or download the spec for the full
                  shape.
                additionalProperties: true
    get:
      tags:
        - Order Allocation Rules
      x-internal: true
      summary: List order allocation rules
      operationId: list-order-allocation-rules
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: |-
                    OrderAllocationRuleDto. See the schema below or download the spec for the full
                    shape.
                  additionalProperties: true
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        List the order allocation rules configured for the merchant, ordered by evaluation priority (sequence).
  /order-allocation-rules/{rule_id}:
    get:
      tags:
        - Order Allocation Rules
      x-internal: true
      summary: Get order allocation rule
      operationId: get-order-allocation-rule
      parameters:
        - name: rule_id
          in: path
          required: true
          schema:
            type: string
          description: Allocation rule ID.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                description: |-
                  OrderAllocationRuleDto. See the schema below or download the spec for the full
                  shape.
                additionalProperties: true
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Return a single order allocation rule by its `rule_id`.
    put:
      tags:
        - Order Allocation Rules
      x-internal: true
      summary: Update order allocation rule
      operationId: update-order-allocation-rule
      parameters:
        - name: rule_id
          in: path
          required: true
          schema:
            type: string
          description: Allocation rule ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: |-
                OrderAllocationRuleDto. See the schema below or download the spec for the full
                shape.
              additionalProperties: true
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                description: |-
                  OrderAllocationRuleDto. See the schema below or download the spec for the full
                  shape.
                additionalProperties: true
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Replace an order allocation rule. The request body fully replaces the existing rule;
        fields you omit are reset to defaults. The rule's evaluation priority is managed
        separately via **Update rule sequence**.
    delete:
      tags:
        - Order Allocation Rules
      x-internal: true
      summary: Delete order allocation rule
      operationId: delete-order-allocation-rule
      parameters:
        - name: rule_id
          in: path
          required: true
          schema:
            type: string
          description: Allocation rule ID.
      responses:
        '204':
          description: Deleted.
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Delete an order allocation rule. Orders that would have matched this rule fall through
        to the next matching rule in evaluation order.
  /order-allocation-rules/sequences:
    patch:
      tags:
        - Order Allocation Rules
      x-internal: true
      summary: Update rule sequence
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Set the priority order in which allocation rules are evaluated. Carriyo evaluates
        rules in this order when splitting an order into fulfillment orders.
      operationId: update-order-allocation-rule-sequences
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  ruleId:
                    type: string
                  sequence:
                    type: integer
      responses:
        '200':
          description: Updated.
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.
    delivery-option:
      title: Delivery Option
      type: object
      description: |-
        The delivery option chosen by the customer at checkout. Carriyo uses
        the option's `code` to determine where the order should be fulfilled
        from and which service level applies.
      properties:
        code:
          type: string
          description: The unique code of the delivery option, as configured in Carriyo.
        id:
          type: string
          description: The Carriyo-issued identifier for the delivery option.
        name:
          type: string
          description: The human-readable name of the delivery option.
    create-order-request:
      title: Create Order Request
      type: object
      required:
        - merchant
        - partner_order_reference
        - line_items
      description: |-
        Request body for creating an order.

        **Order-level delivery fields are request-only.** The following fields exist only on the create/update request payloads and are **not stored on the `Order` itself**; they are propagated to each auto-allocated fulfillment order and persisted there:

        - `delivery_method`
        - `delivery_type`
        - `delivery_address`
        - `delivery_schedule`
        - `customer_collection_address`
        - `customer_collection_schedule`

        When `fulfillment_orders` are explicitly provided in the request, the per-FO values take precedence over these top-level values. To inspect or change these fields after creation, read or update them on the corresponding fulfillment order.
      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").
        delivery_method:
          allOf:
            - $ref: '#/components/schemas/delivery-method'
          description: |-
            The delivery method to apply to all auto-allocated fulfillment orders.

            Request-only field, stored on each fulfillment order, not on the `Order`.
        delivery_type:
          type: string
          description: |-
            The delivery service level (e.g., `standard`, `express`, `same_day`). Configurable per tenant. Only applicable when `delivery_method` is `DELIVERY`.

            Request-only field, stored on each fulfillment order, not on the `Order`.
        delivery_option:
          allOf:
            - $ref: '#/components/schemas/delivery-option'
          description: The chosen delivery option reference. Carriyo resolves the underlying carrier and service level from this reference.
        delivery_address:
          allOf:
            - $ref: '#/components/schemas/address'
          description: |-
            The address where the order should be delivered. Used when `delivery_method` is `DELIVERY`.

            Request-only field, stored on each fulfillment order, not on the `Order`.
        delivery_schedule:
          allOf:
            - $ref: '#/components/schemas/fo-schedule'
          description: |-
            The scheduled delivery window. Only applicable when `delivery_method` is `DELIVERY`.

            Request-only field, stored on each fulfillment order, not on the `Order`.
        customer_collection_address:
          allOf:
            - $ref: '#/components/schemas/address'
          description: |-
            The address from which the customer will collect the order (e.g., a store, locker, or pickup point). Only applicable when `delivery_method` is `COLLECTION`.

            Request-only field, stored on each fulfillment order, not on the `Order`.
        customer_collection_schedule:
          allOf:
            - $ref: '#/components/schemas/fo-schedule'
          description: |-
            The window during which the customer can collect the order. Only applicable when `delivery_method` is `COLLECTION`.

            Request-only field, stored on each fulfillment order, not on the `Order`.
        billing_address:
          $ref: '#/components/schemas/address'
        customer:
          allOf:
            - $ref: '#/components/schemas/address'
          description: The customer's contact and address details.
        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. When omitted, Carriyo auto-allocates fulfillment orders based on inventory and rules.
        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'
        status:
          type: string
          enum:
            - open
            - partially_allocated
            - allocated
            - processing
            - fulfilled
            - cancelled
            - 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
            - `processing` - One or more fulfillment orders are being processed (picked, packed, shipped or partially fulfilled)
            - `fulfilled` - All items have been fulfilled
            - `cancelled` - Order has been cancelled
            - `closed` - Order is complete and closed
        auto_allocation_failed:
          type: boolean
          description: Whether automatic fulfillment allocation failed.
        cancellation_reason:
          $ref: '#/components/schemas/cancellation-reason'
        billing_address:
          $ref: '#/components/schemas/address'
        customer:
          allOf:
            - $ref: '#/components/schemas/address'
          description: The customer's contact and address details.
        customer_key:
          type: string
          description: A derived key that uniquely identifies the customer based on email/phone, used to link orders to a customer record.
        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.
        billing_address:
          $ref: '#/components/schemas/address'
        customer:
          allOf:
            - $ref: '#/components/schemas/address'
          description: The customer's contact and address details.
        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 items with pending statuses (`open`, `allocated`, `pick_in_progress`, `picked`, `pack_in_progress`)
            - Items with terminal statuses (`fulfilled`, `cancelled`, `closed`) are automatically preserved
          items:
            $ref: '#/components/schemas/update-fulfillment-order-request'
        delivery_option:
          allOf:
            - $ref: '#/components/schemas/delivery-option'
          description: The chosen delivery option reference. Carriyo resolves the underlying carrier and service level from this reference.
    update-line-item-request:
      title: Update Line Item Request
      type: object
      required:
        - id
        - sku
      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.
        digital:
          type: boolean
          description: Whether this item is a digital product.
        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.
        category:
          type: string
          description: Product category.
        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
      required:
        - partner_fulfillment_order_reference
      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_method:
          $ref: '#/components/schemas/delivery-method'
        delivery_type:
          type: string
          description: The delivery service level (e.g., `standard`, `express`, `same_day`). Only applicable when `delivery_method` is `DELIVERY`.
        delivery_option:
          allOf:
            - $ref: '#/components/schemas/delivery-option'
          description: The chosen delivery option reference. Carriyo resolves the underlying carrier and service level from this reference.
        delivery_address:
          allOf:
            - $ref: '#/components/schemas/address'
          description: The address where the fulfillment order should be delivered. Only applicable when `delivery_method` is `DELIVERY`.
        delivery_schedule:
          allOf:
            - $ref: '#/components/schemas/fo-schedule'
          description: The scheduled delivery window. Only applicable when `delivery_method` is `DELIVERY`.
        customer_collection_address:
          allOf:
            - $ref: '#/components/schemas/address'
          description: The address from which the customer will collect this fulfillment order. Only applicable when `delivery_method` is `COLLECTION`.
        customer_collection_schedule:
          allOf:
            - $ref: '#/components/schemas/fo-schedule'
          description: The window during which the customer can collect the order. Only applicable when `delivery_method` is `COLLECTION`.
        line_items:
          type: array
          description: |-
            Line items for this fulfillment order.

            **Important Rules**:
            - Only include items with pending statuses (`open`, `allocated`, `pick_in_progress`, `picked`, `pack_in_progress`)
            - Do NOT include items with terminal statuses (`fulfilled`, `cancelled`, `closed`); they are preserved automatically
            - This replaces all pending items in the FO
          items:
            $ref: '#/components/schemas/fo-line-item-request'
    discount-allocation:
      title: Discount Allocation
      type: object
      properties:
        amount:
          type: number
          format: double
          description: The discounted amount allocated.
        discount_application_id:
          type: integer
          description: References the corresponding `discount_application_id` in the order's `discount_applications`.
    tax:
      title: Tax
      type: object
      properties:
        amount:
          type: number
          format: double
          description: Tax amount.
        rate:
          type: number
          format: double
          description: Tax rate (e.g., 0.05 for 5%).
        description:
          type: string
          description: Tax description (e.g., "VAT").
    duty:
      title: Duty
      type: object
      properties:
        amount:
          type: number
          format: double
          description: Duty amount.
        rate:
          type: number
          format: double
          description: Duty rate.
        description:
          type: string
          description: Duty description.
        taxes:
          type: array
          items:
            $ref: '#/components/schemas/tax'
          description: Taxes that apply on top of this duty.
    weight:
      title: Weight
      type: object
      properties:
        value:
          type: number
          format: double
        unit:
          type: string
          enum:
            - kg
            - lb
            - gm
          description: |-
            Unit of weight. `gm` is deprecated; use `kg` instead.
    dimension:
      title: Dimension
      type: object
      properties:
        width:
          type: number
          format: double
        height:
          type: number
          format: double
        depth:
          type: number
          format: double
        unit:
          type: string
          enum:
            - cm
            - in
            - mm
          description: |-
            Unit of dimension. `mm` is deprecated; use `cm` instead.
    battery:
      title: Battery
      type: object
      properties:
        material_type:
          type: string
          description: Battery material composition.
          enum:
            - lithium_metal
            - lithium_ion
        packing_type:
          type: string
          description: How the battery is packed.
          enum:
            - contained_in_equipment
            - packed_with_equipment
            - stand_alone
    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
      required:
        - partner_fulfillment_order_reference
      properties:
        fulfillment_order_id:
          type: string
          description: |-
            Carriyo's unique identifier for the fulfillment order. Only used when updating an existing fulfillment order during an order update; ignored on create.
        partner_fulfillment_order_reference:
          type: string
          description: Your system's reference for this fulfillment order.
        location_id:
          type: string
          description: The location ID (or `partner_location_code`) where items will be fulfilled from.
        delivery_method:
          $ref: '#/components/schemas/delivery-method'
        delivery_type:
          type: string
          description: |-
            The delivery service level (e.g., `standard`, `express`, `same_day`). Only applicable when `delivery_method` is `DELIVERY`.
        delivery_option:
          allOf:
            - $ref: '#/components/schemas/delivery-option'
          description: The chosen delivery option reference. Carriyo resolves the underlying carrier and service level from this reference.
        delivery_address:
          allOf:
            - $ref: '#/components/schemas/address'
          description: The address where the fulfillment order should be delivered. Only applicable when `delivery_method` is `DELIVERY`.
        delivery_schedule:
          allOf:
            - $ref: '#/components/schemas/fo-schedule'
          description: The scheduled delivery window. Only applicable when `delivery_method` is `DELIVERY`.
        customer_collection_address:
          allOf:
            - $ref: '#/components/schemas/address'
          description: The address from which the customer will collect this fulfillment order. Only applicable when `delivery_method` is `COLLECTION`.
        customer_collection_schedule:
          allOf:
            - $ref: '#/components/schemas/fo-schedule'
          description: The window during which the customer can collect the order. Only applicable when `delivery_method` is `COLLECTION`.
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/fo-line-item-request'
          description: Line items to include in this fulfillment order.
    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.
        allocation_history:
          type: array
          items:
            $ref: '#/components/schemas/allocation-history'
          description: History of location allocations for this fulfillment order.
        creation_date:
          type: string
          format: date-time
          description: When the fulfillment order was created.
        status:
          type: string
          enum:
            - open
            - allocated
            - processing
            - fulfilled
            - cancelled
            - closed
          description: |-
            Current status of the fulfillment order:
            - `open` - Created, no location assigned
            - `allocated` - Assigned to a location and ready to be fulfilled
            - `processing` - One or more line items are being picked, packed, shipped, or partially fulfilled
            - `fulfilled` - All line items have been fulfilled
            - `cancelled` - Fulfillment order has been cancelled
            - `closed` - All processing is complete
        delivery_method:
          $ref: '#/components/schemas/delivery-method'
        delivery_type:
          type: string
          description: The delivery service level (e.g., `standard`, `express`, `same_day`). Only applicable when `delivery_method` is `DELIVERY`.
        delivery_option:
          allOf:
            - $ref: '#/components/schemas/delivery-option'
          description: The chosen delivery option reference. Carriyo resolves the underlying carrier and service level from this reference.
        delivery_address:
          allOf:
            - $ref: '#/components/schemas/address'
          description: The address where the fulfillment order is to be delivered. Only applicable when `delivery_method` is `DELIVERY`.
        delivery_schedule:
          allOf:
            - $ref: '#/components/schemas/fo-schedule'
          description: The scheduled delivery window. Only applicable when `delivery_method` is `DELIVERY`.
        customer_collection_address:
          allOf:
            - $ref: '#/components/schemas/address'
          description: The address from which the customer will collect this fulfillment order. Only applicable when `delivery_method` is `COLLECTION`.
        customer_collection_schedule:
          allOf:
            - $ref: '#/components/schemas/fo-schedule'
          description: The window during which the customer can collect the order. Only applicable when `delivery_method` is `COLLECTION`.
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/fo-line-item'
    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
      required:
        - cancellation_reason
        - line_items
      properties:
        cancellation_reason:
          $ref: '#/components/schemas/cancellation-reason'
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/fo-line-item-request'
          description: The line items to cancel.
    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.
    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 for this fulfillment.
    address:
      title: Address
      type: object
      description: |-
        Carriyo address object used for customer, billing, delivery and customer-collection addresses.

        You can either pass a fully free-form address (`contact_name`, `address1`, `city`, `country`, etc.) or reference a pre-configured location in Carriyo using `partner_location_id`, `partner_location_name`, or `partner_location_code`.
      properties:
        partner_location_id:
          type: string
          description: |-
            Reference to a pre-configured location in Carriyo. When provided, the address is resolved from the matching location and free-form fields are typically not required.
        partner_location_name:
          type: string
          description: Alternative way to reference a Carriyo location by name.
        partner_location_code:
          type: string
          description: Alternative way to reference a Carriyo location by your custom location code.
        collection_point_id:
          type: string
          description: ID of the carrier's collection point for deliveries held at the carrier location for collection.
        contact_name:
          type: string
          description: Name of the contact person or business.
          example: Jo Bloggs
        personal_id:
          $ref: '#/components/schemas/personal-id'
        contact_phone:
          type: string
          description: |-
            Primary phone number for contact in E164 Format with country code, e.g., +16175551212.
            Conditionally mandatory based on Account Settings.
          format: E164 Format (with +<country-code-prefix>)
          example: '+16175551212'
        alternate_phone:
          type: string
          description: Alternate phone number for contact in E164 Format with country code.
          format: E164 Format (with +<country-code-prefix>)
          example: '+16175551210'
        contact_email:
          type: string
          format: email
          description: |-
            Email address for contact.
            Conditionally mandatory based on Account Settings.
          example: jo.bloggs@example.com
        company_name:
          type: string
          description: Business or legal entity name. Optional; only needed when it differs from `contact_name`.
          example: Acme Fashion Ltd
        address1:
          type: string
          description: Address Line 1 (e.g., street, PO Box, or company name).
          example: 1 Financial Centre Road
        address2:
          type: string
          description: Address Line 2 (e.g., apartment, floor, unit, or building).
          example: Downtown Views, Apartment 101
        city:
          type: string
          description: |-
            City, town, or village, represented by the Carriyo City Code if known. If not, it's a free text.

            [Please refer to the Carriyo Geo List for more information.](https://carriyo.com/docs/guides/carriyo-geo-list)
          example: DUBAI
        state:
          type: string
          description: |-
            State, county, province, or region, represented by the Carriyo State Code if known. If not, it's a free text.
          example: DUBAI
        postcode:
          type: string
          description: ZIP or postal code.
          example: E1 6AN
        country:
          type: string
          description: Two-letter country code (ISO 3166-1 alpha-2).
          example: AE
          format: Two-letter ISO country code
        area:
          type: string
          description: |-
            District, suburb or neighbourhood, represented by the Carriyo Area Code if known. If not, it's a free text.
          example: DOWNTOWN-DUBAI
        coords:
          type: array
          description: Latitude and longitude (decimal degrees) of the address as an array. e.g., `[25.19741, 55.27442]`.
          items:
            type: number
            format: double
        type:
          type: string
          description: Type of address.
          enum:
            - residential
            - business
        notes:
          type: string
          maxLength: 1000
          description: Any additional notes, e.g., "Leave the parcel next to the bin".
        street:
          type: string
          description: Street name when capturing the address in structured form.
        building:
          type: string
          description: Building name or number.
        floor:
          type: string
          description: Floor.
        flat:
          type: string
          description: Flat or apartment.
        po_box:
          type: string
          description: Box number if the address is a PO Box.
        custom_fields:
          $ref: '#/components/schemas/custom-fields'
        address_codes:
          $ref: '#/components/schemas/address-codes'
    address-codes:
      title: Address Codes
      type: array
      items:
        $ref: '#/components/schemas/address-code'
    address-code:
      title: Address Code
      type: object
      description: Location-specific address identifier used in certain countries or systems to enhance delivery precision
      properties:
        type:
          type: string
          enum:
            - WHAT_3_WORDS
            - EMIRATES_MAKANI_CODE
            - KUWAIT_PACI_CODE
            - SAUDI_SHORT_CODE
          description: Type of address code
        value:
          type: string
          description: The actual value of the address code corresponding to the selected type
    order-payment:
      title: Order Payment
      type: object
      properties:
        currency:
          type: string
          description: Currency code (ISO 4217).
        order_total:
          type: number
          format: double
          description: Total amount of the order in the specified currency.
        payment_on_delivery:
          type: number
          format: double
          description: |-
            Amount the customer needs to pay on delivery (e.g., for cash-on-delivery or card-on-delivery orders). `0` or omitted indicates a fully prepaid order.
    discount-application:
      title: Discount Application
      type: object
      properties:
        discount_application_id:
          type: integer
          description: Identifier referenced by line item discount allocations.
        type:
          type: string
          description: Type of discount (e.g., `percentage`, `fixed_amount`, `automatic`).
        coupon_code:
          type: string
          description: The coupon or discount code applied.
    line-item:
      title: Line Item
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: Unique identifier for the line item within the order.
        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.
        digital:
          type: boolean
          description: Whether this item is a digital product.
        quantity:
          type: integer
          description: Quantity ordered.
        removed_quantities:
          type: array
          items:
            $ref: '#/components/schemas/removed-quantity'
          description: Tracks quantities removed from this line item over its lifecycle.
        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.
        category:
          type: string
          description: Product category.
        dangerous_goods:
          type: boolean
          description: Whether the item contains dangerous goods.
        battery:
          $ref: '#/components/schemas/battery'
    fo-line-item-request:
      title: Fulfillment Order Line Item Request
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: Reference to the order line item's `id`.
        quantity:
          type: integer
          description: Quantity to fulfill.
    fo-line-item:
      title: Fulfillment Order Line Item
      type: object
      properties:
        id:
          type: string
          description: Reference to the order line item's `id`.
        quantity:
          type: integer
          description: Quantity in this fulfillment order.
        status:
          type: string
          enum:
            - open
            - allocated
            - pick_in_progress
            - picked
            - pack_in_progress
            - cancelled
            - fulfilled
            - closed
          description: |-
            Current status of the line item:
            - `open` - Item is pending allocation
            - `allocated` - Item is allocated and ready for fulfillment
            - `pick_in_progress` - Item is being picked
            - `picked` - Item has been picked
            - `pack_in_progress` - Item is being packed
            - `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.
        partner_fulfillment_reference:
          type: string
          description: Your system's reference for the fulfillment of this line item.
        shipment_ids:
          type: array
          items:
            type: string
          description: IDs of shipments containing this item.
        collection_ids:
          type: array
          items:
            type: string
          description: IDs of customer collections (when delivery method is `COLLECTION`) containing this item.
        cancellation_reason:
          type: string
          description: Reason this item was cancelled, if applicable.
    shipping-line:
      title: Shipping Line
      type: object
      properties:
        name:
          type: string
          description: Display name for the shipping method.
        carrier_account_id:
          type: string
          description: ID of the carrier account chosen for this shipping line.
        carrier:
          type: string
          description: Carrier code.
        price:
          type: number
          format: double
          description: Shipping cost.
        taxes:
          type: array
          items:
            $ref: '#/components/schemas/tax'
          description: Taxes applied on the shipping cost.
    fulfillment-delivery:
      title: Fulfillment Delivery
      type: object
      description: Scheduling window for a fulfillment.
      properties:
        scheduled_from:
          type: string
          format: date-time
          description: Start of the scheduled window.
        scheduled_to:
          type: string
          format: date-time
          description: End of the scheduled window.
    fulfillment-payment:
      title: Fulfillment Payment
      type: object
      properties:
        currency:
          type: string
          description: Currency code (ISO 4217).
        fulfillment_total:
          type: number
          format: double
          description: Total amount for this fulfillment.
        payment_on_delivery:
          type: number
          format: double
          description: Amount to be collected on delivery for this fulfillment.
        payment_mode:
          type: string
          description: |-
            Payment mode for this fulfillment (e.g., `prepaid`, `cash_on_delivery`, `card_on_delivery`). The exact set of valid values is configurable per tenant.
    carrier-account-request:
      title: Carrier Account Request
      type: object
      description: Identifies a specific carrier account configured in Carriyo.
      properties:
        carrier_id:
          type: string
          description: ID of the carrier (e.g., `aramex`, `dhl`).
        carrier_account_name:
          type: string
          description: Name of the carrier account configured in Carriyo.
    parcel-request:
      title: Parcel Request
      type: object
      properties:
        packing_template_reference:
          type: string
          description: Reference to a pre-configured packing template.
        parcel_id:
          type: string
          description: Carriyo's parcel ID, when updating an existing parcel.
        partner_parcel_reference:
          type: string
          description: Your system's reference for this parcel.
        description:
          type: string
          description: Description of parcel contents.
        weight:
          $ref: '#/components/schemas/weight'
        dimension:
          $ref: '#/components/schemas/dimension'
        parcel_items:
          type: array
          description: Items inside this parcel. Each entry references an order line item id with its packed quantity.
          items:
            type: object
            properties:
              id:
                type: string
                description: The line item `id`.
              quantity:
                type: integer
                description: Quantity of this line item in the parcel.
    pre-booking-info:
      title: Pre-Booking Info
      type: object
      description: Information about a shipment that has already been booked with a carrier outside Carriyo.
      properties:
        carrier_tracking_no:
          type: string
          description: Tracking number from the carrier.
        carrier_tracking_url:
          type: string
          description: Tracking URL provided by the carrier.
        input_carrier:
          type: string
          description: The carrier used for the pre-booked shipment.
    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
      description: Describes which system or actor triggered an order create or update.
      properties:
        source_type:
          type: string
          description: |-
            The type of source (e.g., `api`, `dashboard`, `handler`, `carriyo`, `order_service`, `shopify_connector`, `magento_connector`, etc.).
        source_id:
          type: string
          description: Identifier of the originator (e.g., user id, connector identifier).
        api_pattern:
          type: string
          description: For API-originated requests, the matched API path pattern.
        request_type:
          type: string
          description: The Carriyo request type that produced this change (e.g., `ORDER_CREATE`, `ORDER_UPDATE`).
        system_log_identifier:
          type: string
          description: Reference to the system log entry that recorded this request.
    error-detail:
      title: Error Detail
      type: object
      properties:
        level:
          type: string
          description: Severity level of the error (e.g., `error`, `warning`).
        trigger:
          type: string
          description: What triggered this error (e.g., the operation or field).
        source:
          type: string
          description: Where the error originated (e.g., `carriyo`, `carrier`).
        type:
          type: string
          description: Category of error.
        message:
          type: string
          description: Human-readable error message.
        code:
          type: string
          description: Machine-readable error code.
        field:
          type: string
          description: The field that caused the error, if applicable.
    update-fulfillment-order-delivery-method-request:
      title: Update Delivery Method Request
      type: object
      description: |-
        Request body for changing the delivery method of a fulfillment order. The required fields depend on the new `delivery_method`.
      required:
        - delivery_method
      properties:
        delivery_method:
          $ref: '#/components/schemas/delivery-method'
        address:
          allOf:
            - $ref: '#/components/schemas/address'
          description: |-
            The new address for the fulfillment order.
            - For `DELIVERY`: the new delivery address.
            - For `COLLECTION`: the new customer collection address.
            - For `DIGITAL`: not required.
        scheduled_from:
          type: string
          format: date-time
          description: |-
            Start of the new scheduled window (delivery or customer-collection, depending on `delivery_method`).
        scheduled_to:
          type: string
          format: date-time
          description: End of the new scheduled window.
        delivery_type:
          type: string
          description: |-
            The delivery service level (e.g., `standard`, `express`). Only applicable when `delivery_method` is `DELIVERY`.
        delivery_option:
          type: object
          description: Carriyo delivery option reference.
          properties:
            code:
              type: string
              description: The delivery option code as configured in Carriyo.
            id:
              type: string
              description: The delivery option ID.
    update-fulfillment-order-address-request:
      title: Update Address Request
      type: object
      required:
        - address
      properties:
        address:
          allOf:
            - $ref: '#/components/schemas/address'
          description: |-
            The new address. Applies to `delivery_address` when `delivery_method` is `DELIVERY`, or `customer_collection_address` when `delivery_method` is `COLLECTION`.
    update-fulfillment-order-schedule-request:
      title: Update Schedule Request
      type: object
      description: |-
        Request body for updating the scheduled window of a fulfillment order.

        - For fulfillment orders with `delivery_method: DELIVERY`, this updates the `delivery_schedule`.
        - For fulfillment orders with `delivery_method: COLLECTION`, this updates the `customer_collection_schedule`.
      properties:
        scheduled_from:
          type: string
          format: date-time
          description: Start of the scheduled window.
        scheduled_to:
          type: string
          format: date-time
          description: End of the scheduled window.
    update-fulfillment-order-partner-references-request:
      title: Update Fulfillment Order References Request
      type: object
      description: |-
        Request body for updating partner reference fields on a fulfillment order. Either `partner_fulfillment_order_reference` or `fulfillments` (or both) may be provided.
      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' partner references.
    delivery-method:
      title: Delivery Method
      type: string
      description: |-
        How the order is delivered to the customer:
        - `DELIVERY`: standard delivery to the customer's address (uses `delivery_address` and `delivery_schedule`).
        - `COLLECTION`: customer collects the order from a specified location (uses `customer_collection_address` and `customer_collection_schedule`).
        - `DIGITAL`: no physical delivery; the order is fulfilled digitally.
      enum:
        - DELIVERY
        - COLLECTION
        - DIGITAL
    fo-schedule:
      title: Fulfillment Order Schedule
      type: object
      description: A scheduled window expressed as a `from`–`to` date-time pair.
      properties:
        scheduled_from:
          type: string
          format: date-time
          description: Start of the scheduled window.
        scheduled_to:
          type: string
          format: date-time
          description: End of the scheduled window.
    allocation-history:
      title: Allocation History
      type: object
      description: A historical entry showing when and why a fulfillment order was allocated to a location.
      properties:
        date:
          type: string
          format: date-time
          description: When the allocation occurred.
        location_id:
          type: string
          description: The location the fulfillment order was allocated to.
        reason:
          type: string
          description: Reason for the allocation (e.g., `auto_allocation`, `manual_reallocation`).
    personal-id:
      title: Personal ID
      type: object
      description: ID of the person to whom the shipment is addressed.
      properties:
        id:
          type: string
          description: ID number.
          example: U123457896
        type:
          type: string
          description: ID type.
          example: Passport
    removed-quantity:
      title: Removed Quantity
      type: object
      description: Tracks a quantity removed from a line item over the order's lifecycle.
      properties:
        quantity:
          type: integer
          description: The quantity that was removed.
        note:
          type: string
          description: Optional note describing why the quantity was removed.
    custom-fields:
      title: Custom Fields
      type: object
      additionalProperties:
        type: array
        items:
          type: string
      description: |-
        Custom fields in the form of a map of arrays:
        ```
        {"field1": ["value1", "value2"], "field2": ["value1"]}
        ```
  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: {}
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: "Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`."
    TenantId:
      type: apiKey
      in: header
      name: tenant-id
      description: "Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`."
