openapi: 3.0.1
info:
  title: Carriyo Shipping API
  description: |-
    Manage individual shipments: create, confirm, cancel, and track parcels from booking through delivery. Covers the full shipment lifecycle including label and document retrieval, status overrides, consolidated (master) shipments, manifests, and bulk operations.

    Shipment booking is asynchronous. Creating or confirming a shipment returns `pending`; the carrier-confirmed outcome (tracking number, label, or booking error) arrives by webhook.
  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: shipments
    description: |-
      ## The shipment object

      The shipment object is the backbone of the Shipping API. It represents a grouping of items that are transported together from a starting point to a final destination, in one or more parcels.

      The type of shipment can be classified as either `FORWARD` or `REVERSE`. A forward shipment moves items from a merchant to a customer; a reverse shipment is the opposite, returning items from a customer to a merchant.

      Each shipment is given two identifiers: a `shipment_id` generated by Carriyo, and a `partner_shipment_reference` supplied by the merchant.

      <JsonSchema
        definitionId="shipping"
        pointer="#/components/schemas/shipment-object"
      />
  - name: manifests
    description: |-
      A manifest is a collection of shipments shipped together from the same location with the same carrier. It acts as an instruction to schedule the collection of the shipments with your carrier.
  - name: consolidated-shipments
    description: |-
      Consolidated (master) shipments group multiple child shipments under a single parent. Useful for multi-parcel consignments and freight where one master tracking number aggregates several physical movements.
  - name: bulk-operations
    description: |-
      Do-X-to-many-shipments operations: kick off a batch, poll for status, validate before booking, retry, force a status refresh.

      Unlike Consolidated shipments, which represents a master shipment containing child shipments, these endpoints operate over arbitrary sets of independent shipments in a single call. Useful for high-volume booking flows and back-office bulk corrections.
  - name: shipment-audit
    description: |-
      Audit trails: system logs (carrier API calls, internal events) and change logs (field-level history) for individual shipments.
paths:
  /shipments:
    post:
      tags:
        - shipments
      summary: Create shipment
      description: |-
        Create a shipment. Returns a unique `shipment_id`. Either name a `carrier_account` explicitly or let Carriyo's predefined automation rules pick one.

        ### Forward vs reverse

        Set `entity_type` to either:

        - `FORWARD`: a normal outbound shipment from the merchant to the customer.
        - `REVERSE`: a return shipment, where the customer sends items back to the merchant.

        ### Draft, confirmed, prebooked

        Three creation modes, each with different behaviour against the carrier:

        - **Draft** (`?draft=true`): the shipment is saved in Carriyo for visibility but is **not** sent to the carrier. Use this when parcel details aren't final yet. The shipment stays in `draft` until you call **Confirm shipment**.
        - **Confirmed** (default, no `?draft` query parameter): Carriyo validates the payload, assigns a carrier, and immediately submits the booking request to that carrier. The API responds with status `pending` straight away, without waiting for the carrier's response. The carrier's outcome (acceptance, rejection, label) arrives via webhook. If Carriyo's own validations fail, the shipment is created in `error` status with the validation errors in the response.
        - **Prebooked** (`pre_booked: true`): register a shipment that was booked outside Carriyo so Carriyo can track it. Once registered, the shipment shows up alongside the rest of your shipments in operational monitoring, reporting, and the branded customer tracking experience. Carriyo does **not** call the carrier's booking endpoint in this mode, but it does take ownership of tracking the shipment with the carrier from this point on. Supply the existing carrier and tracking number in `pre_booking_info`:

            ```json
            {
              "pre_booked": true,
              "pre_booking_info": {
                "input_carrier": "DHL",
                "carrier_tracking_no": "1234567890"
              }
            }
            ```

        ### After booking

        Once the carrier accepts the booking, the shipment status moves to `booked` and the carrier's tracking number is attached. A label is generated. From that point, all subsequent status changes and label updates are pushed to your webhooks; the response from this endpoint represents only the moment of submission, not the carrier's final decision.
      operationId: create-shipment
      parameters:
        - schema:
            type: boolean
          in: query
          name: draft
          description: Pass true for draft shipment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/shipment-request'
            examples:
              Domestic Shipment:
                value:
                  entity_type: FORWARD
                  merchant: MERCHANT-ID
                  references:
                    partner_order_reference: domestic-order-001
                    partner_shipment_reference: domestic-ship-001
                  payment:
                    payment_mode: PRE_PAID
                    total_amount: 49.98
                    currency: GBP
                  items:
                    - description: Classic Sneakers - White, Size 42
                      sku: SNKR-W-42
                      quantity: 1
                      price:
                        amount: 34.99
                        currency: GBP
                      weight:
                        value: 1
                        unit: kg
                    - description: Baseball Cap - Navy
                      sku: CAP-NVY-01
                      quantity: 1
                      price:
                        amount: 14.99
                        currency: GBP
                      weight:
                        value: 0.5
                        unit: kg
                  parcels:
                    - partner_parcel_reference: parcel-001
                      weight:
                        value: 1.5
                        unit: kg
                      dimension:
                        width: 30
                        height: 20
                        depth: 15
                        unit: cm
                  pickup:
                    contact_name: Acme Fashion Warehouse
                    contact_phone: '+442071234567'
                    contact_email: warehouse@acmefashion.co.uk
                    address1: Unit 5, Riverside Industrial Estate
                    city: Manchester
                    state: Greater Manchester
                    country: GB
                    postcode: M17 1SG
                  dropoff:
                    contact_name: James Wilson
                    contact_phone: '+447700100200'
                    contact_email: james.wilson@example.com
                    address1: 14 Elm Street
                    city: Birmingham
                    state: West Midlands
                    country: GB
                    postcode: B1 2HL
                  order_date: '2026-04-15T10:00:00.000+00:00'
              Cash on Delivery Shipment:
                value:
                  entity_type: FORWARD
                  merchant: MERCHANT-ID
                  references:
                    partner_order_reference: cod-order-201
                    partner_shipment_reference: cod-ship-201
                  payment:
                    payment_mode: CASH_ON_DELIVERY
                    pending_amount: 350
                    total_amount: 350
                    currency: AED
                  items:
                    - description: Running Shoes - Black, Size 44
                      sku: SHOE-RUN-BLK-44
                      quantity: 1
                      price:
                        amount: 250
                        currency: AED
                      weight:
                        value: 1.2
                        unit: kg
                    - description: Sports Water Bottle - 750ml
                      sku: BOTTLE-750
                      quantity: 1
                      price:
                        amount: 100
                        currency: AED
                      weight:
                        value: 0.3
                        unit: kg
                  parcels:
                    - partner_parcel_reference: parcel-201
                      weight:
                        value: 1.5
                        unit: kg
                      dimension:
                        width: 35
                        height: 25
                        depth: 15
                        unit: cm
                  pickup:
                    contact_name: Acme Sports Store
                    contact_phone: '+97143872701'
                    contact_email: ops@acmesports.ae
                    address1: Shop 14, Mall of the Emirates
                    city: Dubai
                    state: Dubai
                    country: AE
                  dropoff:
                    contact_name: Ali Hassan
                    contact_phone: '+971561234567'
                    contact_email: ali.hassan@example.com
                    address1: Villa 12, Al Barsha 1
                    city: Dubai
                    state: Dubai
                    country: AE
                    coords:
                      - 25.1136
                      - 55.2003
                  order_date: '2026-04-15T10:00:00.000+04:00'
              B2B Freight Shipment:
                value:
                  entity_type: FORWARD
                  merchant: MERCHANT-ID
                  references:
                    partner_order_reference: b2b-order-501
                    partner_shipment_reference: b2b-ship-501
                  payment:
                    payment_mode: PRE_PAID
                    total_amount: 5000
                    currency: GBP
                  items:
                    - description: Office Desk Chair - Ergonomic
                      sku: CHAIR-ERGO-BLK
                      quantity: 20
                      price:
                        amount: 250
                        currency: GBP
                      weight:
                        value: 15
                        unit: kg
                  freight:
                    packages:
                      - package_reference: pallet-001
                        type: pallet
                        weight:
                          value: 320
                          unit: kg
                        dimension:
                          width: 120
                          height: 150
                          depth: 100
                          unit: cm
                      - package_reference: carton-001
                        type: carton
                        weight:
                          value: 16
                          unit: kg
                        dimension:
                          width: 60
                          height: 70
                          depth: 50
                          unit: cm
                        parent: pallet-001
                      - package_reference: carton-002
                        type: carton
                        weight:
                          value: 16
                          unit: kg
                        dimension:
                          width: 60
                          height: 70
                          depth: 50
                          unit: cm
                        parent: pallet-001
                  pickup:
                    contact_name: Acme Furniture Warehouse
                    company_name: Acme Furniture Co.
                    contact_phone: '+441234567890'
                    contact_email: warehouse@acmefurniture.co.uk
                    address1: Unit 8, Trafford Park Industrial Estate
                    city: Manchester
                    state: Greater Manchester
                    country: GB
                    postcode: M17 1HH
                  dropoff:
                    contact_name: Corporate Interiors Receiving
                    company_name: Corporate Interiors Ltd
                    contact_phone: '+441214567890'
                    contact_email: receiving@corpinteriors.co.uk
                    address1: 25 Victoria Road, Aston
                    city: Birmingham
                    state: West Midlands
                    country: GB
                    postcode: B6 5HG
                  order_date: '2026-04-15T08:00:00.000+00:00'
              Cross-Border Shipment:
                value:
                  entity_type: FORWARD
                  merchant: MERCHANT-ID
                  references:
                    partner_order_reference: intl-order-1001
                    partner_shipment_reference: intl-ship-1001
                  payment:
                    payment_mode: PRE_PAID
                    total_amount: 139.99
                    currency: USD
                  items:
                    - description: Women's cotton T-shirt, size M, navy blue
                      sku: TSHIRT-W-M-NAVY
                      quantity: 2
                      price:
                        amount: 25
                        currency: USD
                      weight:
                        value: 0.2
                        unit: kg
                      hs_code: '610910'
                      origin_country: IN
                    - description: Wireless Bluetooth earbuds with charging case
                      sku: EARBUDS-BT-001
                      quantity: 1
                      price:
                        amount: 89.99
                        currency: USD
                      weight:
                        value: 0.15
                        unit: kg
                      hs_code: '851830'
                      origin_country: CN
                      dangerous_goods: false
                      battery:
                        material_type: lithium_ion
                        packing_type: contained_in_equipment
                  parcels:
                    - weight:
                        value: 0.9
                        unit: kg
                      dimension:
                        width: 30
                        height: 20
                        depth: 15
                        unit: cm
                      parcel_items:
                        - sku: TSHIRT-W-M-NAVY
                          quantity: 2
                        - sku: EARBUDS-BT-001
                          quantity: 1
                  customs:
                    incoterms: DAP
                    declaration_statement: |-
                      I hereby certify that the information on this invoice is true and correct and
                      that the contents of this shipment are as stated above.
                    seller:
                      contact_name: Ahmed Al Rashid
                      company_name: Acme Fashion Ltd
                      contact_phone: '+971501234567'
                      contact_email: exports@acmefashion.com
                      address1: Dubai Internet City, Building 12
                      city: Dubai
                      country: AE
                      postcode: '00000'
                      registration_numbers:
                        - type_code: VAT
                          value: '100234567890003'
                          issuer_country_code: AE
                    buyer:
                      contact_name: Jane Smith
                      contact_phone: '+447700900123'
                      contact_email: jane.smith@example.com
                      address1: 42 King's Road
                      city: London
                      state: England
                      country: GB
                      postcode: SW3 4ND
                    exporter:
                      contact_name: Ahmed Al Rashid
                      company_name: Acme Fashion Ltd
                      contact_phone: '+971501234567'
                      contact_email: exports@acmefashion.com
                      address1: Dubai Internet City, Building 12
                      city: Dubai
                      country: AE
                      postcode: '00000'
                      registration_numbers:
                        - type_code: EOR
                          value: AEXXXXXXXXX
                          issuer_country_code: AE
                    importer:
                      contact_name: Jane Smith
                      contact_phone: '+447700900123'
                      address1: 42 King's Road
                      city: London
                      state: England
                      country: GB
                      postcode: SW3 4ND
                      registration_numbers:
                        - type_code: EOR
                          value: GB205672212000
                          issuer_country_code: GB
                  pickup:
                    partner_location_code: DUBAI-WH-01
                  dropoff:
                    contact_name: Jane Smith
                    contact_phone: '+447700900123'
                    contact_email: jane.smith@example.com
                    address1: 42 King's Road
                    city: London
                    state: England
                    country: GB
                    postcode: SW3 4ND
                  order_date: '2026-04-15T14:30:00.000+04:00'
              Draft Shipment:
                description: |-
                  A draft shipment can be created with partial data using the draft=true query
                  parameter. Missing fields such as pickup and parcels can be added later before
                  confirming.
                value:
                  merchant: MERCHANT-ID
                  references:
                    partner_order_reference: draft-order-001
                    partner_shipment_reference: draft-ship-001
                  payment:
                    payment_mode: PRE_PAID
                    total_amount: 199.99
                    currency: AED
                  items:
                    - description: Wireless Headphones - Black
                      sku: WH-BLK-100
                      quantity: 1
                      price:
                        amount: 199.99
                        currency: AED
                  dropoff:
                    contact_name: Sara Ahmed
                    contact_phone: '+971509876543'
                    contact_email: sara.ahmed@example.com
                    address1: Apt 1402, Marina Heights Tower
                    city: Dubai
                    state: Dubai
                    country: AE
        required: true
        description: ''
      responses:
        '200':
          description: Shipment created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
              examples:
                200 Error Response:
                  value:
                    shipment_id: KR22VUXEXGKX1
                    merchant: MERCHANT-ID
                    entity_type: FORWARD
                    carrier_account: {}
                    references:
                      partner_order_reference: test-order-1
                      partner_shipment_reference: test-order-1
                    payment:
                      payment_mode: PRE_PAID
                      pending_amount: 0
                      total_amount: 99
                      currency: USD
                    delivery:
                      delivery_type: STANDARD
                      scheduled_from: '2021-07-15T06:00:00.000Z'
                      scheduled_to: '2021-07-15T10:00:00.000Z'
                    parcels:
                      - parcel_id: KR22VUXEXGKX1-1
                        partner_parcel_reference: ''
                        description: Parcel 1
                        weight:
                          value: 1
                          unit: kg
                        dimension:
                          width: 10
                          height: 10
                          depth: 10
                          unit: cm
                    items:
                      - sku: S12345
                        description: Carriyo T-Shirt
                        barcode: B12345
                        image_link: https://mybusiness.com/images/sku1.png
                        origin_country: US
                        quantity: 1
                        price:
                          amount: 99
                          currency: USD
                        cost:
                          amount: 20
                          currency: USD
                        weight:
                          value: 1
                          unit: kg
                        dangerous_goods: false
                    customs:
                      declared_value:
                        amount: 100
                        currency: USD
                      incoterms: DDU
                    pickup:
                      partner_location_id: ACCOUNT_bef3862a-b27e-45d4-b077-8e8f4d674849
                      contact_name: Customer Service
                      contact_phone: '+971561234567'
                      contact_email: crm@mybusiness.com
                      address1: DIP Delivery Warehouse
                      area: DUBAI-INVESTMENT-PARK-1
                      city: DUBAI
                      state: DUBAI
                      country: AE
                      coords:
                        - 29.373420706419914
                        - 47.97881566875099
                    dropoff:
                      contact_name: Jo Bloggs
                      contact_phone: '+971561234567'
                      contact_email: jo.bloggs@gmail.com
                      address1: 1 Financial Centre Road
                      address2: Downtown Views, Apartment 101
                      area: DOWNTOWN-DUBAI
                      city: DUBAI
                      state: DUBAI
                      country: AE
                      coords:
                        - 29.294045
                        - 48.087608
                    post_shipping_info:
                      status: error
                      key_milestones: {}
                      error_details:
                        - level: ERROR
                          trigger: BOOKING
                          source: CARRIYO
                          type: VALIDATION
                          message: |-
                            No carrier assigned. Please provide valid carrier and reprocess booking
                            again.
                          code: no_carrier_assigned
                          field: carrier
                        - level: WARNING
                          trigger: BOOKING
                          source: CARRIYO
                          type: VALIDATION
                          message: Contact Email is missing.
                          code: email_missing
                          field: dropoff.contact_email
                    creation_date: '2021-07-13T13:16:23.016Z'
                    confirmation_date: '2021-07-13T13:16:23.149Z'
                    update_date: '2021-08-10T17:31:20.218Z'
                    order_date: '2021-07-13T11:42:12.889Z'
                    language: en
                200 Pending Response:
                  value:
                    shipment_id: KR22VUXEXGKX1
                    merchant: MERCHANT-ID
                    entity_type: FORWARD
                    carrier_account:
                      carrier: ARAMEX
                      carrier_id: c1053e4b-f2e7-4cee-917f-a390e73887a6
                      carrier_account_name: ARAMEX UAE
                    references:
                      partner_order_reference: test-order-1
                      partner_shipment_reference: test-order-1
                    payment:
                      payment_mode: PRE_PAID
                      pending_amount: 0
                      total_amount: 99
                      currency: USD
                    delivery:
                      delivery_type: STANDARD
                      scheduled_from: '2021-07-15T06:00:00.000Z'
                      scheduled_to: '2021-07-15T10:00:00.000Z'
                    parcels:
                      - parcel_id: KR22VUXEXGKX1-1
                        partner_parcel_reference: ''
                        description: Parcel 1
                        weight:
                          value: 1
                          unit: kg
                        dimension:
                          width: 10
                          height: 10
                          depth: 10
                          unit: cm
                    items:
                      - sku: S12345
                        description: Carriyo T-Shirt
                        barcode: B12345
                        image_link: https://mybusiness.com/images/sku1.png
                        origin_country: US
                        quantity: 1
                        price:
                          amount: 99
                          currency: USD
                        cost:
                          amount: 20
                          currency: USD
                        weight:
                          value: 1
                          unit: kg
                        dangerous_goods: false
                    pickup:
                      partner_location_id: ACCOUNT_bef3862a-b27e-45d4-b077-8e8f4d674849
                      contact_name: Customer Service
                      contact_phone: '+971561234567'
                      contact_email: crm@mybusiness.com
                      address1: DIP Delivery Warehouse
                      area: DUBAI-INVESTMENT-PARK-1
                      city: DUBAI
                      state: DUBAI
                      country: AE
                      coords:
                        - 29.373420706419914
                        - 47.97881566875099
                    dropoff:
                      contact_name: Jo Bloggs
                      contact_phone: '+971561234567'
                      contact_email: jo.bloggs@gmail.com
                      address1: 1 Financial Centre Road
                      address2: Downtown Views, Apartment 101
                      area: DOWNTOWN-DUBAI
                      city: DUBAI
                      state: DUBAI
                      country: AE
                      coords:
                        - 29.294045
                        - 48.087608
                    post_shipping_info:
                      status: pending
                      key_milestones: {}
                    creation_date: '2021-07-13T13:16:23.016Z'
                    confirmation_date: '2021-07-13T13:16:23.149Z'
                    update_date: '2021-08-10T17:31:20.218Z'
                    order_date: '2021-07-13T11:42:12.889Z'
                    language: en
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-shipment-error-response'
              examples:
                400 Error Response:
                  value:
                    status: '400'
                    timestamp: '2021-08-10T17:34:22.906Z'
                    errors:
                      - Duplicate partner shipment reference
      x-codegen-request-body-name: body
    get:
      tags:
        - shipments
      summary: List shipments
      description: |-
        Return a paginated list of shipments matching the search and filter parameters. The
        `search_string` parameter does a substring match across carrier tracking number, order
        reference, shipment reference, customer name, email, and similar fields; combine it with
        the other filters, sort, and pagination parameters as needed.


        > **Quota:** this endpoint is subject to your account's monthly shipment quota. Once the
        monthly limit is exceeded, further requests are blocked until the quota resets.
      operationId: list-shipments
      parameters:
        - name: search_string
          in: query
          required: false
          schema:
            type: string
          description: |-
            The search string to find shipments using shipment data such as carrier tracking number,
            order reference, shipment reference, customer name, email etc.
        - name: order_ref
          in: query
          required: false
          schema:
            type: string
          description: The string to be used to fetch shipments for a given order reference.
        - name: merchant
          in: query
          required: false
          schema:
            type: string
          description: |-
            The merchant parameter filters shipments for a given merchant. This parameter can be
            used multiple times to filter results for multiple merchants.
        - name: shipment_type
          in: query
          required: false
          schema:
            type: string
          description: |-
            The shipment type can either be `forward` or `reverse`. If not passed, then both types
            of shipments will be included in the results.
        - name: creation_date_from
          in: query
          required: false
          schema:
            type: string
          description: The start date in ISO 8601 format to filter the results using shipment creation date.
        - name: creation_date_to
          in: query
          required: false
          schema:
            type: string
          description: The end date in ISO 8601 format to filter the results using shipment creation date.
        - name: update_date_from
          in: query
          required: false
          schema:
            type: string
          description: |-
            The start date in ISO 8601 format to filter results, returning shipments that were
            either created OR updated during this time period.
        - name: update_date_to
          in: query
          required: false
          schema:
            type: string
          description: |-
            The end date in ISO 8601 format to filter results, returning shipments that were either
            created OR updated during this time period.
        - name: page
          in: query
          required: false
          schema:
            type: string
          description: The page number of the result set, starting from 0. Defaults to the first page (page 0).
        - name: page_size
          in: query
          required: false
          schema:
            type: string
          description: |-
            The number of results to be included in the response, ranging from 10 to 100. Defaults
            to page size of 10.
      responses:
        '200':
          description: Matching shipments.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/shipment-object'
  /shipments/{shipment_id}:
    get:
      tags:
        - shipments
      summary: Get shipment
      description: |-
        Return the latest shipment object, including the most up-to-date status and tracking
        information.


        The path parameter accepts either the Carriyo `shipment_id` or the merchant's
        `partner_shipment_reference`. The reference variant is useful when your own system only
        retained the value it originally supplied.
      operationId: get-shipment
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Returns the requested shipment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
        '404':
          description: Shipment not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-shipment-error-response'
              examples:
                '404':
                  value:
                    status: '404'
                    timestamp: '2020-12-07T13:50:11.853Z'
                    errors:
                      - 'No shipment found with the shipment id: KHNI57EYOAICSdf'
    patch:
      tags:
        - shipments
      summary: Update shipment
      description: |-
        Partially update an existing shipment. Allowed when the shipment is in `draft`, `error`,
        or `cancelled`; any other status returns 400. (Cancelled shipments are editable so you
        can correct them before reprocessing.)


        ### Merge rules

        - **Top-level fields you include are replaced wholesale.** For example, to change only the
          pickup postcode, you still pass the entire `pickup` object; any field you omit there
          is reset to its default. Plan your payload accordingly.
        - **Custom attributes are the exception** and merge key-by-key. You can add or change a
          single attribute without supplying the others. To remove an attribute, set its value
          to `null`.


        The path parameter accepts either the Carriyo `shipment_id` or the merchant's
        `partner_shipment_reference`.
      operationId: update-shipment-patch
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/shipment-request'
        required: true
      responses:
        '200':
          description: Shipment updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  status:
                    type: string
                    minLength: 1
                  timestamp:
                    type: string
                    minLength: 1
                  errors:
                    type: array
                    items:
                      type: string
                required:
                  - status
                  - timestamp
                  - errors
                x-examples:
                  example-1:
                    status: '400'
                    timestamp: '2022-04-07T13:37:09.855Z'
                    errors:
                      - Shipment L1OJMRKJEPTNB is not [draft, error, cancelled].
              examples:
                update-failed:
                  value:
                    status: '400'
                    timestamp: '2022-04-07T13:37:09.855Z'
                    errors:
                      - Shipment L1OJMRKJEPTNB is not [draft, error, cancelled].
      x-codegen-request-body-name: body
    put:
      tags:
        - shipments
      summary: Replace shipment
      description: |-
        Fully replace a draft shipment. The request body overwrites the existing shipment in its
        entirety: any field you omit is reset to the schema default, including nested objects
        like `pickup`, `dropoff`, `parcels`, and `items`. If you want to change only a few
        fields and leave the rest intact, use **Update shipment** (`PATCH`) instead.


        Only `draft` shipments can be replaced. Confirmed shipments return 400.


        The path parameter accepts either the Carriyo `shipment_id` or the merchant's
        `partner_shipment_reference`.
      operationId: update-shipment
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/shipment-request'
        required: true
      responses:
        '200':
          description: Shipment replaced.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  status:
                    type: string
                    minLength: 1
                  timestamp:
                    type: string
                    minLength: 1
                  errors:
                    type: array
                    items:
                      type: string
                required:
                  - status
                  - timestamp
                  - errors
                x-examples:
                  example-1:
                    status: '400'
                    timestamp: '2022-04-07T13:37:09.855Z'
                    errors:
                      - Shipment L1OJMRKJEPTNB is not [draft, error, cancelled].
              examples:
                update-failed:
                  value:
                    status: '400'
                    timestamp: '2022-04-07T13:37:09.855Z'
                    errors:
                      - Shipment L1OJMRKJEPTNB is not [draft, error, cancelled].
      x-codegen-request-body-name: body
  /shipments/{shipment_id}/confirm:
    post:
      tags:
        - shipments
      summary: Confirm shipment
      description: |-
        Book a `draft` shipment for the first time, or retry booking a shipment that's currently
        in `error` status.


        **Eligible statuses:** `draft`, `error`. For any other status that still allows
        re-booking (e.g. `booked`, `cancelled`, `returned`), use **Reprocess shipment**
        (`POST /shipments/{shipment_id}/reprocess`) instead.


        ### Optional updates

        The request body is optional. Supply it if you want to amend the shipment as part of
        confirming. Merge rules match **Update shipment** (`PATCH`):

        - Top-level fields you include are replaced wholesale; omitted fields reset to defaults.
        - Custom attributes are the exception and merge key-by-key. Pass `null` to remove one.


        ### Booking flow

        Carriyo moves the shipment to `pending`, assigns a carrier, and submits the booking
        request to that carrier. The API responds immediately with status `pending`, without
        waiting for the carrier's reply. If the carrier accepts, the status becomes `booked`
        and the tracking number is attached. If the carrier rejects, the status becomes `error`
        with the carrier's reason in `post_shipping_info.error_details`.


        Booking outcomes and label generation are delivered via webhooks, not in the response to
        this call.


        The path parameter accepts either the Carriyo `shipment_id` or the merchant's
        `partner_shipment_reference`.
      operationId: confirm-shipment
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/shipment-patch-request'
        required: false
      responses:
        '200':
          description: Shipment confirmed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  status:
                    type: string
                    minLength: 1
                  timestamp:
                    type: string
                    minLength: 1
                  errors:
                    type: array
                    items:
                      type: string
                required:
                  - status
                  - timestamp
                  - errors
                x-examples:
                  example-1:
                    status: '400'
                    timestamp: '2022-04-07T13:30:14.500Z'
                    errors:
                      - |-
                        You can only confirm shipments which are in Draft or Error. Current shipment
                        status: booked.
              examples:
                confirmation-failed:
                  value:
                    status: '400'
                    timestamp: '2022-04-07T13:30:14.500Z'
                    errors:
                      - |-
                        You can only confirm shipments which are in Draft or Error. Current shipment
                        status: booked.
      x-codegen-request-body-name: body
  /shipments/{shipment_id}/reprocess:
    post:
      tags:
        - shipments
      summary: Reprocess shipment
      description: |-
        Re-book a shipment that's no longer in `draft`. **Confirm shipment** only handles `draft`
        and `error`; this endpoint covers the wider list of statuses below. For `error`, either
        endpoint works.


        **Eligible statuses:** `booked`, `ready_to_ship`, `error`, `cancelled`,
        `cancelled_by_carrier`, `out_for_collection`, `failed_collection_attempt`,
        `ready_for_return`, `return_in_transit`, `returned`.


        Typical uses:

        - Retry after a transient carrier error.
        - Switch carrier or routing after the original carrier cancelled or rejected the booking.
        - Correct addresses, parcels, or other shipment data and re-submit.
        - Re-book during a return or reverse-logistics flow.


        ### Optional updates

        The request body is optional. Supply it to amend shipment data as part of reprocessing.
        Merge rules match **Update shipment** (`PATCH`):

        - Top-level fields you include are replaced wholesale; omitted fields reset to defaults.
        - Custom attributes are the exception and merge key-by-key. Pass `null` to remove one.


        ### Booking flow

        Carriyo moves the shipment to `pending`, re-assigns a carrier (or keeps the one specified
        in the body), and submits the booking request. The API responds immediately as `pending`,
        without waiting for the carrier. If the carrier accepts, status becomes `booked` with the
        tracking number attached; if rejected, status becomes `error` with details in
        `post_shipping_info.error_details`. Subsequent booking outcomes and label updates flow
        through webhooks.


        The path parameter accepts either the Carriyo `shipment_id` or the merchant's
        `partner_shipment_reference`.
      operationId: reprocess-shipment
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/shipment-patch-request'
        required: false
      responses:
        '200':
          description: Shipment reprocessed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  status:
                    type: string
                    minLength: 1
                  timestamp:
                    type: string
                    minLength: 1
                  errors:
                    type: array
                    items:
                      type: string
                required:
                  - status
                  - timestamp
                  - errors
                x-examples:
                  example-1:
                    status: error
                    timestamp: '2022-04-07T13:30:14.500Z'
                    errors:
                      - Current shipment status [delivered] does not allow it to be reprocessed.
              examples:
                reprocess-not-allowed:
                  value:
                    status: error
                    timestamp: '2022-04-07T13:30:14.500Z'
                    errors:
                      - Current shipment status [delivered] does not allow it to be reprocessed.
      x-codegen-request-body-name: body
  /shipments/{shipment_id}/ready-to-ship:
    post:
      tags:
        - shipments
      summary: Ready to ship
      description: |-
        Mark a shipment as ready to ship.


        For carriers that support scheduled collection (typically on-demand couriers), this also
        notifies the carrier of the scheduled collection date and time so they can arrange
        pickup.


        > **Use with care.** For carriers that operate pre-agreed line hauls or fixed daily
        > pickup routes, sending an ad-hoc ready-to-ship notification can interfere with the
        > carrier's own scheduling. Only call this endpoint for carriers and accounts configured
        > to expect it.


        The body is optional. Include it to update parcel information (weight, dimensions,
        count) at the same time, which is often when the final parcel details become known.


        The path parameter accepts either the Carriyo `shipment_id` or the merchant's
        `partner_shipment_reference`.
      operationId: ready-to-ship
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-parcels-request'
        required: false
      responses:
        '200':
          description: Shipment marked ready to ship.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
      x-codegen-request-body-name: body
  /shipments/{shipment_id}/cancel:
    post:
      tags:
        - shipments
      summary: Cancel shipment
      description: |-
        Cancel a shipment that has not yet shipped. Returns 400 if the shipment is already in
        transit or beyond.


        Where the carrier supports it, Carriyo also issues the cancellation against the carrier's
        booking; for carriers that don't support cancellation, the Carriyo record is cancelled
        but no carrier call is made. Either way, the resulting shipment object reflects the
        cancelled state.


        The body is optional. Include `update_reason_code` to record why; the value can be one of
        Carriyo's standard reason codes or a custom code configured for your merchant.


        The path parameter accepts either the Carriyo `shipment_id` or the merchant's
        `partner_shipment_reference`.
      operationId: cancel-shipment
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                update_reason_code:
                  type: string
                  description: |-
                    Any one of the standard reason codes (below) or custom reason codes defined by
                    the merchant.


                    [Click here for the list of Standard Reason
                    Codes](https://carriyo.com/docs/guides/shipment-reason-codes/)
        required: false
      responses:
        '200':
          description: Shipment cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  timestamp:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
                x-examples:
                  example-1:
                    status: error
                    timestamp: '2022-03-22T09:29:01.889Z'
                    errors:
                      - |-
                        Status change is not allowed from current status: 'shipped' to the new
                        status: 'cancelled'
              examples:
                cancellation-failed:
                  value:
                    status: error
                    timestamp: '2022-03-22T09:29:01.889Z'
                    errors:
                      - |-
                        Status change is not allowed from current status: 'shipped' to the new
                        status: 'cancelled'
      x-codegen-request-body-name: body
  /shipments/{shipment_id}/update-status:
    post:
      tags:
        - shipments
      summary: Update status
      description: |-
        Set the shipment status manually. Use this when:

        1. Recording a merchant-controlled status such as `shipped`, `delivery_confirmed`, or
           `return_confirmed`, which the carrier doesn't emit.
        2. Overriding an incorrect carrier status. For example, if the carrier reported
           `delivered` but the parcel actually came back to the warehouse, set the status to
           `returned`.
        3. Filling in a status the carrier failed to report. For example, if you know the
           parcel was delivered but no `delivered` event came through, set it manually here.


        ### Allowed transitions

        The full transition matrix below shows every `current → new_status` change permitted
        by the platform. Any transition not listed returns 400.

        | `new_status` | Allowed current status |
        |---|---|
        | `shipped` | `booked`, `cancelled_by_carrier`, `failed_collection_attempt`, `ready_to_ship`, `out_for_collection` |
        | `out_for_delivery` | `awaiting_customer_collection`, `delayed`, `failed_delivery_attempt`, `in_transit`, `missing`, `ready_for_return`, `return_in_transit`, `shipped`, `suspended` |
        | `delivered` | `awaiting_customer_collection`, `cancelled`, `delayed`, `delivery_confirmed`, `failed_delivery_attempt`, `in_transit`, `missing`, `out_for_delivery`, `ready_for_return`, `return_in_transit`, `returned`, `shipped`, `suspended` |
        | `delivery_confirmed` | `delivered` |
        | `return_in_transit` | `awaiting_customer_collection`, `delayed`, `failed_delivery_attempt`, `in_transit`, `missing`, `out_for_delivery`, `ready_for_return`, `shipped`, `suspended`, `out_for_collection` |
        | `returned` | `awaiting_customer_collection`, `cancelled`, `delayed`, `delivered`, `failed_delivery_attempt`, `in_transit`, `missing`, `out_for_delivery`, `ready_for_return`, `return_confirmed`, `return_in_transit`, `shipped`, `suspended` |
        | `return_confirmed` | `returned` |


        > Most integrations only ever set the merchant-controlled statuses (`shipped`,
        > `delivery_confirmed`, `return_confirmed`). The wider matrix exists for override and
        > correction scenarios.


        The path parameter accepts either the Carriyo `shipment_id` or the merchant's
        `partner_shipment_reference`.
      operationId: update-status
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                new_status:
                  type: string
                update_date:
                  type: string
        required: true
      responses:
        '200':
          description: Status updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  timestamp:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
                x-examples:
                  example-1:
                    status: error
                    timestamp: '2022-05-11T17:39:16.126Z'
                    errors:
                      - |-
                        Status change is not allowed from current status: 'delivered' to the new
                        status: 'delivered'
              examples:
                status-update-failed:
                  value:
                    status: error
                    timestamp: '2022-05-11T17:39:16.126Z'
                    errors:
                      - |-
                        Status change is not allowed from current status: 'delivered' to the new
                        status: 'delivered'
      x-codegen-request-body-name: body
  /shipments/{shipment_id}/label/refresh:
    post:
      tags:
        - shipments
      summary: Refresh label
      description: |-
        Re-request the default shipping label from the carrier when the label is missing on a
        booked shipment. Use this if the label URL is absent or returned a download error and
        you need Carriyo to fetch a fresh one.


        The path parameter accepts either the Carriyo `shipment_id` or the merchant's
        `partner_shipment_reference`.
      operationId: refresh-label
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Label refreshed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  awb:
                    type: string
  /shipments/{shipment_id}/commercial-invoice/refresh:
    post:
      tags:
        - shipments
      summary: Refresh commercial invoice
      description: |-
        Re-fetch or regenerate the commercial invoice for a cross-border shipment from the
        carrier.


        Use this when customs data was corrected after the original booking and you need the
        carrier to issue a new commercial invoice that reflects the corrected information.
        Typical triggers include:

        - Item descriptions or quantities updated post-booking.
        - HS code added or corrected.
        - A registration number (`VAT`, `IOSS`, `EOR`, etc.) added on the seller, importer, or
          exporter.
        - Incoterms changed mid-flight, for example flipping `DAP` to `DDP`.


        Carriyo asks the carrier for a refreshed invoice and replaces the existing
        `commercial_invoice` reference on the shipment with the new one. The previous invoice
        URL stops being valid once the refresh completes.


        Only meaningful for carriers that produce commercial invoices via API (DHL Express,
        FedEx, and similar). Carriers without invoice-refresh support return an error.
      operationId: refresh-commercial-invoice
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
          description: Carriyo shipment ID.
      responses:
        '200':
          description: Shipment with the refreshed `commercial_invoice` reference.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
  /shipments/{shipment_id}/estimate-shipping-cost:
    parameters:
      - schema:
          type: string
        name: shipment_id
        in: path
        required: true
    post:
      summary: Estimate shipping cost
      tags:
        - shipments
      operationId: estimate-shipping-cost-for-shipment
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Shipping cost estimated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
      description: |-
        Get a cost estimate for a draft shipment before booking it. The estimate is sourced from
        the configured costing profile or, where available, from the carrier's live rating API,
        and is attached to the returned shipment object.


        Useful for rate-shopping or for surfacing shipping cost on a checkout page before
        committing to the booking.


        The path parameter accepts either the Carriyo `shipment_id` or the merchant's
        `partner_shipment_reference`.
  /shipments/{shipment_id}/update-delivery-promise:
    post:
      summary: Update delivery promise
      tags:
        - shipments
      operationId: update-delivery-promise
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Delivery promise updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
      description: |-
        Update the promised delivery date displayed to the customer on the branded tracking page
        and used in your own SLA tracking. Allowed at any time until the shipment reaches a final
        status (`delivered`, `returned`, `cancelled`).


        This only updates the *promise* in Carriyo. It does not change the carrier's actual
        delivery commitment.


        The path parameter accepts either the Carriyo `shipment_id` or the merchant's
        `partner_shipment_reference`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/promised-delivery-date-request'
        required: true
  /shipments/{shipment_id}/update-delivery-schedule:
    parameters:
      - schema:
          type: string
        name: shipment_id
        in: path
        required: true
    post:
      summary: Update delivery schedule
      tags:
        - shipments
      operationId: update-delivery-schedule
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Delivery schedule updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
      description: |-
        Update the scheduled delivery date for a shipment. Allowed at any time until the shipment
        reaches a final status (`delivered`, `returned`, `cancelled`).


        > **Note:** most carriers don't accept schedule updates after the original booking, so
        this change is recorded in Carriyo (and reflected on the branded tracking page) but is
        **not** propagated to the carrier post-booking.


        Two shapes are supported:

        - **Time window**, using `scheduled_from` and `scheduled_to`:

            ```json
            { "delivery": { "scheduled_from": "2022-01-01T10:00:00.000Z", "scheduled_to": "2022-01-01T12:00:00.000Z" } }
            ```

        - **Whole day**, using just `scheduled_date`:

            ```json
            { "delivery": { "scheduled_date": "2022-01-01" } }
            ```


        The path parameter accepts either the Carriyo `shipment_id` or the merchant's
        `partner_shipment_reference`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/collection-request'
            examples:
              Delivery Slot:
                value:
                  scheduled_from: '2022-01-01T10:00:00.000Z'
                  scheduled_to: '2022-01-01T12:00:00.000Z'
              Delivery Day:
                value:
                  scheduled_date: '2022-01-01'
        required: true
  /shipments/{shipment_id}/update-collection-schedule:
    parameters:
      - schema:
          type: string
        name: shipment_id
        in: path
        required: true
    post:
      summary: Update collection schedule
      tags:
        - shipments
      operationId: update-collection-schedule
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Collection schedule updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
      description: |-
        Update the scheduled collection date for a shipment. Allowed at any time until the
        shipment reaches a final status (`delivered`, `returned`, `cancelled`).


        > **Note:** most carriers don't accept schedule updates after the original booking, so
        this change is recorded in Carriyo but is **not** propagated to the carrier
        post-booking.


        Two shapes are supported:

        - **Time window**, using `scheduled_from` and `scheduled_to`:

            ```json
            { "collection": { "scheduled_from": "2022-01-01T10:00:00.000Z", "scheduled_to": "2022-01-01T12:00:00.000Z" } }
            ```

        - **Whole day**, using just `scheduled_date`:

            ```json
            { "collection": { "scheduled_date": "2022-01-01" } }
            ```


        The path parameter accepts either the Carriyo `shipment_id` or the merchant's
        `partner_shipment_reference`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/collection-request'
            examples:
              Collection Slot:
                value:
                  scheduled_from: '2022-01-01T10:00:00.000Z'
                  scheduled_to: '2022-01-01T12:00:00.000Z'
              Collection Day:
                value:
                  scheduled_date: '2022-01-01'
        required: true
  /shipments/{shipment_id}/parcels:
    put:
      tags:
        - shipments
      summary: Update parcels
      description: |-
        Replace the parcel list on a shipment after it's been created. Use this when the
        original parcel data (weight, dimensions, count) was wrong, or when the final parcel
        details only become known after picking and packing.


        The request body is optional; if omitted, the parcel list is unchanged. If supplied, it
        fully replaces the existing parcels.


        The path parameter accepts either the Carriyo `shipment_id` or the merchant's
        `partner_shipment_reference`.
      operationId: update-parcels
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-parcels-request'
        required: false
      responses:
        '200':
          description: Parcels updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
      x-codegen-request-body-name: body
  /shipments/{shipment_id}/custom-attributes:
    patch:
      tags:
        - shipments
      summary: Update custom attributes
      description: |-
        Update the tenant-defined custom attribute values on an existing shipment, without
        touching the rest of the shipment data.


        Use this when your tenant has configured custom attributes (for example an SAP order
        number, a 3PL pick-batch reference, or a warehouse zone code) and you want to set or
        replace those values on an already-created shipment.


        A common scenario is when an upstream system becomes aware of metadata after the shipment
        has been created. For example, a WMS may assign a pick-batch ID once items are picked, or
        an ERP may issue a tax document number after the fact. Rather than re-sending the entire
        shipment via `PUT /shipments/{shipment_id}`, you can patch just the attributes that
        changed.


        Only attributes registered for your tenant via the Attributes
        API are accepted. Unknown attribute names return a
        `custom_attribute_invalid` error.
      operationId: update-shipment-custom-attributes
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
          description: Carriyo shipment ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - custom_attributes
              properties:
                custom_attributes:
                  type: object
                  description: |-
                    Map of attribute name → value. Both string and numeric values are accepted,
                    depending on how the attribute was registered.
                  additionalProperties: true
                  example:
                    sap_order_number: SAP-2026-00482
                    pick_batch_id: BATCH-0331-A
      responses:
        '200':
          description: Updated shipment with the new attribute values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
  /shipments/{shipment_id}/documents:
    post:
      tags:
        - shipments
      summary: Upload document
      description: |-
        Attach a document to a shipment, such as a commercial invoice, packing list, or
        certificate. The document is stored against the shipment in Carriyo and, when the
        carrier-upload prerequisites are met, also pushed to the carrier asynchronously.


        ### Request

        Identify the target document setting by either `document_id` or `document_name`; one
        is required. When both are supplied, `document_id` takes precedence. `content_base64`
        is required and must be a valid PDF (the only currently supported format).


        ### Validation

        The request is rejected with `400` when:

        - No document setting in your tenant matches the supplied `document_id` or
          `document_name`.
        - A document for the same setting is already attached to the shipment. To replace
          existing content, use **Update document** or **Bulk upload documents**, which upserts.


        ### Carrier sync

        After Carriyo stores the document, it is pushed to the carrier asynchronously only when
        all of the following are true:

        - The document setting is configured to be uploaded to the carrier.
        - A carrier account is assigned to the shipment.
        - The shipment has progressed past the pre-booking statuses (i.e. its status is not
          `draft`, `pending`, or `error`).
        - The assigned carrier supports document upload. Today, that's **DHL**, **FedEx**, and
          **UPS**.
        - The carrier account has a document-type mapping configured for the matched document
          setting.


        If any of those conditions is not met, the document is still stored in Carriyo and the
        carrier upload simply does not run. You can call **Retry document upload** later once
        the missing condition is in place.


        Sync runs asynchronously. The `carrier_upload_status` field on the document reflects
        progress: `pending` while in flight, `complete` once the carrier accepts it, or
        `error` if the carrier rejects it (the document's `message` field then carries the
        carrier's reason).


        The path parameter accepts either the Carriyo `shipment_id` or the merchant's
        `partner_shipment_reference`.
      operationId: upload-document
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
          description: The Carriyo shipment ID or the merchant provided `partner_shipment_reference`.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/document-upload-request'
            examples:
              upload-by-document-id:
                summary: Upload using document ID
                value:
                  document_id: DOC123
                  content_base64: |-
                    JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFI+PgplbmRvYmoKMiAwIG9iago...
              upload-by-document-name:
                summary: Upload using document name
                value:
                  document_name: Commercial Invoice
                  content_base64: |-
                    JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFI+PgplbmRvYmoKMiAwIG9iago...
        required: true
      responses:
        '200':
          description: Document uploaded successfully. Returns the updated shipment object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
        '400':
          description: |-
            Bad Request - Document settings not found, document already exists, or validation
            failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-shipment-error-response'
              examples:
                document-settings-not-found:
                  value:
                    status: '400'
                    timestamp: '2024-01-15T10:30:00.000Z'
                    errors:
                      - Not able to find a valid document settings.
                document-already-exists:
                  value:
                    status: '400'
                    timestamp: '2024-01-15T10:30:00.000Z'
                    errors:
                      - This document is already present in the shipment
                missing-required-fields:
                  value:
                    status: '400'
                    timestamp: '2024-01-15T10:30:00.000Z'
                    errors:
                      - Either document_id or document_name is required
                missing-content:
                  value:
                    status: '400'
                    timestamp: '2024-01-15T10:30:00.000Z'
                    errors:
                      - content_base64 is required
        '404':
          description: Shipment not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-shipment-error-response'
              examples:
                '404':
                  value:
                    status: '404'
                    timestamp: '2024-01-15T10:30:00.000Z'
                    errors:
                      - 'No shipment found with the shipment id: KHNI57EYOAICSdf'
      x-codegen-request-body-name: body
  /shipments/{shipment_id}/documents/{document_identifier}:
    put:
      tags:
        - shipments
      summary: Update document
      description: |-
        Replace the content of a document that already exists on a shipment. Useful when a
        commercial invoice, packing list, or certificate has been amended after upload.


        ### Identifying the document

        The `document_identifier` path parameter accepts either:

        - The document's `document_id`.
        - The document's `name`. URL-encode it if it contains special characters or spaces.


        ### Behaviour

        - The document must already exist on the shipment; otherwise the call returns 400.
        - Content is supplied as a Base64-encoded string. Only PDF is supported, and the
          content is security-validated against the declared format.
        - The new content fully replaces the existing content in storage; the previous version
          is not retained.


        ### Carrier sync

        The same carrier-upload prerequisites as **Upload document** apply: the document
        setting is configured for carrier upload, a carrier account is assigned, the shipment
        is past the pre-booking statuses, the carrier supports document upload, and the
        carrier account has a document-type mapping for the matched setting. When all are met,
        the updated content is re-pushed to the carrier asynchronously.


        The path parameter accepts either the Carriyo `shipment_id` or the merchant's
        `partner_shipment_reference`.
      operationId: update-document
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
          description: The Carriyo shipment ID or the merchant provided `partner_shipment_reference`.
        - name: document_identifier
          in: path
          required: true
          schema:
            type: string
          description: The document ID or document name (URL-encoded) to identify the document to update.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/document-update-request'
            examples:
              update-document:
                summary: Update document content
                value:
                  content_base64: |-
                    JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2cvUGFnZXMgMiAwIFI+PgplbmRvYmoKMiAwIG9iago...
        required: true
      responses:
        '200':
          description: Document updated successfully. Returns the updated shipment object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
        '400':
          description: Bad Request - Document not found or validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-shipment-error-response'
              examples:
                no-documents:
                  value:
                    status: '400'
                    timestamp: '2024-01-15T10:30:00.000Z'
                    errors:
                      - No documents found in shipment
                document-not-found:
                  value:
                    status: '400'
                    timestamp: '2024-01-15T10:30:00.000Z'
                    errors:
                      - 'Document not found: Commercial Invoice'
                missing-content:
                  value:
                    status: '400'
                    timestamp: '2024-01-15T10:30:00.000Z'
                    errors:
                      - content_base64 is required
        '404':
          description: Shipment not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-shipment-error-response'
      x-codegen-request-body-name: body
    delete:
      tags:
        - shipments
      summary: Delete document
      description: |-
        Remove a document from a shipment.


        ### Identifying the document

        The `document_identifier` path parameter accepts either:

        - The document's `document_id`.
        - The document's `name`. URL-encode it if it contains special characters or spaces.


        ### Behaviour

        - The document must exist on the shipment; otherwise the call returns 400.
        - The content is deleted from Carriyo storage (S3). This operation cannot be undone.
        - If the document was already uploaded to a carrier, deleting it from Carriyo does **not**
          remove it from the carrier's system.


        The path parameter accepts either the Carriyo `shipment_id` or the merchant's
        `partner_shipment_reference`.
      operationId: delete-document
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
          description: The Carriyo shipment ID or the merchant provided `partner_shipment_reference`.
        - name: document_identifier
          in: path
          required: true
          schema:
            type: string
          description: The document ID or document name (URL-encoded) to identify the document to delete.
      responses:
        '200':
          description: Document deleted successfully. Returns the updated shipment object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
        '400':
          description: Bad Request - Document not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-shipment-error-response'
              examples:
                no-documents:
                  value:
                    status: '400'
                    timestamp: '2024-01-15T10:30:00.000Z'
                    errors:
                      - No documents found in shipment
                document-not-found:
                  value:
                    status: '400'
                    timestamp: '2024-01-15T10:30:00.000Z'
                    errors:
                      - 'Document not found: DOC123'
        '404':
          description: Shipment not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-shipment-error-response'
  /shipments/{shipment_id}/documents/{document_identifier}/retry:
    post:
      tags:
        - shipments
      summary: Retry document upload to carrier
      description: |-
        Re-attempt the upload of an existing document to the carrier after a previous carrier
        upload failed.


        ### Identifying the document

        The `document_identifier` path parameter accepts either:

        - The document's `document_id`.
        - The document's `name`. URL-encode it if it contains special characters or spaces.


        ### Prerequisites

        All of the following must hold; any missing one returns 400 with the specific reason:

        - A carrier account is assigned to the shipment.
        - The document exists on the shipment.
        - The document has a stored URL (i.e. it was previously uploaded successfully to
          Carriyo).
        - The assigned carrier supports document upload. Today, that's **DHL**, **FedEx**, and
          **UPS**.
        - The carrier account has a document-type mapping configured for this document.


        ### Behaviour

        The retry runs asynchronously. The document's `carrier_upload_status` is set to
        `pending` immediately, then transitions to `complete` or `error` once the carrier
        processes the upload. Watch the shipment via webhooks or polling to observe the
        final state.


        The path parameter accepts either the Carriyo `shipment_id` or the merchant's
        `partner_shipment_reference`.
      operationId: retry-document-upload
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
          description: The Carriyo shipment ID or the merchant provided `partner_shipment_reference`.
        - name: document_identifier
          in: path
          required: true
          schema:
            type: string
          description: The document ID or document name (URL-encoded) to identify the document.
      responses:
        '200':
          description: |-
            Document upload retry initiated successfully. Returns the updated shipment object with
            `carrier_upload_status` set to `pending`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
        '400':
          description: Bad Request - Prerequisites not met.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-shipment-error-response'
              examples:
                no-carrier:
                  value:
                    status: '400'
                    timestamp: '2024-01-15T10:30:00.000Z'
                    errors:
                      - Please assign a carrier first
                no-documents:
                  value:
                    status: '400'
                    timestamp: '2024-01-15T10:30:00.000Z'
                    errors:
                      - No documents found in shipment
                document-not-found:
                  value:
                    status: '400'
                    timestamp: '2024-01-15T10:30:00.000Z'
                    errors:
                      - 'Document not found: DOC123'
                no-url:
                  value:
                    status: '400'
                    timestamp: '2024-01-15T10:30:00.000Z'
                    errors:
                      - Document has no URL to upload
                carrier-not-supported:
                  value:
                    status: '400'
                    timestamp: '2024-01-15T10:30:00.000Z'
                    errors:
                      - Carrier does not support document upload
        '404':
          description: Shipment not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-shipment-error-response'
  /shipments/{shipment_id}/documents/bulk:
    post:
      tags:
        - shipments
      summary: Bulk upload documents
      description: |-
        Upload or update multiple documents on a shipment in a single request. Unlike single
        **Upload document**, which rejects duplicates, this endpoint upserts: existing
        documents are replaced and missing ones are created.


        ### How it works

        Each entry in the array is validated individually, then processed. For each entry, if a
        document for that setting already exists on the shipment, its content is replaced.
        Otherwise a new document is created. After all entries are persisted in one save,
        carrier sync is triggered per document following the same rules as **Upload document**.


        ### Prerequisites

        A document setting must exist for every entry in the request, matched by `document_id`
        or `document_name`. If any entry fails to match, the entire request is rejected with
        400; there is no partial success. `content_base64` is required on each entry, and is
        validated against the matching document setting's format (currently PDF only).


        ### Carrier sync

        Per-document carrier sync is asynchronous and follows the same prerequisites as
        **Upload document**. Track each document's `carrier_upload_status` to observe progress.
      operationId: bulk-upload-documents
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
          description: The Carriyo shipment ID or the merchant provided `partner_shipment_reference`.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/document-upload-request'
            examples:
              bulk-upload:
                summary: Upload multiple documents
                value:
                  - document_id: DOC123
                    content_base64: JVBERi0xLjQKJeLjz9MKMSAwIG9iago...
                  - document_name: Commercial Invoice
                    content_base64: JVBERi0xLjQKJeLjz9MKMSAwIG9iago...
        required: true
      responses:
        '200':
          description: Documents uploaded or updated successfully. Returns the updated shipment object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
        '400':
          description: Bad Request - Document settings not found or validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-shipment-error-response'
        '404':
          description: Shipment not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-shipment-error-response'
      x-codegen-request-body-name: body
  /shipments/{shipment_id}/live-tracking:
    get:
      tags:
        - shipments
      summary: Get live tracking
      description: |-
        Fetch real-time driver location and ETA for a shipment that is currently being collected
        or delivered. Designed for same-day, hyper-local carriers whose drivers move continuously
        through the day; the response is a snapshot of where the driver is right now, not a list
        of past events.


        ### Carrier support

        Only supported by carriers whose handlers integrate with the carrier's live driver-tracking
        API. Today that means **Careem Express** and **Quiqup**. Calling this endpoint on a
        shipment whose carrier doesn't support live tracking returns an error.


        ### Status requirements

        The shipment must be in a live-trackable status: `out_for_collection` or `out_for_delivery`.
        Calling on a shipment in any other status returns `400` with
        `"Shipment is not in a live trackable status."`.


        ### Caching

        Results are cached for 15 seconds per (carrier account, shipment) to protect the
        carrier's API. Repeated calls within that window return the cached payload.
      operationId: live-track-shipment
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
          description: Carriyo shipment ID.
      responses:
        '200':
          description: Driver location and ETA for the in-flight shipment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/live-tracking-info'
        '400':
          description: |-
            Returned when the shipment is not in a live-trackable status (`out_for_collection`,
            `out_for_delivery`), or when the assigned carrier doesn't support live tracking.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-shipment-error-response'
  /shipments/{shipment_id}/redact:
    post:
      tags:
        - shipments
      summary: Redact shipment PII
      description: |-
        Permanently remove personally identifiable information (PII) from a shipment, for privacy
        and data-protection compliance.


        Use this when a customer exercises a right of erasure under GDPR, CCPA, or similar
        regulation, or when your data retention policy reaches its scrub window. Call the
        endpoint on each affected shipment.


        After redaction:

        - Contact fields are cleared: `contact_name`, `contact_phone`, `contact_email`,
          `address1`, `address2`, `coords`, and customer-supplied notes.
        - Operational fields are kept: status, tracking number, carrier, dates, weights, and
          dimensions.
        - The shipment remains usable for analytics, audit, and tracking statistics, but the
          recipient can no longer be identified from it.


        **This action is irreversible.** The original PII cannot be recovered. Webhooks that
        fired before the redaction are not retroactively scrubbed, so you remain responsible
        for redacting any copies of shipment data held in your own systems.
      operationId: redact-shipment
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
          description: Carriyo shipment ID.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: |-
                    Free-text reason captured in the audit log (e.g. "GDPR Article 17 request,
                    ticket #4421").
      responses:
        '200':
          description: Shipment object with PII fields cleared.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
  /manifests:
    post:
      tags:
        - manifests
      summary: Create manifest
      operationId: create-manifest
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/manifest-request'
        required: false
      responses:
        '201':
          description: Manifest created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/manifest-response'
      x-codegen-request-body-name: body
      description: Creates a new manifest. The request body lists the shipments to include and the planned pickup details (location, schedule, and carrier).
    get:
      tags:
        - manifests
      summary: List manifests
      operationId: list-manifests
      responses:
        '200':
          description: Matching manifests.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/manifest-response'
      description: Returns the merchant's manifests, with optional filters for status, date range, and carrier.
  /manifests/{manifest-id}:
    patch:
      tags:
        - manifests
      summary: Update manifest
      operationId: update-manifest
      description: |-
        Update a draft manifest. Once a manifest has been moved to ready-to-ship or shipped,
        it can no longer be edited.
      parameters:
        - name: manifest-id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/manifest-request'
        required: true
      responses:
        '200':
          description: Manifest updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/manifest-response'
      x-codegen-request-body-name: body
    get:
      tags:
        - manifests
      summary: Get manifest
      operationId: get-manifest
      parameters:
        - name: manifest-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Returns the requested manifest.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/manifest-response'
      description: Returns the specified manifest by ID, including its list of shipments and current status.
    delete:
      tags:
        - manifests
      summary: Delete manifest
      operationId: delete-manifest
      parameters:
        - name: manifest-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Manifest deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/manifest-response'
      description: Permanently deletes the specified manifest. Only allowed while the manifest is in a non-shipped status.
  /manifests/{manifest-id}/ready-to-ship:
    post:
      tags:
        - manifests
      summary: Mark manifest ready to ship
      operationId: ready-to-ship-manifest
      description: |-
        Lock the contents of a draft manifest. After this call, no more shipments can be added
        or removed. The manifest must be in draft when called. Once locked, ship the manifest
        with `POST /manifests/{manifest-id}/ship` to dispatch it to the carrier.
      parameters:
        - name: manifest-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Manifest marked ready to ship.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/manifest-response'
  /manifests/{manifest-id}/cancel:
    post:
      tags:
        - manifests
      summary: Cancel manifest
      operationId: cancel-manifest
      parameters:
        - name: manifest-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Manifest cancellation requested.
          content:
            application/json:
              schema:
                type: object
      description: Cancel the manifest. The constituent shipments are not cancelled; they are released from the manifest and can be added to another one.
  /manifests/{manifest-id}/retry:
    post:
      tags:
        - manifests
      summary: Retry manifest
      operationId: retry-manifest
      parameters:
        - name: manifest-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Manifest retry triggered.
          content:
            application/json:
              schema:
                type: object
      description: Retries a manifest that failed at the carrier. Used when the carrier rejected the initial manifest submission and a transient cause has been resolved.
  /manifests/{manifest-id}/ship:
    post:
      tags:
        - manifests
      summary: Ship manifest
      operationId: ship-manifest
      parameters:
        - name: manifest-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Manifest ship request submitted to the carrier.
          content:
            application/json:
              schema:
                type: object
      description: Marks the manifest as shipped and submits it to the carrier. Triggers carrier-side processing and finalises the pickup arrangement.
  /shipments/{shipment_id}/add-child-shipments:
    post:
      tags:
        - consolidated-shipments
      summary: Link child shipments
      description: |-
        Adds one or more existing shipments as children of a consolidated (master) shipment. The
        parent must already be marked as consolidated. Children must be in `draft` or `error` status
        and not already linked to another consolidated parent. Linked children inherit certain
        routing and lifecycle behaviour from the parent.
      operationId: add-child-shipments
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
          description: Identifier of the consolidated parent shipment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - child_shipment_ids
              properties:
                child_shipment_ids:
                  type: array
                  description: Carriyo shipment IDs to link as children.
                  items:
                    type: string
      responses:
        '200':
          description: Updated consolidated parent shipment, including the new child references.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
  /shipments/{shipment_id}/remove-child-shipments:
    post:
      tags:
        - consolidated-shipments
      summary: Unlink child shipments
      description: |-
        Remove one or more child shipments from a consolidated parent. The unlinked children become
        independent shipments again; they are not deleted, just disassociated from the parent.
      operationId: remove-child-shipments
      parameters:
        - name: shipment_id
          in: path
          required: true
          schema:
            type: string
          description: Identifier of the consolidated parent shipment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - child_shipment_ids
              properties:
                child_shipment_ids:
                  type: array
                  description: Carriyo shipment IDs to unlink.
                  items:
                    type: string
      responses:
        '200':
          description: Updated consolidated parent shipment, with the listed children removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-object'
  /shipments/bulk/status:
    get:
      tags:
        - bulk-operations
      summary: Get bulk status
      description: |-
        This endpoint is designed to provide user with the statuses of requested shipments.
        Parameter `shipment_id` can be specified multiple times. The result of this operation is the
        list of shipments' current statuses and all milestones.
      operationId: get-bulk-status
      parameters:
        - name: shipment_id
          in: query
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Status of a bulk operation.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/bulk-shipment-status-response'
  /shipments/bulk/import:
    post:
      tags:
        - bulk-operations
      summary: Bulk import shipments
      description: |-
        Asynchronously creates a batch of shipments from a single request. Optionally confirms
        (books with the carrier) every shipment in the batch via the `confirm` query parameter;
        otherwise shipments are created in the same state as a single `POST /shipments` would
        produce. Subject to per-tenant batch size limits.
      operationId: bulk-import-shipments
      parameters:
        - name: confirm
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: If `true`, every imported shipment is auto-confirmed (booked with the carrier).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - shipments
              properties:
                shipments:
                  type: array
                  description: |-
                    Shipment requests to create. Each follows the same shape as the body of `POST
                    /shipments`.
                  items:
                    $ref: '#/components/schemas/shipment-request'
      responses:
        '202':
          description: Batch accepted for asynchronous processing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  bulk_id:
                    type: string
                    description: |-
                      Identifier for the batch. Use it to query status via `GET
                      /shipments/bulk/status`.
                  total:
                    type: integer
                    description: Number of shipments accepted into the batch.
  /shipments/bulk/validate:
    post:
      tags:
        - bulk-operations
      summary: Validate shipment batch
      description: |-
        Pre-validate a batch of shipment payloads without creating them. Applies the same
        request-time validations as `POST /shipments` (required fields, schema shape, and
        duplicate `partner_shipment_reference` detection across the batch) and returns
        per-shipment validation errors so you can fix issues before calling `POST
        /shipments/bulk/import`.


        Deferred validations (the kind that would set a created shipment's status to `error`
        rather than reject the request outright) are not surfaced here.
      operationId: bulk-validate-shipments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - shipments
              properties:
                shipments:
                  type: array
                  description: Shipment requests to validate.
                  items:
                    $ref: '#/components/schemas/shipment-request'
      responses:
        '200':
          description: Per-shipment validation results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    description: One result per input shipment, in the same order as the request.
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                          description: Position in the input list.
                        valid:
                          type: boolean
                        errors:
                          type: array
                          description: Validation errors when `valid` is false.
                          items:
                            $ref: '#/components/schemas/error-detail'
  /shipments/bulk/reprocess:
    post:
      tags:
        - bulk-operations
      summary: Reprocess shipment batch
      description: |-
        Asynchronously retries booking for a list of shipment IDs. Useful when many shipments
        errored due to a transient carrier issue and need to be rebooked together.
      operationId: bulk-reprocess-shipments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - shipment_ids
              properties:
                shipment_ids:
                  type: array
                  items:
                    type: string
                  description: Carriyo shipment IDs to reprocess.
      responses:
        '202':
          description: Batch accepted for asynchronous reprocessing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  bulk_id:
                    type: string
                  total:
                    type: integer
  /shipments/bulk/status/refresh:
    post:
      tags:
        - bulk-operations
      summary: Refresh status batch
      description: |-
        Triggers a carrier status refresh for a list of shipments. The latest carrier-reported
        status is fetched and persisted; webhook events fire on any state change. Subject to
        per-tenant batch size limits.
      operationId: bulk-refresh-status
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - shipment_ids
              properties:
                shipment_ids:
                  type: array
                  items:
                    type: string
                  description: Carriyo shipment IDs to refresh.
      responses:
        '202':
          description: Refresh batch accepted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
components:
  schemas:
    live-tracking-info:
      title: Live Tracking Info
      type: object
      description: Driver location, contact details, and ETA for a shipment currently being collected or delivered. Returned by **Get live tracking** for supported carriers.
      properties:
        driver_location:
          type: object
          description: Current geographic position of the driver, as reported by the carrier.
          properties:
            latitude:
              type: number
              format: double
              example: 25.2048
            longitude:
              type: number
              format: double
              example: 55.2708
        driver_name:
          type: string
          description: Driver's name, where the carrier exposes it.
          example: Jane Doe
        driver_phone:
          type: string
          description: Driver's contact phone, where the carrier exposes it.
          example: '+971501234567'
        estimated_time:
          type: string
          format: date-time
          description: Carrier-reported estimated arrival time for the next stop.
    bulk-shipment-status-response:
      title: Bulk Shipment Status Response
      type: object
      properties:
        shipmentId:
          type: string
        status:
          $ref: '#/components/schemas/carriyo-response-status'
        milestones:
          type: array
          description: The list of all shipment statuses
          items:
            type: object
            properties:
              status:
                $ref: '#/components/schemas/carriyo-response-status'
              date:
                type: string
    carrier-account-request:
      title: Carrier Account Request
      type: object
      description: |-
        Carrier account chosen for the shipment. Should contain either the carrier account id or
        carrier account name. Carrier account id takes precedence if both fields are passed.
      properties:
        carrier_id:
          type: string
          description: The ID of the carrier account assigned to the shipment
        carrier_account_name:
          type: string
          description: The name of the carrier account assigned to the shipment
    carrier-account-object:
      title: Carrier Account Object
      type: object
      description: Carrier account chosen for the shipment.
      properties:
        carrier:
          type: string
          description: The actual carrier based on the carrier account assigned to the shipment
          example: DHL
        carrier_account_name:
          type: string
          description: The name of the carrier account assigned to the shipment
          example: My DHL Account
        carrier_id:
          type: string
          description: The id of the carrier account assigned to the shipment
          example: act_1261YQIU2eTuokipwqbNBV
    carriyo-response-status:
      title: Carriyo Response Status
      type: string
      enum:
        - pending
        - error
        - booked
        - ready_to_ship
        - shipped
        - out_for_delivery
        - delivered
        - cancelled
        - cancelled_by_carrier
        - failed_collection_attempt
        - in_transit
        - awaiting_customer_collection
        - delivery_confirmed
        - failed_delivery_attempt
        - ready_for_return
        - return_in_transit
        - returned
        - return_confirmed
        - suspended
        - missing
        - delayed
    collection-request:
      title: Collection Request
      type: object
      description: |-
        Collection details chosen for the shipment, such as scheduled collection date.


        It can be set using one of the following options


        Option 1: Provide the `scheduled_from` and `scheduled_to` to choose the scheduled date along
        with start and end time.


        Example:

        "collection": {
          "scheduled_from": "2022-01-01'T'10:00:00.000+1:00",
          "scheduled_to": "2022-01-01'T'12:00:00.000+1:00"
        }


        Option 2: Provide the `scheduled_date` only to choose the entire day.


        Example:

        "collection": {
          "scheduled_date": "2022-01-01"
        }
      properties:
        scheduled_date:
          type: string
          description: |-
            Scheduled date for delivery provided by the merchant, represented using only the date
            part of the ISO 8601 format.
          format: date
          example: '2022-01-01'
        scheduled_from:
          type: string
          description: |-
            Start datetime for delivery provided by the merchant, represented using both the date
            and time the ISO 8601 format.
          format: date-time
          example: 2022-01-01T10:00:000Z
        scheduled_to:
          type: string
          description: |-
            End datetime for delivery provided by the merchant, represented using both the date and
            time the ISO 8601 format.
          format: date-time
          example: 2022-01-01T12:00:000Z
    collection-object:
      title: Collection Object
      type: object
      description: Collection details chosen for the shipment, such as scheduled collection date.
      properties:
        scheduled_date:
          type: string
          description: |-
            Scheduled date for collection provided by the merchant, represented using only the date
            part of the ISO 8601 format.
          format: date
          example: '2022-01-01'
        scheduled_from:
          type: string
          description: |-
            Start datetime for collection provided by the merchant, represented using both the date
            and time the ISO 8601 format.
          format: date-time
          example: 2022-01-01T10:00:000Z
        scheduled_to:
          type: string
          description: |-
            End datetime for collection provided by the merchant, represented using both the date
            and time the ISO 8601 format.
          format: date-time
          example: 2022-01-01T12:00:000Z
    create-shipment-error-response:
      title: Create Shipment Error Response
      type: object
      description: The error response returned when a shipment creation request is rejected by Carriyo
      properties:
        status:
          type: string
          description: The error status
          example: error
        timestamp:
          type: string
          description: |-
            date in format:
            <code>yyyy-MM-dd'T'HH:mm:ss.SSSXXX</code>
        errors:
          type: array
          description: Array of validation errors
          items:
            type: string
    custom-attributes:
      title: Custom Attributes
      type: object
      additionalProperties:
        type: array
        items:
          type: string
      description: |-
        Custom attributes in the form of a map:
        ```
        {"attribute1" : ["value1", "value2"], "attribute2" : ["value1", "value2"]}
        ```
        Please Note: You can only use custom attributes if you are subscribed to this feature.
    custom-fields:
      title: Custom Fields
      type: object
      additionalProperties:
        type: array
        items:
          type: string
      description: |-
        Custom address fields in the form of a map:
        ```
        {"field1" : ["value1", "value2"], "field2" : ["value1", "value2"]}
        ```
    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
    registration-numbers:
      title: Registration Numbers
      type: array
      items:
        $ref: '#/components/schemas/registration-number'
    registration-number:
      title: Registration Number
      type: object
      description: Registration number associated with the entity.
      properties:
        type_code:
          type: string
          enum:
            - VAT
            - EIN
            - GST
            - SSN
            - EOR
            - DUN
            - FED
            - STA
            - CNP
            - IE
            - INN
            - KPP
            - OGR
            - OKP
            - SDT
            - IOSS
            - PAN
          description: Type of registration number
        value:
          type: string
          description: The actual value of the registration number corresponding to the selected type
        issuer_country_code:
          type: string
          description: Two-letter country code (ISO 3166-1 alpha-2).
    delivery-request:
      title: Delivery
      type: object
      properties:
        delivery_type:
          type: string
          description: Pass one of the delivery types you have predefined in Carriyo
        scheduled_from:
          type: string
          description: Pass the start date-time
          format: date-time
        scheduled_to:
          type: string
          description: Pass the end date-time
          format: date-time
        scheduled_date:
          type: string
          description: Pass the Scheduled Date to select an entire day
          format: date
      description: |-
        The delivery options chosen for the shipment, including the delivery type and schedule.


        It can be set using one of the following options


        Option 1: Provide the `scheduled_from` and `scheduled_to` to choose the scheduled date along
        with start and end time.


        Example:

        "delivery": {
          "delivery_type": "STANDARD",
          "scheduled_from": "2022-01-01'T'10:00:00.000+1:00",
          "scheduled_to": "2022-01-01'T'12:00:00.000+1:00"
        }


        Option 2: Provide the `scheduled_date` only to choose the entire day.


        Example:

        "delivery": {
          "delivery_type": "STANDARD",
          "scheduled_date": "2022-01-01"
        }
    delivery-object:
      title: Delivery Object
      type: object
      description: |-
        Delivery details chosen for the shipment, such as chosen delivery type and scheduled
        delivery date.
      properties:
        delivery_type:
          type: string
          description: |-
            The type of the delivery. The possible values can be one of the delivery types
            predefined by the merchant.
        scheduled_date:
          type: string
          description: |-
            Scheduled date for delivery provided by the merchant, represented using only the date
            part of the ISO 8601 format.
          format: date
          example: '2022-01-01'
        scheduled_from:
          type: string
          description: |-
            Start datetime for delivery provided by the merchant, represented using both the date
            and time the ISO 8601 format.
          format: date-time
          example: 2022-01-01T10:00:000Z
        scheduled_to:
          type: string
          description: |-
            End datetime for delivery provided by the merchant, represented using both the date and
            time the ISO 8601 format.
          format: date-time
          example: 2022-01-01T12:00:000Z
    dimension:
      title: Dimension
      type: object
      properties:
        width:
          type: number
        height:
          type: number
        depth:
          type: number
        unit:
          type: string
          enum:
            - cm
          description: Default dimension unit is `cm` if not provided.
    error-detail:
      title: Error Detail
      type: object
      properties:
        level:
          type: string
          description: 'Possible Values: ERROR, WARNING'
        code:
          type: string
          description: |-
            Possible Values:

            required_data_missing, required_data_invalid, merchant_missing,
            default_merchant_not_configured, phone_number_invalid, email_invalid, email_missing,
            coordinates_invalid, coordinates_latitude_invalid, coordinates_longitude_invalid,
            carrier_account_invalid, no_carrier_assigned, partner_location_invalid,
            time_slot_invalid, status_change_not_allowed, custom_attribute_invalid,
            custom_attribute_value_invalid, parcel_item_invalid, payment_method_invalid,
            payment_currency_invalid, country_invalid, postcode_missing,
            item_origin_country_missing, item_hscode_missing, item_weight_missing,
            parcel_info_missing, parcel_weight_missing, parcel_dimensions_missing,
            label_format_invalid, weight_unit_invalid, dimension_unit_invalid,
            address_field_not_found, template_parsing_failed
        field:
          type: string
        message:
          type: string
        source:
          type: string
          description: 'Possible Values: CARRIYO, CARRIER'
        trigger:
          type: string
          description: 'Possible Values: BOOKING, CANCELLATION, TRACKING, SCHEDULING'
        type:
          type: string
          description: 'Possible Values: VALIDATION, TECHNICAL, UNKNOWN'
    document-object:
      title: Document
      type: object
      description: |-
        Represents a document attached to a shipment, such as a commercial invoice, packing list, or
        certificate.
      properties:
        document_id:
          type: string
          description: The unique identifier of the document setting that this document was created from.
        name:
          type: string
          description: The name of the document (e.g., "Commercial Invoice", "Packing List").
        type:
          type: string
          description: |-
            The type/category of the document.

            Possible Values:

            commercial_invoice, packing_list, customer_receipt, gift_message, label,
            delivery_advice, manifest, qr_code, certificate, other
          enum:
            - commercial_invoice
            - packing_list
            - customer_receipt
            - gift_message
            - label
            - delivery_advice
            - manifest
            - qr_code
            - certificate
            - other
        source:
          type: string
          description: |-
            Indicates who created/uploaded the document.
            Possible Values:
            - carriyo: Document generated by Carriyo
            - carrier: Document provided by the carrier
            - user: Document uploaded by the merchant/user via API
          enum:
            - carriyo
            - carrier
            - user
        format:
          type: string
          description: |-
            The file format of the document.
            Possible Values:
            pdf
          enum:
            - pdf
        url:
          type: string
          description: |-
            The URL to access/download the document. This URL is a pre-signed URL that expires after
            a certain period.
        carrier_upload_status:
          type: string
          description: |-
            The status of uploading this document to the carrier (only applicable for documents
            configured for carrier upload).

            Possible Values:

            - pending: Upload is in progress

            - complete: Document was successfully uploaded to the carrier

            - error: Upload to carrier failed
          enum:
            - pending
            - complete
            - error
        carrier_upload_date:
          type: string
          format: date-time
          description: |-
            The date and time when the document was successfully uploaded to the carrier (in ISO
            8601 format).
        message:
          type: string
          description: |-
            Additional message or error details related to the document, particularly useful when
            carrier_upload_status is 'error'.
    document-upload-request:
      title: Document Upload Request
      type: object
      description: Request body for uploading a new document to a shipment.
      properties:
        document_id:
          type: string
          description: |-
            The ID of the document setting to use for this upload. The document setting must be
            pre-configured in your Carriyo account.

            Either `document_id` or `document_name` must be provided.
        document_name:
          type: string
          description: |-
            The name of the document setting to use for this upload. If multiple document settings
            have the same name, the first match will be used.

            Either `document_id` or `document_name` must be provided.
        content_base64:
          type: string
          description: The document content encoded as a Base64 string. Currently only PDF format is supported.
      required:
        - content_base64
    document-update-request:
      title: Document Update Request
      type: object
      description: Request body for updating an existing document's content in a shipment.
      properties:
        content_base64:
          type: string
          description: |-
            The new document content encoded as a Base64 string. This will replace the existing
            document content.
      required:
        - content_base64
    customs-object:
      title: Customs
      type: object
      description: Customs declaration details such as total declared value.
      properties:
        declared_value:
          type: object
          description: |-
            The total value of the shipment (optional) to declare for customs. This value is
            computed from individual item price if this is not passed.
          properties:
            amount:
              minimum: 0
              type: number
            currency:
              type: string
              description: The three-letter currency code (ISO 4217) for the amount. e.g., USD
        incoterms:
          type: string
          enum:
            - CFR
            - CIF
            - CIP
            - CPT
            - DAF
            - DAP
            - DAT
            - DDP
            - DDU
            - DEQ
            - DES
            - DPU
            - EXW
            - FAS
            - FCA
            - FOB
          description: |-
            Defines the international trade term (Incoterm) that specifies the responsibility for
            shipping, duties, and taxes between sender and recipient.
        instructions:
          type: string
          description: Shipment handling instructions or comments intended for customs.
        declaration_statement:
          type: string
          description: |-
            A formal legal statement required for customs clearance, describing the purpose and
            nature of the shipment.
        seller:
          $ref: '#/components/schemas/location-object'
        buyer:
          $ref: '#/components/schemas/location-object'
        importer:
          $ref: '#/components/schemas/location-object'
        exporter:
          $ref: '#/components/schemas/location-object'
        broker:
          $ref: '#/components/schemas/location-object'
    charge-request:
      title: Charge
      required:
        - type
        - amount
      type: object
      properties:
        type:
          type: string
          enum:
            - shipping
            - cod
            - insurance
          description: Defines the category of the charge.
        amount:
          type: object
          properties:
            value:
              minimum: 0
              type: number
            currency:
              type: string
              description: The three-letter currency code (ISO 4217) for the amount. e.g., USD
    item-request:
      title: Item
      required:
        - description
        - price
        - quantity
        - sku
      type: object
      properties:
        sku:
          type: string
          description: SKU ID of the item
        product_item_code:
          type: string
          description: |-
            Use your product item code from your product items list, this will be used for shipment
            item enhancement.
        description:
          type: string
          maxLength: 1000
          description: Description of the item
        barcode:
          type: string
          description: Barcode of the item
        image_link:
          type: string
          description: Image URL of the item
        quantity:
          minimum: 1
          type: integer
        price:
          type: object
          description: The unit price of the item
          required:
            - amount
            - currency
          properties:
            amount:
              minimum: 0
              type: number
            currency:
              type: string
              description: The three-letter currency code (ISO 4217) for the amount. e.g., USD
        cost:
          type: object
          description: |-
            The unit cost of the item. Useful when the selling price is zero (e.g. samples or
            promotional items), since customs authorities require a monetary value for declaration
            even when the item is not being sold. In such cases, set `price` to 0 and provide the
            actual cost here.
          required:
            - amount
            - currency
          properties:
            amount:
              minimum: 0
              type: number
            currency:
              type: string
              description: The three-letter currency code (ISO 4217) for the amount. e.g., USD
        weight:
          type: object
          description: The weight of the item
          properties:
            value:
              type: number
            unit:
              type: string
              enum:
                - kg
              description: Default weight unit is `kg` if not provided.
        origin_country:
          type: string
          description: |-
            Two-letter ISO country code (ISO 3166-1 alpha-2) for the item's country of origin.
            Usually required for cross-border shipping.
        hs_code:
          type: string
          description: HS Code of the item. Usually required for cross-border shipping.
        dangerous_goods:
          type: boolean
          description: |-
            If the item is classified as dangerous goods. Usually required for cross-border
            shipping.
        battery:
          type: object
          description: Battery details of the item. Usually required for cross-border shipping.
          properties:
            material_type:
              type: string
              enum:
                - lithium_metal
                - lithium_ion
            packing_type:
              type: string
              enum:
                - contained_in_equipment
                - packed_with_equipment
                - stand_alone
        manufacturer_id:
          type: string
          description: |-
            Manufacturer reference for the item. May be required by some carriers for certain
            destination countries.
        material_composition:
          type: string
          description: |-
            Material details of the item (e.g., "100% cotton", "polyester blend"). Relevant for
            textile and apparel shipments where customs classification depends on material.
        notes:
          type: string
          maxLength: 1000
          description: Additional information about the item
        taxes:
          type: array
          items:
            $ref: '#/components/schemas/item-tax'
        duties:
          type: array
          items:
            $ref: '#/components/schemas/item-duty'
    item-tax:
      title: Item-level breakdown of taxes
      type: object
      properties:
        amount:
          type: number
          description: Tax amount
        rate:
          type: number
          description: Tax rate
        description:
          type: string
          description: Tax description
    item-duty:
      title: Item-level breakdown of duties
      type: object
      properties:
        amount:
          type: number
          description: Duty amount
        rate:
          type: number
          description: Duty rate
        description:
          type: string
          description: Duty description
        taxes:
          type: array
          items:
            $ref: '#/components/schemas/item-tax'
    item-object:
      title: Item Object
      type: object
      properties:
        sku:
          type: string
          description: SKU ID of the item
        product_item_code:
          type: string
          description: |-
            Use your product item code from your product items list, this will be used for shipment
            item enhancement.
        description:
          type: string
          maxLength: 1000
          description: Description of the item
        barcode:
          type: string
          description: Barcode of the item
        image_link:
          type: string
          description: Image URL of the item
        quantity:
          minimum: 1
          type: integer
        price:
          type: object
          description: The unit price of the item
          required:
            - amount
            - currency
          properties:
            amount:
              minimum: 0
              type: number
            currency:
              type: string
              description: The three-letter currency code (ISO 4217) for the amount. e.g., USD
        cost:
          type: object
          description: |-
            The unit cost of the item. Useful when the selling price is zero (e.g. samples or
            promotional items), since customs authorities require a monetary value for declaration
            even when the item is not being sold. In such cases, set `price` to 0 and provide the
            actual cost here.
          required:
            - amount
            - currency
          properties:
            amount:
              minimum: 0
              type: number
            currency:
              type: string
              description: The three-letter currency code (ISO 4217) for the amount. e.g., USD
        weight:
          type: object
          description: The weight of the item
          properties:
            value:
              type: number
            unit:
              type: string
              enum:
                - kg
              description: Default weight unit is `kg` if not provided.
        origin_country:
          type: string
          description: |-
            Two-letter ISO country code (ISO 3166-1 alpha-2) for the item's country of origin.
            Usually required for cross-border shipping.
        hs_code:
          type: string
          description: HS Code of the item. Usually required for cross-border shipping.
        dangerous_goods:
          type: boolean
          description: |-
            If the item is classified as dangerous goods. Usually required for cross-border
            shipping.
        battery:
          type: object
          description: Battery details of the item. Usually required for cross-border shipping.
          properties:
            material_type:
              type: string
              enum:
                - lithium_metal
                - lithium_ion
            packing_type:
              type: string
              enum:
                - contained_in_equipment
                - packed_with_equipment
                - stand_alone
        manufacturer_id:
          type: string
          description: |-
            Manufacturer reference for the item. May be required by some carriers for certain
            destination countries.
        material_composition:
          type: string
          description: |-
            Material details of the item (e.g., "100% cotton", "polyester blend"). Relevant for
            textile and apparel shipments where customs classification depends on material.
        notes:
          type: string
          description: Additional information about the item
        taxes:
          type: array
          items:
            $ref: '#/components/schemas/item-tax'
        duties:
          type: array
          items:
            $ref: '#/components/schemas/item-duty'
      x-examples: {}
    manifest-request:
      title: Manifest Request
      required:
        - carrier_account
        - merchant
        - pickup
        - pickup_schedule_from
        - pickup_schedule_to
        - ship_manifest_date
        - shipment_ids
      type: object
      properties:
        merchant:
          type: string
        shipment_ids:
          type: array
          items:
            type: string
        carrier_account:
          type: string
        pickup:
          type: object
          properties: {}
        pickup_schedule_from:
          type: string
          format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX
        pickup_schedule_to:
          type: string
          format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX
        ship_manifest_date:
          type: string
          format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX
    manifest-response:
      title: Manifest Response
      required:
        - carrier_account
        - manifest_id
        - merchant
        - pickup
        - pickup_schedule_from
        - pickup_schedule_to
        - ship_manifest_date
        - shipment_ids
      type: object
      properties:
        manifest_id:
          type: string
        merchant:
          type: string
        shipment_ids:
          type: array
          items:
            type: string
        carrier_account:
          type: string
        pickup:
          type: object
          properties: {}
        pickup_schedule_from:
          type: string
          format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX
        pickup_schedule_to:
          type: string
          format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX
        ship_manifest_date:
          type: string
          format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX
    payment-request:
      title: Payment Request
      type: object
      description: |-
        Payment details including the total value of the shipment and any pending Cash on Delivery
        amount.
      properties:
        payment_mode:
          type: string
          enum:
            - PRE_PAID
            - CASH_ON_DELIVERY
          description: |-
            Payment mode of the shipment can be `PRE_PAID` or `CASH_ON_DELIVERY`. It defaults to
            `PRE_PAID` for reverse shipment or if no input is provided.


            `PRE_PAID` is the only valid value for reverse shipments.
        pending_amount:
          minimum: 0
          type: number
          format: double
          description: |-
            Outstanding amount payable on delivery of the shipment. It defaults to 0 for reverse
            shipment or if no input is provided.
        total_amount:
          minimum: 0
          type: number
          format: double
          description: Total value of the shipment
        currency:
          type: string
          description: The three-letter currency code (ISO 4217) for the amount. e.g., USD
      required:
        - total_amount
        - currency
    payment-object:
      title: Payment Object
      type: object
      description: |-
        Payment details including the total value of the shipment and any pending Cash on Delivery
        amount.
      properties:
        payment_mode:
          type: string
          enum:
            - PRE_PAID
            - CASH_ON_DELIVERY
          description: |-
            Payment mode of the shipment can be `PRE_PAID` or `CASH_ON_DELIVERY`. It defaults to
            `PRE_PAID` for reverse shipment or if no input is provided.


            `PRE_PAID` is the only valid value for reverse shipments.
        pending_amount:
          minimum: 0
          type: number
          format: double
          description: |-
            Outstanding amount payable on delivery of the shipment. It defaults to 0 if no input is
            provided.
        total_amount:
          minimum: 0
          type: number
          format: double
          description: Total value of the shipment
        currency:
          type: string
          description: The three-letter currency code (ISO 4217) for the amount. e.g., USD
    insurance-object:
      title: Insurance Object
      type: object
      description: Insurance details including the total insured value of the shipment.
      properties:
        amount:
          minimum: 0
          type: number
          format: double
          description: Total insured amount of the shipment
        currency:
          type: string
          description: The three-letter currency code (ISO 4217) for the amount. e.g., USD
    parcel-request:
      title: Parcel Request
      type: object
      description: List of parcels in a B2C shipment.
      maximum: 250
      properties:
        partner_parcel_reference:
          type: string
          maxLength: 250
          description: A reference number to identify the parcel
        description:
          type: string
          maxLength: 1000
          description: A description for the parcel
        weight:
          $ref: '#/components/schemas/weight'
        dimension:
          $ref: '#/components/schemas/dimension'
        parcel_items:
          type: array
          items:
            $ref: '#/components/schemas/parcel-item'
    freight-request:
      title: Freight request
      type: object
      description: List of packages of type pallet or carton in a B2B shipment.
      maximum: 250
      properties:
        packages:
          type: array
          items:
            $ref: '#/components/schemas/package-object'
    promised-delivery-date-request:
      title: Promised Delivery Date Request
      type: object
      description: Revised promised delivery date
      properties:
        revised_promised_delivery_date:
          type: string
          description: |-
            Revised promised delivery date in ISO 8601 format. For Example:
            2020-09-03T17:07:05.000+1:00 represents the date-time in UTC+1 time zone or
            2020-09-03T17:07:05.000Z represents date-time in UTC (zulu) time zone
          example: '2022-01-01T09:00:00.000+1:00'
          format: date-time
    parcel-object:
      title: Parcel Object
      type: object
      description: List of parcels in a B2C shipment.
      maximum: 250
      properties:
        parcel_id:
          type: string
          description: Unique parcel ID generated by Carriyo
        partner_parcel_reference:
          type: string
          maxLength: 250
          description: Unique parcel reference provided by the merchant
        description:
          type: string
          maxLength: 1000
          description: Description for the parcel provided by the merchant
        weight:
          $ref: '#/components/schemas/weight'
        dimension:
          $ref: '#/components/schemas/dimension'
        parcel_items:
          type: array
          items:
            $ref: '#/components/schemas/parcel-item'
    parcel-item:
      title: Parcel Item
      type: object
      properties:
        sku:
          type: string
        quantity:
          type: integer
    package-object:
      title: Package object
      type: object
      description: List of packages of type pallet or carton in a B2B shipment.
      maximum: 250
      properties:
        package_reference:
          type: string
          maxLength: 250
          description: A reference number to identify the package
        type:
          enum:
            - pallet
            - carton
        weight:
          $ref: '#/components/schemas/weight'
        dimension:
          $ref: '#/components/schemas/dimension'
        parent:
          type: string
          description: A reference number to identify the parent package
    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
    free-form-request:
      title: Free-Form Request
      description: Provide the contact and address information
      type: object
      properties:
        contact_name:
          type: string
          description: Name of the contact person or business
          example: Jo Bloggs
        company_name:
          type: string
          description: |-
            Business or legal entity name. Optional; only needed when it differs from
            `contact_name`. For domestic shipments, the company name is often passed directly in
            `contact_name`.
          example: Acme Fashion Ltd
        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.  e.g., +16175551210
          format: E164 Format (with +<country-code-prefix>)
          example: 16175551210
        contact_email:
          type: string
          description: |-
            Email address for contact
            Conditionally mandatory based on Account Settings
          format: RFC 5322
          example: jo.bloggs@gmail.com
        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
        area:
          type: string
          description: |-
            District, suburb or neighbourhood, represented by the Carriyo Area Code if known. If
            not, it's a free text.


            Please use the Carriyo standard Area Code when available, to ensure that Carriyo can map
            this information correctly to the carrier.


            [Please refer to the Carriyo Geo List for more
            information.](https://carriyo.com/docs/guides/carriyo-geo-list)
          example: DOWNTOWN-DUBAI
        city:
          type: string
          description: |-
            City, town, or village, represented by the Carriyo City Code if known. If not, it's a
            free text.


            Please use the Carriyo standard City Code when available, to ensure that Carriyo can map
            this information correctly to the carrier.


            [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.


            **Note: The state is automatically set if a standard Carriyo city is passed.**


            [Please refer to the Carriyo Geo List for more
            information.](https://carriyo.com/docs/guides/carriyo-geo-list)
          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
        coords:
          type: array
          description: |-
            Latitude and longitude (decimal degrees) of the address as an array. e.g., [25.19741,
            55.27442]
          items:
            type: number
            example: 41.40338
        type:
          type: string
          description: Type of address. i.e. business or residential
          enum:
            - residential
            - business
        notes:
          type: string
          maxLength: 1000
          description: |-
            Any additional notes e.g., "Leave the parcel next to the bin" or "Collect the parcel
            from the neighbour"
          example: Leave the parcel next to the bin
        personal_id:
          $ref: '#/components/schemas/personal_id'
        po_box:
          type: string
          description: Box number if the address is a PO Box
        collection_point_id:
          type: string
          description: |-
            ID of the carrier's collection point for deliveries held at the carrier location for
            collection
        custom_fields:
          $ref: '#/components/schemas/custom-fields'
        address_codes:
          $ref: '#/components/schemas/address-codes'
        registration_numbers:
          $ref: '#/components/schemas/registration-numbers'
      required:
        - contact_name
        - address1
        - city
        - country
    location-request:
      title: Location Request
      type: object
      description: |-
        Specify the Carriyo location ID (`partner_location_id`), or the location code
        (`partner_location_code`) you defined when you created the location in Carriyo.
      properties:
        partner_location_id:
          type: string
          description: Carriyo's internal location id to use for the pickup
        partner_location_code:
          type: string
          description: You can also pass the unique locaton code intead of the location id
    location-object:
      title: Location Object
      type: object
      description: Either a free-form address or a predefined location.
      properties:
        partner_location_id:
          type: string
          description: ID of the location chosen by the merchant
        contact_name:
          type: string
          description: Name of the contact person or business
          example: Jo Bloggs
        company_name:
          type: string
          description: |-
            Business or legal entity name. Optional; only needed when it differs from
            `contact_name`. For domestic shipments, the company name is often passed directly in
            `contact_name`.
          example: Acme Fashion Ltd
        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.  e.g., +16175551210
          format: E164 Format (with +<country-code-prefix>)
          example: 16175551210
        contact_email:
          type: string
          description: |-
            Email address for contact
            Conditionally mandatory based on Account Settings
          format: RFC 5322
          example: jo.bloggs@gmail.com
        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
        area:
          type: string
          description: |-
            District, suburb or neighbourhood, represented by the Carriyo Area 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: DOWNTOWN-DUBAI
        input_area:
          type: string
          description: |-
            (Ready-only) Preserves the original input provided for "area". It is useful when Carriyo
            is instructed to automatically recognise the Carriyo area code.
          example: Downtown Dubai
        area_coords:
          type: array
          description: |-
            (Read-only) Approximate latitude and longitude for the area, if found in Carriyo's
            database. e.g., [25.1949849, 55.2784141]
          items:
            type: number
        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
        input_city:
          type: string
          description: |-
            (Ready-only) Preserves the original input provided for "city". It is useful when Carriyo
            is instructed to automatically recognise the Carriyo city code.
          example: Dubai
        city_coords:
          type: array
          description: |-
            (Read-only) Approximate latitude and longitude for the city, if found in Carriyo's
            database. e.g., [25.1949849, 55.2784141]
          items:
            type: number
        state:
          type: string
          description: |-
            State, county, province, or region, represented by the Carriyo State 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
        input_state:
          type: string
          description: |-
            (Ready-only) Preserves the original input provided for "state". It is useful when
            Carriyo is instructed to automatically recognise the Carriyo state code.
          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
        coords:
          type: array
          description: |-
            Latitude and longitude (decimal degrees) of the address as an array. e.g., [25.19741,
            55.27442]
          items:
            type: number
            example: 41.40338
        type:
          type: string
          description: Type of address. i.e. business or residential
          enum:
            - residential
            - business
        notes:
          type: string
          maxLength: 1000
          description: |-
            Any additional notes e.g., "Leave the parcel next to the bin" or "Collect the parcel
            from the neighbour"
          example: Leave the parcel next to the bin
        personal_id:
          $ref: '#/components/schemas/personal_id'
        po_box:
          type: string
          description: Box number if the address is a PO Box
        collection_point_id:
          type: string
          description: |-
            ID of the carrier's collection point for deliveries held at the carrier location for
            collection
        custom_fields:
          $ref: '#/components/schemas/custom-fields'
        address_codes:
          $ref: '#/components/schemas/address-codes'
        registration_numbers:
          $ref: '#/components/schemas/registration-numbers'
    post-shipping-info:
      title: Post Shipping Info
      type: object
      description: Booking details such as tracking number, labels etc.
      properties:
        status:
          type: string
          description: The status of the shipment (one of the standard Carriyo status)
        reason_code:
          type: string
          description: |-
            The reason code linked to the status (one of the standard Carriyo reason codes or a
            merchant defined status)
        carrier_status:
          type: string
          description: The raw status provided by the carrier
        carrier_status_description:
          type: string
          description: The status description provided by the carrier
        carrier_status_date:
          type: string
          description: |-
            The Date when the carrier status was last updated in ISO 8601 format. Example:
            2022-01-01T17:07:05.000Z
          format: date-time
        carrier_status_location:
          type: string
          description: 'The last known location of the shipment provided by the carrier. For example: Dubai'
        tracking_no:
          type: string
          description: The unique shipment tracking number provided by the carrier
        parcel_tracking_numbers:
          type: array
          description: Tracking numbers for individual parcels if generated by the carrier
          items:
            type: object
            properties:
              parcel_id:
                type: string
              tracking_number:
                type: string
        default_label_url:
          type: string
          description: The url for the default label - either carrier or carriyo generated
        carrier_pdf_label_url:
          type: string
          description: The url of PDF label provided by the carrier
        carrier_qrcode_label_url:
          type: string
          description: The url of QR code label (PNG) provided by the carrier
        carriyo_pdf_label_url:
          type: string
          description: The url of PDF label generated by Carriyo
        carriyo_zpl_label_url:
          type: string
          description: The url of ZPL label generated by Carriyo
        carrier_tracking_url:
          type: string
          description: The url of tracking page provided by the carrier
        carriyo_tracking_url:
          type: string
          description: The url of tracking page provided by the Carriyo
        carriyo_feedback_url:
          type: string
          description: The url of feedback page provided by the Carriyo
        carriyo_pinpoint_url:
          type: string
          description: The url of pinpoint page provided by the Carriyo
        driver_name:
          type: string
          description: The name of the driver delivering the shipment
        driver_phone:
          type: string
          description: The phone number of the driver delivering the shipment
        recipient_name:
          type: string
          description: The name of the recipient to whom shipment was delivered
        proof_of_delivery:
          type: string
          description: The url of document or image containing the proof of delivery
        key_milestones:
          type: object
          properties:
            pending:
              type: string
            error:
              type: string
            booked:
              type: string
            out_for_collection:
              type: string
            ready_to_ship:
              type: string
            cancelled:
              type: string
            cancelled_by_carrier:
              type: string
            failed_collection_attempt:
              type: string
            shipped:
              type: string
            in_transit:
              type: string
            out_for_delivery:
              type: string
            awaiting_customer_collection:
              type: string
            delivered:
              type: string
            delivery_confirmed:
              type: string
            failed_delivery_attempt:
              type: string
            ready_for_return:
              type: string
            return_in_transit:
              type: string
            returned:
              type: string
            return_confirmed:
              type: string
            suspended:
              type: string
            missing:
              type: string
            delayed:
              type: string
        failed_delivery_attempts:
          type: number
          description: The total number of failed delivery attempts on the shipment
        estimated_delivery_date:
          type: string
          description: |-
            The date the shipment is expected to be delivered in ISO 8601 format. Example:
            2022-01-01T17:07:05.000Z
          format: date-time
        carrier_estimated_delivery_date:
          type: string
          description: |-
            The carrier estimated delivery date for the shipment in ISO 8601 format. Example:
            2022-01-01T17:07:05.000Z
          format: date-time
        estimated_ship_date:
          type: string
          description: |-
            The date the shipment is expected to be shipped in ISO 8601 format. Example:
            2022-03-01T17:07:05.000Z
          format: date-time
        error_details:
          type: array
          items:
            $ref: '#/components/schemas/error-detail'
        documents:
          type: array
          description: Shipping documents such as commercial invoice, packing list etc
          items:
            $ref: '#/components/schemas/document-object'
    estimated-shipping-cost:
      type: object
      description: |-
        The estimated cost of the shipping based either on the costing profile you have configured
        for the carrier or carrier costing API response
      properties:
        amount:
          type: number
          example: 10
        currency:
          type: string
          example: USD
        breakdown:
          type: array
          description: The breakdown of shipping cost.
          items:
            $ref: '#/components/schemas/breakdown-object'
    breakdown-object:
      type: object
      description: |-
        The estimated cost of the shipping based either on the costing profile you have configured
        for the carrier or carrier costing API response
      properties:
        amount:
          type: number
          example: 10
        currency:
          type: string
          example: USD
        description:
          type: string
          example: Total VAT Charge
    references-request:
      title: References Request
      type: object
      description: |-
        References for a shipment, provided by the merchant.


        The `partner_order_reference` is mandatory but not required to be unique. It is usually the
        customer facing order number.


        The `partner_shipment_reference` must be unique for every shipment. It is mandatory, but is
        copied from `partner_order_reference` if it is not provided.


        If a single order has multiple shipments, then they will share the `partner_order_reference`
        but have unique `partner_shipment_reference`.
      properties:
        partner_order_reference:
          type: string
          maxLength: 250
          description: Order reference provided by the merchant
        partner_shipment_reference:
          type: string
          maxLength: 250
          description: Unique shipment reference provided by the merchant
        alternate_reference:
          type: string
          maxLength: 250
          description: |-
            An alternate reference that can be used for searching shipments in Carriyo or mapping
            references to the carrier.
        other_references:
          type: array
          maxLength: 250
          description: A list of references that can be used for searching shipments in Carriyo
          items:
            type: string
      required:
        - partner_order_reference
        - partner_shipment_reference
    references-object:
      title: References Object
      type: object
      description: References for a shipment, provided by the merchant.
      properties:
        partner_order_reference:
          type: string
          description: Order reference provided by the merchant
          maxLength: 250
        partner_shipment_reference:
          type: string
          description: Unique shipment reference provided by the merchant
          maxLength: 250
        alternate_reference:
          type: string
          description: |-
            An alternate reference that can be used for searching shipments in Carriyo or mapping
            references to the carrier.
          maxLength: 250
        other_references:
          type: array
          maxLength: 250
          description: A list of references that can be used for searching shipments in Carriyo
          items:
            type: string
    shipment-patch-request:
      title: Shipment Patch Update Request
      type: object
      properties:
        order_type:
          type: string
          description: Pass one of the order types you have predefined in Carriyo
        carrier_account:
          $ref: '#/components/schemas/carrier-account-request'
        payment:
          $ref: '#/components/schemas/payment-request'
        collection:
          $ref: '#/components/schemas/collection-request'
        delivery:
          $ref: '#/components/schemas/delivery-request'
        pickup:
          description: |-
            Pickup address for the shipment. You can either pass a free-form address or a predefined
            location.


            For forward shipments, you must pass a predefined pickup location. Carriyo will copy the
            contact and address fields from the specified location. To specify the location, you can
            use Carriyo's internal location ID (`partner_location_id`), or your own location code
            (`partner_location_code`) defined when you created the location in Carriyo.


            For reverse shipments, you can pass the customer's pickup address as a free-form pickup
            address.
          anyOf:
            - $ref: '#/components/schemas/location-request'
            - $ref: '#/components/schemas/free-form-request'
        dropoff:
          description: |-
            Dropoff address for the shipment. You can either pass a free-form address or a
            predefined location.


            For forward shipments, you can pass the customer's dropoff address as a free-form
            address.


            For reverse shipments, you must pass a predefined dropoff location. Carriyo will copy
            the contact and address fields from the specified location. To specify the location, you
            can use Carriyo's internal location ID (`partner_location_id`), or your own location
            code (`partner_location_code`) defined when you created the location in Carriyo.
          anyOf:
            - $ref: '#/components/schemas/free-form-request'
            - $ref: '#/components/schemas/location-request'
        items:
          type: array
          items:
            $ref: '#/components/schemas/item-request'
          description: List of individual items or SKUs in a shipment.
          maximum: 250
        parcels:
          type: array
          items:
            $ref: '#/components/schemas/parcel-request'
          description: List of parcels in a B2C shipment.
          maximum: 250
        freight:
          type: object
          description: List of packages of type pallet or carton in a B2B shipment.
          maximum: 250
          properties:
            packages:
              type: array
              items:
                $ref: '#/components/schemas/package-object'
        customs:
          $ref: '#/components/schemas/customs-object'
        charges:
          type: array
          items:
            $ref: '#/components/schemas/charge-request'
          description: List of individual charge components applied to the shipment.
        custom_attributes:
          $ref: '#/components/schemas/custom-attributes'
        order_date:
          type: string
          format: date-time
        input_promised_delivery_date:
          type: string
          description: |-
            Optional. The promised delivery date to the end customer, in ISO 8601 format.


            If omitted, Carriyo will set the promised delivery date from the scheduled delivery
            window when present, or otherwise from service level configuration.


            Example: 2020-09-03T17:07:05.000+1:00 represents the date-time in UTC+1 time zone or
            2020-09-03T17:07:05.000Z represents date-time in UTC (zulu) time zone
          format: date-time
          example: '2022-01-01T09:00:00.000Z'
        consolidated:
          type: boolean
          description: Mark this shipment as a consolidated parent. Requires `consolidated_child_shipments`.
        consolidated_child_shipments:
          type: array
          items:
            type: string
          description: Shipment IDs of the child shipments to consolidate under this one. Only used when `consolidated` is `true`.
        duties_included:
          type: boolean
          description: Whether duties are already included in the item prices.
        taxes_included:
          type: boolean
          description: Whether taxes are already included in the item prices.
        estimated_shipping_cost:
          allOf:
            - $ref: '#/components/schemas/estimated-shipping-cost'
          description: Override the estimated shipping cost. Carriyo will recompute where possible.
        insurance:
          allOf:
            - $ref: '#/components/schemas/insurance-object'
          description: Insurance details for the shipment.
        language:
          type: string
          description: Two-letter ISO 639-1 language code for customer-facing communications.
          example: en
        pre_booked:
          type: boolean
          description: Mark as `true` for a shipment already booked with a carrier outside Carriyo. Requires `pre_booking_info`.
        pre_booking_info:
          allOf:
            - $ref: '#/components/schemas/pre-booking-info'
          description: Carrier tracking details for a pre-booked shipment. Required when `pre_booked` is `true`.
        references:
          allOf:
            - $ref: '#/components/schemas/references-request'
          description: Merchant-supplied references (order reference, partner reference, etc.).
        skip_validations:
          type: array
          items:
            type: string
          description: Names of validation groups to skip on this request. Used in advanced flows where the caller wants to bypass specific validation rules, for example accepting a shipment without a confirmed pickup window.
    shipment-request:
      title: Shipment Request
      type: object
      properties:
        entity_type:
          type: string
          default: FORWARD
          enum:
            - FORWARD
            - REVERSE
        merchant:
          type: string
          description: Merchant ID is mandatory to create a shipment
          example: YOUR_MERCHANT_ID
        references:
          $ref: '#/components/schemas/references-request'
        carrier_account:
          $ref: '#/components/schemas/carrier-account-request'
        payment:
          $ref: '#/components/schemas/payment-request'
        collection:
          $ref: '#/components/schemas/collection-request'
        delivery:
          $ref: '#/components/schemas/delivery-request'
        pickup:
          description: |-
            Pickup address for the shipment. You can either pass a free-form address or a predefined
            location.


            For forward shipments, you must pass a predefined pickup location. Carriyo will copy the
            contact and address fields from the specified location. To specify the location, you can
            use Carriyo's internal location ID (`partner_location_id`), or your own location code
            (`partner_location_code`) as defined when you created the location in Carriyo.


            For reverse shipments, you can pass the customer's pickup address as a free-form pickup
            address.
          anyOf:
            - $ref: '#/components/schemas/location-request'
            - $ref: '#/components/schemas/free-form-request'
        dropoff:
          description: |-
            Dropoff address for the shipment. You can either pass a free-form address or a
            predefined location.


            For forward shipments, you can pass the customer's dropoff address as a free-form
            address.


            For reverse shipments, you must pass a predefined dropoff location. Carriyo will copy
            the contact and address fields from the specified location. To specify the location, you
            can use Carriyo's internal location ID (`partner_location_id`), or your own location
            code (`partner_location_code`) as defined when you created the location in Carriyo.
          anyOf:
            - $ref: '#/components/schemas/free-form-request'
            - $ref: '#/components/schemas/location-request'
        items:
          type: array
          items:
            $ref: '#/components/schemas/item-request'
          description: List of individual items or SKUs in a shipment.
          maximum: 250
        parcels:
          type: array
          items:
            $ref: '#/components/schemas/parcel-request'
          description: List of parcels in a B2C shipment.
          maximum: 250
        freight:
          title: Freight request
          type: object
          description: List of packages of type pallet or carton in a B2B shipment.
          maximum: 250
          properties:
            packages:
              type: array
              items:
                $ref: '#/components/schemas/package-object'
        customs:
          $ref: '#/components/schemas/customs-object'
        charges:
          type: array
          items:
            $ref: '#/components/schemas/charge-request'
          description: List of individual charge components applied to the shipment.
        custom_attributes:
          $ref: '#/components/schemas/custom-attributes'
        order_date:
          type: string
          description: |-
            Date-time in ISO 8601 format.


            Example: 2020-09-03T17:07:05.000+1:00 represents the date-time in UTC+1 time zone or
            2020-09-03T17:07:05.000Z represents date-time in UTC (zulu) time zone
          format: date-time
          example: '2022-01-01T09:00:00.000+1:00'
        input_promised_delivery_date:
          type: string
          description: |-
            Optional. The promised delivery date to the end customer, in ISO 8601 format.


            If present, Carriyo will not calculate promise date from service level configuration.


            Example: 2020-09-03T17:07:05.000+1:00 represents the date-time in UTC+1 time zone or
            2020-09-03T17:07:05.000Z represents date-time in UTC (zulu) time zone
          format: date-time
          example: '2022-01-01T09:00:00.000Z'
        order_type:
          type: string
          description: Pass one of the order types you have predefined in Carriyo
          example: HOME_DELIVERY
        language:
          type: string
          description: 'Two letter ISO 639-1 code. Example: en'
          example: en
        taxes_included:
          type: boolean
          description: Indicating whether taxes are included in the item's price
        duties_included:
          type: boolean
          description: Indicating whether duties are included in the item's price
        consolidated:
          type: boolean
          description: |-
            Set to `true` to create this shipment as a consolidated parent. Requires
            `consolidated_child_shipments` to be supplied.


            This is a **deferred validation**: if `consolidated_child_shipments` is missing
            when Carriyo books the shipment with the carrier, the shipment is set to
            status `error`. It is not rejected at create time.
        consolidated_child_shipments:
          type: array
          items:
            type: string
          description: Shipment IDs of the child shipments to consolidate under this one. Only used when `consolidated` is `true`.
        estimated_shipping_cost:
          allOf:
            - $ref: '#/components/schemas/estimated-shipping-cost'
          description: Optionally pre-populate the estimated shipping cost. Carriyo will recompute this where possible.
        fulfillment_order_id:
          type: string
          description: ID of the fulfillment order this shipment fulfills (when creating a shipment for an order managed by the Carriyo Orders API).
        order_id:
          type: string
          description: ID of the parent order (when creating a shipment for an order managed by the Carriyo Orders API).
        return_request_id:
          type: string
          description: ID of the return request that triggered this (reverse) shipment.
        insurance:
          allOf:
            - $ref: '#/components/schemas/insurance-object'
          description: Insurance details for the shipment.
        pre_booked:
          type: boolean
          description: |-
            Set to `true` when registering a shipment that has already been booked with a
            carrier outside Carriyo. Requires `pre_booking_info`.


            This is a **deferred validation**: if `pre_booking_info` is missing when
            Carriyo books the shipment, the shipment is set to status `error`. It is not
            rejected at create time.
        pre_booking_info:
          allOf:
            - $ref: '#/components/schemas/pre-booking-info'
          description: Carrier tracking details for a pre-booked shipment. Required when `pre_booked` is `true`.
      required:
        - merchant
        - references
    shipment-object:
      title: Shipment Object
      type: object
      properties:
        shipment_id:
          type: string
          description: Unique identifier for the shipment
          example: XYZABC123
        tenant:
          type: string
          description: Identifier of the Carriyo tenant that owns this shipment. Derived from the authenticated credentials at create time; you cannot set it directly.
          readOnly: true
          example: acme
        entity_type:
          type: string
          enum:
            - FORWARD
            - REVERSE
          description: The type of the shipment is either FORWARD or REVERSE
        merchant:
          type: string
          description: ID of the merchant that created this shipment
          example: MY_BRAND
        references:
          $ref: '#/components/schemas/references-object'
        carrier_account:
          $ref: '#/components/schemas/carrier-account-object'
        payment:
          $ref: '#/components/schemas/payment-object'
        insurance:
          $ref: '#/components/schemas/insurance-object'
        collection:
          $ref: '#/components/schemas/collection-object'
        delivery:
          $ref: '#/components/schemas/delivery-object'
        pickup:
          $ref: '#/components/schemas/location-object'
        dropoff:
          $ref: '#/components/schemas/location-object'
        items:
          type: array
          items:
            $ref: '#/components/schemas/item-object'
          description: List of individual items or SKUs in a shipment.
          maximum: 250
        freight:
          title: Freight request
          type: object
          description: List of packages of type pallet or carton in a B2B shipment.
          maximum: 250
          properties:
            packages:
              type: array
              items:
                $ref: '#/components/schemas/package-object'
        customs:
          $ref: '#/components/schemas/customs-object'
        charges:
          type: array
          items:
            $ref: '#/components/schemas/charge-request'
          description: List of individual charge components applied to the shipment.
        parcels:
          type: array
          items:
            $ref: '#/components/schemas/parcel-object'
          description: List of parcels in a B2C shipment.
          maximum: 250
        post_shipping_info:
          $ref: '#/components/schemas/post-shipping-info'
        custom_attributes:
          type: object
          description: Additional custom attributes provided by the merchant.
        order_date:
          type: string
          format: date-time
          description: The date the customer order was received by the merchant
          example: '2022-01-01T09:00:00.000Z'
        order_type:
          type: string
          description: |-
            The type of the order. The possible values can be one of the order types predefined by
            the merchant.
          example: HOME_DELIVERY
        creation_date:
          type: string
          format: date-time
          description: The date the shipment was created in Carriyo
          example: '2022-01-01T09:00:00.000Z'
        update_date:
          type: string
          format: date-time
          description: The date the shipment was last updated in Carriyo
          example: '2022-01-01T09:00:00.000Z'
        confirmation_date:
          type: string
          format: date-time
          description: The date the shipment was confirmed for booking
          example: '2022-01-01T09:00:00.000Z'
        estimated_process_date:
          type: string
          format: date-time
          description: |-
            The date the shipment is expected to be processed in ISO 8601 format. Example:
            2022-03-01T17:07:05.000Z
        promised_delivery_date:
          type: string
          format: date-time
          description: |-
            The promised delivery date for the shipment in ISO 8601 format. Example:
            2022-03-01T17:07:05.000Z
          example: '2022-01-01T09:00:00.000Z'
        original_promised_delivery_date:
          type: string
          format: date-time
          description: |-
            The original promised delivery date for the shipment in ISO 8601 format (if the promise
            is updated). Example: 2022-03-01T17:07:05.000Z
          example: '2022-01-01T09:00:00.000Z'
        estimated_shipping_cost:
          $ref: '#/components/schemas/estimated-shipping-cost'
        language:
          type: string
          description: 'Two letter ISO 639-1 code. Example: en'
          example: en
        return_request_id:
          type: string
          description: ID of the Return request that initiated the reverse shipment
          example: rma_123abcXYZ
        consolidated:
          type: boolean
          description: True when this shipment is a consolidated parent containing other shipments.
        consolidated_child_shipments:
          type: array
          items:
            type: string
          description: Shipment IDs of the child shipments. Populated when `consolidated` is true.
        consolidated_parent_shipment:
          type: string
          description: Shipment ID of the consolidated parent. Populated when this shipment is a child of a consolidated parent.
        creation_source:
          allOf:
            - $ref: '#/components/schemas/request-source'
          description: Identifies the system or actor that created the shipment.
        update_source:
          allOf:
            - $ref: '#/components/schemas/request-source'
          description: Identifies the system or actor that last updated the shipment.
        customer_key:
          type: string
          description: Derived stable identifier for the customer on this shipment, used for repeat-customer matching. Derived from contact details on the dropoff/pickup; you cannot set it directly.
          readOnly: true
        duties_included:
          type: boolean
          description: Whether duties are already included in the item prices.
        taxes_included:
          type: boolean
          description: Whether taxes are already included in the item prices.
        fulfillment_order_id:
          type: string
          description: ID of the fulfillment order that this shipment fulfills (if created via the Orders API).
        order_id:
          type: string
          description: ID of the order this shipment belongs to (if created via the Orders API).
        manifest_id:
          type: string
          description: ID of the manifest this shipment has been added to (if any).
        input_promised_delivery_date:
          type: string
          format: date-time
          description: The originally-requested promised delivery date as supplied on create, before any rule-based or carrier-driven adjustment. Carriyo uses this to detect customer-visible changes.
        pre_booked:
          type: boolean
          description: True when the shipment was already booked with a carrier outside Carriyo and ingested into Carriyo for tracking only.
        pre_booking_info:
          allOf:
            - $ref: '#/components/schemas/pre-booking-info'
          description: Pre-booking details. Required when `pre_booked` is true.
        suppress_communication:
          type: boolean
          description: When true, Carriyo will not send customer-facing communications (tracking emails, SMS) for this shipment.
        translated:
          allOf:
            - $ref: '#/components/schemas/translated'
          description: Translated pickup and dropoff details. Populated when the `language` field requested a translation that Carriyo has generated.
    update-parcels-request:
      title: Update Parcels Request
      type: object
      properties:
        parcels:
          type: array
          items:
            $ref: '#/components/schemas/parcel-request'
    weight:
      title: Weight
      type: object
      properties:
        value:
          type: number
        unit:
          type: string
          enum:
            - kg
          description: Default weight unit is `kg` if not provided.
    carriyo-metadata:
      title: Carriyo Metadata
      type: object
      description: A custom key-value metadata entry attached to a Carriyo entity.
      properties:
        name:
          type: string
          description: Metadata key.
        value:
          type: string
          description: Metadata value.
    request-source:
      title: Request Source
      type: object
      description: Identifies the system or actor that originated a shipment create or update.
      properties:
        source_type:
          type: string
          description: Originating system type (e.g. `api`, `dashboard`, `handler`, `carriyo`, `shopify_connector`, `magento_connector`).
        source_id:
          type: string
          description: Identifier of the originator (user id, connector id, handler name).
        api_pattern:
          type: string
          description: For API-originated requests, the matched route pattern.
        request_type:
          type: string
          description: Logical operation name (e.g. `SHIPMENT_CREATE`).
        system_log_identifier:
          type: string
          description: Correlation identifier for the system log entry.
    pre-booking-info:
      title: Pre-Booking Info
      type: object
      description: Tracking details supplied when a shipment was already booked with a carrier outside Carriyo (the pre-booked workflow).
      properties:
        carrier_tracking_no:
          type: string
          description: Tracking number issued by 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.
    translated:
      title: Translated
      type: object
      description: Translated location info for pickup and dropoff. Populated when the shipment's `language` differs from the canonical English data and a translation has been generated.
      properties:
        pickup:
          type: object
          description: Translated pickup location info.
          additionalProperties: true
        dropoff:
          type: object
          description: Translated dropoff location info.
          additionalProperties: true
  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`."
