openapi: 3.0.1
info:
  title: Carriyo Checkout API
  version: '1.0'
  description: |-
    Pre-purchase endpoints for showing live shipping options at customer checkout. Use the shipping-rates endpoint to fetch carrier rates for a given route, and the delivery-options endpoint to fetch the curated options configured for the merchant. Neither call creates a shipment.
  contact:
    name: Carriyo Support
    url: https://help.carriyo.com
    email: support@carriyo.com
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: checkout
    description: |-
      Real-time rate and delivery-option lookups used at the customer checkout step. Stateless: no shipment is created by these calls.

      These endpoints are typically called by storefront frontends or headless commerce middleware, and handle higher request volume than the per-shipment management endpoints.
  - name: delivery-options
    description: |-
      Manage the curated delivery options shown at customer checkout. Each option carries the carrier account that fulfils it, the customer-facing pricing and timing, and the eligibility conditions (geography, order value, weight, payment type) under which it appears.

      These are the management endpoints: create, read, update, delete. For the runtime endpoint shoppers indirectly hit at checkout, see the `Checkout` tag above.
paths:
  /checkout/shipping-rates:
    post:
      summary: Get shipping rates
      tags:
        - checkout
      operationId: get-shipping-rates
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/shipping-rates-request'
        required: true
      responses:
        '200':
          description: 'Shipping rates from eligible carriers for the requested shipment.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipping-rates-response'
      description: |-
        Returns live shipping rates from eligible carriers for a future shipment. Stateless: no shipment is created.
  /checkout/delivery-options:
    post:
      summary: Get delivery options
      tags:
        - checkout
      operationId: get-delivery-options
      description: |-
        Returns the **delivery options** that match the supplied cart or order details at checkout
        time.


        Delivery options are configured per merchant in the Carriyo dashboard. Each option declares
        the carrier account that fulfils it, a shipping fee, an estimated delivery window, and a set
        of optional conditions. This endpoint evaluates the configured conditions against the order
        details you supply inline and returns the matching options, typically rendered to the
        shopper as the delivery choices on the checkout page.


        Both `DELIVERY` and `COLLECTION` options can be returned. The shopper has not chosen between
        them at this point, so `customer` represents *where the customer is*, not *where the order is
        being delivered*. For `DELIVERY` options the customer's location is also the delivery
        destination; for `COLLECTION` options it's used to find applicable collection points.


        ### Supplying order details


        Pass the order details inline in the request body. Only `merchant` is required; populate the
        remaining fields based on which conditions the merchant has configured. This endpoint does
        not look up existing orders; all order data must be provided directly in the request.


        ### Restricting by delivery method


        Pass `delivery_methods` to limit the response to only the methods you can render. For
        example, send `["DELIVERY"]` from a storefront that doesn't support pickup points, or
        `["COLLECTION"]` from a click-and-collect locator screen. Omit the field to receive all
        matching methods.


        ### What gets evaluated


        Each condition only applies when the merchant has configured it on a delivery option. The
        corresponding order field is read only if such a condition exists, so callers only need to
        populate the fields relevant to the rules in use.


        | Condition (configured on the option) | Evaluated against |

        |---|---|

        | Working days / blackout days | `order_date` (defaults to now); timezone derived from
        `customer.country` |

        | Customer geography | `customer.{country, state, city, area}` |

        | Order value range | `payment.order_total` |

        | Weight range | Sum of `line_items[].weight` (converted to kg) |

        | Payment type | Derived: `CASH_ON_DELIVERY` if `payment.payment_on_delivery > 0`,
        otherwise `PRE_PAID` |

        | Fulfillment location | `fulfillment_locations[]`. Pass one or more candidate
        fulfillment locations. An option matches if at least one of the supplied locations is in the
        option's allowlist (or the option has no allowlist). For a configured Carriyo location,
        supply either `partner_location_code` (your own code, **recommended for storefront
        integrations**) or `partner_location_id` (Carriyo's internal ID); free-form address fields
        are also accepted |


        ### Collection points for `COLLECTION` options


        For each matching `COLLECTION` option, Carriyo also returns a list of eligible collection
        points (configured Carriyo locations with the `collection_location` flag enabled) under
        `customer_collection_locations` on the response item. Three pieces of input shape the
        result:


        - `customer.coords`: when supplied (latitude/longitude), Carriyo computes the distance
        from the customer to each location and sorts the result nearest-first. Locations without
        coordinates are excluded from a distance-bound result. When customer coordinates aren't
        supplied, locations are returned in the merchant-configured order with no distance field.

        - `max_collection_distance` (request): a client-supplied upper bound on the returned
        distance. Effective only when customer coordinates are supplied.

        - `customer_collection_max_distance` (per-option, configured by the merchant): a hard
        upper bound the merchant authored for this option. Carriyo applies the smaller of this and
        the request's `max_collection_distance` when filtering.


        The result list is capped at `max_collection_locations` (defaults to 10 when omitted,
        capped server-side at 50).


        ### Response


        An array of matching delivery options, each with its carrier account, computed shipping fee,
        and estimated arrival window. The array is empty if no configured option matches the
        supplied order.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/delivery-options-request'
            examples:
              Cart Checkout:
                summary: Cart at checkout with customer location, items, and order value
                description: |-
                  The most common scenario. A shopper is at checkout and order details are supplied
                  inline. The request provides the customer's location (for customer-geography rules
                  and timezone), `payment.order_total` (for order-value range rules), and
                  `line_items` with weights (for weight range rules). Fulfillment location is
                  omitted, so Carriyo falls back to the merchant's default sourcing.
                value:
                  merchant: ACME
                  payment:
                    currency: AED
                    order_total: 285
                  customer:
                    country: AE
                    state: DUBAI
                    city: DUBAI
                    area: DOWNTOWN-DUBAI
                  line_items:
                    - id: line-1
                      sku: TSHIRT-BLK-M
                      quantity: 2
                      weight:
                        value: 0.25
                        unit: kg
                    - id: line-2
                      sku: JEANS-W32-L32
                      quantity: 1
                      weight:
                        value: 0.6
                        unit: kg
              Fulfillment From Specific Locations:
                summary: One or more candidate fulfillment locations
                description: |-
                  Pass the candidate fulfillment locations the order could be sourced from under
                  `fulfillment_locations` (an array). Carriyo returns the options whose
                  fulfillment-location allowlist contains at least one of the supplied locations
                  (options without an allowlist are unconstrained). Per option, the first matching
                  location is used to drive origin-country-based estimated arrival and, for
                  `PASS_THROUGH` pricing, the carrier rate quote. We recommend
                  `partner_location_code` (your own user-defined code) over `partner_location_id`
                  (Carriyo's internal ID): codes are stable in your own systems, easier to keep in
                  sync, and don't require storing the Carriyo-side ID. Either field is accepted.
                  Carriyo enriches the rest of each address from the configured location.
                value:
                  merchant: ACME
                  payment:
                    currency: AED
                    order_total: 450
                  fulfillment_locations:
                    - partner_location_code: store-ad-marina-mall
                    - partner_location_code: warehouse-dxb-01
                  customer:
                    country: AE
                    state: ABU-DHABI
                    city: ABU-DHABI
                  line_items:
                    - id: line-1
                      sku: WATCH-SS-42
                      quantity: 1
                      weight:
                        value: 0.4
                        unit: kg
              Cash on Delivery:
                summary: Order paid on delivery
                description: |-
                  Set `payment.payment_on_delivery` to the amount payable to the courier on
                  delivery. Carriyo derives the payment type as `CASH_ON_DELIVERY`, which lets
                  options with a payment-type condition evaluate correctly; pre-payment-only
                  options are excluded.
                value:
                  merchant: ACME
                  payment:
                    currency: AED
                    order_total: 199
                    payment_on_delivery: 199
                  customer:
                    country: AE
                    state: DUBAI
                    city: DUBAI
                  line_items:
                    - id: line-1
                      sku: HEADPHONES-BT-OE
                      quantity: 1
                      weight:
                        value: 0.3
                        unit: kg
              Collection-aware Checkout:
                summary: Click-and-collect locator, COLLECTION-only with proximity caps
                description: |-
                  A click-and-collect locator screen scoped to `COLLECTION` only via
                  `delivery_methods`. The customer's latitude/longitude is supplied so Carriyo
                  sorts returned collection points by distance, and the cart asks for at most 5
                  nearby points within 15 km of the customer (any per-option merchant cap may
                  narrow this further).
                value:
                  merchant: ACME
                  delivery_methods:
                    - COLLECTION
                  max_collection_locations: 5
                  max_collection_distance:
                    value: 15
                    unit: km
                  payment:
                    currency: AED
                    order_total: 320
                  customer:
                    country: AE
                    state: DUBAI
                    city: DUBAI
                    area: DOWNTOWN-DUBAI
                    coords:
                      - 25.197
                      - 55.274
                  line_items:
                    - id: line-1
                      sku: SHOES-RUN-42
                      quantity: 1
                      weight:
                        value: 0.9
                        unit: kg
      responses:
        '200':
          description: The delivery options that match the supplied order.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/delivery-options-response-item'
              examples:
                Mixed Delivery and Collection Options:
                  summary: A mix of DELIVERY and COLLECTION options matching the cart
                  description: |-
                    Three options are returned: two `DELIVERY` options and one `COLLECTION` option
                    with two nearby collection points sorted by distance from the customer.
                  value:
                    - delivery_method: DELIVERY
                      code: STD
                      name: Standard Delivery
                      description: Delivered in 2–4 working days
                      carrier_account_id: ca-aramex-uae-001
                      shipping_fee:
                        amount: 15
                        currency: AED
                      estimated_arrival_from: '2026-05-07T09:00:00.000Z'
                      estimated_arrival_to: '2026-05-09T18:00:00.000Z'
                    - delivery_method: DELIVERY
                      code: NEXT_DAY
                      name: Next Day Delivery
                      description: Order before 6pm for next working day
                      carrier_account_id: ca-fetchr-uae-001
                      shipping_fee:
                        amount: 25
                        currency: AED
                      estimated_arrival_from: '2026-05-06T09:00:00.000Z'
                      estimated_arrival_to: '2026-05-06T18:00:00.000Z'
                    - delivery_method: COLLECTION
                      code: STORE_PICKUP
                      name: Collect From Store
                      description: Free pickup from a participating store
                      shipping_fee:
                        amount: 0
                        currency: AED
                      estimated_arrival_from: '2026-05-06T10:00:00.000Z'
                      estimated_arrival_to: '2026-05-06T22:00:00.000Z'
                      customer_collection_locations:
                        - location_id: loc-dxb-downtown
                          location_code: STORE-DXB-DOWNTOWN
                          location_name: ACME Downtown Dubai
                          address1: Boulevard Plaza, Tower 1
                          city: DUBAI
                          state: DUBAI
                          country: AE
                          area: DOWNTOWN-DUBAI
                          coords:
                            - 25.197
                            - 55.274
                          distance:
                            value: 0.4
                            unit: km
                        - location_id: loc-dxb-marina
                          location_code: STORE-DXB-MARINA
                          location_name: ACME Marina Mall
                          address1: Marina Mall, Ground Floor
                          city: DUBAI
                          state: DUBAI
                          country: AE
                          area: DUBAI-MARINA
                          coords:
                            - 25.078
                            - 55.144
                          distance:
                            value: 12.3
                            unit: km
  /delivery-options:
    post:
      tags:
        - delivery-options
      summary: Create delivery option
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Creates a customer-facing delivery option (e.g. 'Same Day', 'Next Day Premium') with its associated carrier, schedule, fee, and eligibility conditions.
      operationId: create-delivery-option
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/delivery-option'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delivery-option'
    get:
      tags:
        - delivery-options
      summary: List delivery options
      operationId: list-delivery-options
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/delivery-option'
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Returns the merchant's delivery options.
  /delivery-options/{id}:
    get:
      tags:
        - delivery-options
      summary: Get delivery option
      operationId: get-delivery-option
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Delivery option ID.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delivery-option'
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Returns the specified delivery option.
    put:
      tags:
        - delivery-options
      summary: Update delivery option
      operationId: update-delivery-option
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Delivery option ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/delivery-option'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/delivery-option'
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Updates the specified delivery option.
    delete:
      tags:
        - delivery-options
      summary: Delete delivery option
      operationId: delete-delivery-option
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Delivery option ID.
      responses:
        '204':
          description: Deleted.
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Permanently deletes the specified delivery option.
components:
  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`."
  schemas:
    shipping-rates-request:
      title: Get shipping rates for one or more carriers.
      description: |-
        Request body for a shipping-rates quote. Rates are sourced from each carrier's configured
        costing profile, or from the carrier's live rating API where enabled.
      type: object
      properties:
        merchant:
          type: string
          default: Primary merchant ID if only 1 registered
          description: ID of the merchant
          example: MY_BRAND
        entity_type:
          type: string
          default: FORWARD
          enum:
            - FORWARD
            - REVERSE
        carrier_accounts:
          type: array
          items:
            $ref: '#/components/schemas/carrier-account-request'
          description: List of carrier accounts for which shipping rate is requested.
        payment:
          $ref: '#/components/schemas/payment-request'
        customs:
          $ref: '#/components/schemas/customs-object'
        collection:
          $ref: '#/components/schemas/collection-object'
        delivery:
          $ref: '#/components/schemas/delivery-object'
        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/shipping-rate-location-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/shipping-rate-location-request'
            - $ref: '#/components/schemas/location-request'
        items:
          type: array
          items:
            $ref: '#/components/schemas/shipping-rate-item-request'
          description: List of individual items or SKUs in a shipment.
          maximum: 250
        parcels:
          type: array
          items:
            $ref: '#/components/schemas/shipping-rate-parcel-request'
          description: (One of parcels or freight required) List of parcels in a B2C shipment.
          maximum: 250
        freight:
          title: Freight request
          type: object
          description: |-
            (One of parcels or freight required) List of packages of type pallet or carton in a B2B
            shipment.
          maximum: 250
          properties:
            packages:
              type: array
              items:
                $ref: '#/components/schemas/shipping-rate-package-object'
        custom_attributes:
          $ref: '#/components/schemas/custom-attributes'
      required:
        - carrier_account
        - pickup
        - dropoff
        - parcels
    shipping-rates-response:
      title: Shipping rates response
      type: object
      description: The response returned for shipping rates for one or more carriers.
      properties:
        shipping_rates:
          type: array
          items:
            $ref: '#/components/schemas/shipping-rate'
    delivery-options-request:
      title: Delivery Options Request
      type: object
      description: |-
        Inline order details used to evaluate which delivery options match the current cart.
        Only `merchant` is required; populate the remaining fields based on which conditions the
        merchant has configured (see the operation description).
      properties:
        merchant:
          type: string
          description: The merchant the order belongs to. The API key must have access to this merchant.
          example: ACME
        order_date:
          type: string
          format: date-time
          description: |-
            The date the order was placed (ISO 8601). Defaults to the time of the request. Used as
            the reference date for working-day and blackout-day evaluation.
          example: '2026-05-05T10:30:00.000Z'
        payment:
          $ref: '#/components/schemas/delivery-options-payment'
        line_items:
          type: array
          description: |-
            The items in the order. The total order weight used for weight range condition
            evaluation is the sum of `weight.value` across line items, converted to kg.


            **Quantity is not factored in.** If a line ships multiple units, set `weight.value` to
            the total weight contributed by that line, not the per-unit weight.
          items:
            $ref: '#/components/schemas/delivery-options-line-item'
        parcels:
          type: array
          description: |-
            Parcels in the order. Used by the carrier rate calculator when a matching option's
            pricing strategy is `PASS_THROUGH` (i.e., the carrier-quoted rate is shown to the
            shopper). Not used by condition matching; weight conditions are evaluated against
            `line_items`.
          items:
            $ref: '#/components/schemas/delivery-options-parcel'
        fulfillment_locations:
          type: array
          description: |-
            Candidate locations the order could be fulfilled from (origin/warehouse/store). Pass
            one or more, and Carriyo returns the options whose fulfillment-location allowlist
            contains at least one of these (options without an allowlist are unconstrained). Per
            option, the first matching location is used to drive origin-country-based estimated
            arrival and, for `PASS_THROUGH` pricing, the carrier rate quote. Each entry may be a
            free-form address, or, for a configured Carriyo location, supply `partner_location_code`
            (your own code, **recommended**) or `partner_location_id` (Carriyo's internal ID), and
            the rest of the address is populated from the location record.
          items:
            $ref: '#/components/schemas/delivery-options-address'
        customer:
          allOf:
            - $ref: '#/components/schemas/delivery-options-address'
          description: |-
            The customer's location. Drives customer-geography conditions and the timezone used for
            working-day / blackout-day evaluation. Strongly recommended for any non-trivial result.


            For `DELIVERY` options this is also the implicit delivery destination. For `COLLECTION`
            options it's used to find applicable collection points. The shopper has not chosen
            between the two at this stage; the field captures *where the customer is*, not *where
            the order is being delivered*.
        carriyo_metadata:
          type: array
          description: |-
            Custom name/value pairs attached to the order. Stored on the order but not currently
            used by condition evaluation.
          items:
            $ref: '#/components/schemas/carriyo-metadata-entry'
        delivery_methods:
          type: array
          description: |-
            Restrict the response to options of the listed methods. When omitted or empty, all
            methods are returned. Useful when the storefront has separate UI tabs for delivery and
            click-and-collect, or when the integration only supports one method (e.g., Shopify's
            standard Carrier Service API has no pickup-point concept, so the Shopify connector
            sets this to `["DELIVERY"]`).
          items:
            type: string
            enum:
              - DELIVERY
              - COLLECTION
              - DIGITAL
          example:
            - DELIVERY
            - COLLECTION
        max_collection_locations:
          type: integer
          minimum: 0
          maximum: 50
          default: 10
          description: |-
            Maximum number of customer collection locations to return per matching `COLLECTION`
            option. Defaults to 10 when omitted; capped server-side at 50. Ignored for `DELIVERY`
            and `DIGITAL` options.
        max_collection_distance:
          allOf:
            - $ref: '#/components/schemas/distance'
          description: |-
            Client-supplied upper bound on the distance from the customer's location to a returned
            collection point. The effective cap used by Carriyo is the smaller of this value and any
            per-option `customer_collection_max_distance` configured by the merchant. When the
            customer's coordinates aren't supplied, this cap can't be enforced and is ignored.
      required:
        - merchant
    delivery-options-response-item:
      title: Delivery Option
      type: object
      description: A delivery option that matched the supplied order.
      properties:
        id:
          type: string
          description: Unique identifier for this delivery option.
        delivery_method:
          type: string
          enum:
            - COLLECTION
            - DELIVERY
            - DIGITAL
          description: |-
            The fulfilment method for this option:
            - `DELIVERY`: courier delivers to the customer's address.
            - `COLLECTION`: customer collects from a designated location.
            - `DIGITAL`: no physical fulfilment.

            Aligns with `FulfillmentOrder.delivery_method` on the order model.
        code:
          type: string
          description: The merchant-defined code identifying the delivery option.
        name:
          type: string
          description: Display name of the delivery option (shown to the shopper).
        description:
          type: string
        image_url:
          type: string
          description: URL to an icon or image associated with the option.
        carrier_account_id:
          type: string
          description: The Carriyo carrier account that fulfils this option.
        shipping_fee:
          $ref: '#/components/schemas/delivery-options-shipping-fee'
        estimated_arrival_from:
          type: string
          format: date-time
          description: Earliest estimated arrival date/time (ISO 8601).
        estimated_arrival_to:
          type: string
          format: date-time
          description: Latest estimated arrival date/time (ISO 8601).
        customer_collection_locations:
          type: array
          description: |-
            Eligible collection points for this option. Populated only when `delivery_method` is
            `COLLECTION`. Sorted nearest-first when the customer's coordinates are supplied;
            otherwise returned in the merchant-configured order. May be empty if the option has no
            linked locations or none are within the effective distance cap.
          items:
            $ref: '#/components/schemas/customer-collection-location'
    distance:
      title: Distance
      type: object
      description: A distance value with an explicit unit.
      properties:
        value:
          type: number
          format: double
          minimum: 0
          example: 5
        unit:
          type: string
          enum:
            - km
            - mi
          default: km
          description: 'Unit of measurement: `km` for kilometres, `mi` for miles.'
      required:
        - value
        - unit
    customer-collection-location:
      title: Customer Collection Location
      type: object
      description: |-
        A configured Carriyo location at which the customer can collect their order. Returned only
        for `COLLECTION` delivery options. Locations are filtered to those flagged with
        `collection_location: true` and `status: ACTIVE`.
      properties:
        location_id:
          type: string
          description: Carriyo's internal location identifier.
          example: loc-dxb-marina
        location_code:
          type: string
          description: The merchant's own location code, set when the location was created.
          example: STORE-DXB-MARINA
        location_name:
          type: string
          description: Display name of the location.
          example: ACME Marina Mall Store
        address1:
          type: string
        address2:
          type: string
        city:
          type: string
          example: DUBAI
        state:
          type: string
          example: DUBAI
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          example: AE
        postcode:
          type: string
        area:
          type: string
          example: DUBAI-MARINA
        coords:
          type: array
          items:
            type: number
          description: Latitude and longitude as `[lat, lng]`.
          example:
            - 25.078
            - 55.144
        distance:
          allOf:
            - $ref: '#/components/schemas/distance'
          description: |-
            Distance from the customer's location to this collection point. Present only when both
            the customer's coordinates and the location's coordinates are available. The unit
            matches the unit supplied in `max_collection_distance` (defaults to `km` when the
            request didn't specify).
    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
    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
    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'
    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
    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
    location-request:
      title: Location Request
      type: object
      description: |-
        Identifies a configured Carriyo location. Supply either `partner_location_code` (your own
        user-defined code, **recommended for storefront integrations** since it's stable in your
        systems) or `partner_location_id` (Carriyo's internal ID). One of the two is required.
      properties:
        partner_location_code:
          type: string
          description: |-
            Your own location code, as defined when you created the location in Carriyo.
            Recommended for storefront and merchant-side integrations because it's user-defined
            and stable in your own systems.
        partner_location_id:
          type: string
          description: Carriyo's internal location ID. Use when you've already stored the Carriyo ID.
    shipping-rate-location-request:
      title: Shipping Rate Location Request
      description: Provide geography information
      type: object
      properties:
        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
      required:
        - city
        - country
    shipping-rate-item-request:
      title: Item
      type: object
      properties:
        sku:
          type: string
          description: SKU ID of the item. Only required when you are passing parcel_items in the parcel.
        product_item_code:
          type: string
          description: |-
            Use your product item code from your product items list, this will be used for shipment
            item enhancement.
        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.
    shipping-rate-parcel-request:
      title: Parcel Request
      type: object
      description: List of parcels in a B2C shipment.
      maximum: 250
      properties:
        weight:
          $ref: '#/components/schemas/weight'
        dimension:
          $ref: '#/components/schemas/dimension'
        parcel_items:
          type: array
          items:
            $ref: '#/components/schemas/parcel-item'
    shipping-rate-package-object:
      title: Package object
      type: object
      description: List of packages of type pallet or carton in a B2B shipment.
      maximum: 250
      properties:
        type:
          enum:
            - pallet
            - carton
        weight:
          $ref: '#/components/schemas/weight'
        dimension:
          $ref: '#/components/schemas/dimension'
    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.
    shipping-rate:
      type: object
      description: |-
        Shipping Rate based on either the costing profile you have configured for the carrier or
        carrier costing api response
      properties:
        estimated_shipping_cost:
          $ref: '#/components/schemas/estimated-shipping-cost'
        carrier:
          type: string
          example: UPS
        carrier_account_id:
          type: string
          example: ca584701-f531-482f-ab40-923dca644127
        carrier_account_name:
          type: string
          example: UPS - Dubai
        service_name:
          type: string
        service_description:
          type: string
        delivery_promise:
          type: string
        estimated_days:
          type: integer
        error_details:
          type: array
          items:
            $ref: '#/components/schemas/error-detail'
    delivery-options-shipping-fee:
      title: Delivery Options Shipping Fee
      type: object
      properties:
        amount:
          type: number
          format: double
        currency:
          type: string
          description: ISO 4217 three-letter currency code.
    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'
    weight:
      title: Weight
      type: object
      properties:
        value:
          type: number
        unit:
          type: string
          enum:
            - kg
          description: Default weight unit is `kg` if not provided.
    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.
    parcel-item:
      title: Parcel Item
      type: object
      properties:
        sku:
          type: string
        quantity:
          type: integer
    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'
    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'
    delivery-options-payment:
      title: Delivery Options Payment
      type: object
      description: Payment details for the order. Drives `order_value` and `payment_type` conditions.
      properties:
        currency:
          type: string
          description: ISO 4217 three-letter currency code.
          example: AED
        order_total:
          type: number
          format: double
          description: |-
            Total order value. Compared against `order_value` range conditions on each delivery
            option.
          example: 285
        payment_on_delivery:
          type: number
          format: double
          description: |-
            Amount payable on delivery. A value greater than zero is treated as Cash on Delivery
            (`payment_type` = `CASH_ON_DELIVERY`); zero or absent is treated as `PRE_PAID`. Omit
            this field for prepaid orders.
          example: 199
    delivery-options-line-item:
      title: Delivery Options Line Item
      type: object
      description: |-
        A single line item in the order. Only the fields read by **condition matching** are listed
        here.


        Additional line-item fields accepted by Carriyo's order model (such as `description`,
        `origin_country`, `unit_price`, `unit_cost`, `hs_code`, `barcode`, `image_link`,
        `manufacturer_id`, `material_composition`, `category`, `dangerous_goods`, `battery`,
        `taxes`, and `duties`) are accepted on this endpoint and forwarded to the carrier rate
        calculator when a matching option uses the `PASS_THROUGH` pricing strategy. They do not
        affect which options match.
      properties:
        id:
          type: string
          description: Your line item identifier.
        sku:
          type: string
        product_id:
          type: string
        product_ref:
          type: string
        quantity:
          type: integer
          description: Number of units of this item. Defaults to 1.
        weight:
          allOf:
            - $ref: '#/components/schemas/weight'
          description: |-
            Total weight contributed by this line item. Used to evaluate weight range conditions;
            required when an option has such a condition configured.


            Note that `quantity` is not multiplied with this value during weight evaluation; supply
            the total weight for the line.
    delivery-options-parcel:
      title: Delivery Options Parcel
      type: object
      properties:
        weight:
          $ref: '#/components/schemas/weight'
        dimension:
          $ref: '#/components/schemas/dimension'
    delivery-options-address:
      title: Delivery Options Address
      type: object
      description: |-
        Address used to evaluate geography-based conditions and (for `fulfillment_locations`)
        location-based routing. Only `country`, `state`, `city`, and `area` are needed for condition
        evaluation; additional contact and street-level fields are accepted and may be useful for
        downstream order persistence.


        For a pre-configured Carriyo location, supply `partner_location_code` (your own code,
        **recommended**) or `partner_location_id` (Carriyo's internal ID), and Carriyo will populate
        the remaining address fields from the location record.
      properties:
        partner_location_id:
          type: string
          description: |-
            Carriyo's internal location ID. When supplied, the rest of the address is populated
            from the configured location record (any other address fields supplied alongside are
            overridden by the location's data).


            Primarily intended for `fulfillment_locations` entries (configured warehouses or
            stores). It is also honoured on `customer` for completeness, but a customer's location
            is rarely a Carriyo-configured location.
          example: warehouse-dxb-01
        partner_location_code:
          type: string
          description: |-
            Your own location code, as defined when you created the location in Carriyo.
            Recommended for storefront and merchant-side integrations because it's user-defined
            and stable in your own systems. When supplied, Carriyo populates the remaining address
            fields from the configured location record.
          example: store-ad-marina-mall
        partner_location_name:
          type: string
          description: Display name of the configured location. Read-only; populated by Carriyo when the location is resolved via `partner_location_id` or `partner_location_code`.
        country:
          type: string
          description: |-
            Two-letter ISO 3166-1 alpha-2 country code. Required for evaluating geography
            conditions; for the `customer` field, also used to resolve the timezone for working-day
            and blackout-day evaluation.
          example: AE
        state:
          type: string
          description: State, province, or region. Use the Carriyo State Code where available.
          example: DUBAI
        city:
          type: string
          description: City. Use the Carriyo City Code where available.
          example: DUBAI
        area:
          type: string
          description: District, suburb, or neighbourhood. Use the Carriyo Area Code where available.
          example: DOWNTOWN-DUBAI
        postcode:
          type: string
        address1:
          type: string
        address2:
          type: string
        contact_name:
          type: string
        contact_phone:
          type: string
        contact_email:
          type: string
        coords:
          type: array
          items:
            type: number
          description: Latitude and longitude as `[lat, lng]`.
          example:
            - 25.19741
            - 55.27442
    carriyo-metadata-entry:
      title: Carriyo Metadata Entry
      type: object
      properties:
        name:
          type: string
        value:
          type: string
    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
    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'
    registration-numbers:
      title: Registration Numbers
      type: array
      items:
        $ref: '#/components/schemas/registration-number'
    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
    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-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).
    string-condition:
      title: String condition
      type: object
      description: A condition that matches one or more string values against a Carriyo field.
      properties:
        operator:
          type: string
          enum:
            - EQUALS
            - NOT_EQUALS
            - IN
            - NOT_IN
            - ANY
          description: Match operator. `ANY` matches everything (the condition is effectively absent).
        values:
          type: array
          items:
            type: string
          description: Values to compare against. Used with `IN` / `NOT_IN`; for `EQUALS` / `NOT_EQUALS` provide a single-item array.
    number-area-condition:
      title: Number area condition
      type: object
      description: A condition that matches a numeric Carriyo field against a range, threshold, or set.
      properties:
        operator:
          type: string
          enum:
            - EQUALS
            - NOT_EQUALS
            - GREATER_THAN
            - LESS_THAN
            - BETWEEN
            - ANY
          description: Match operator.
        min:
          type: number
          description: Lower bound (inclusive). Used with `BETWEEN`, `GREATER_THAN`.
        max:
          type: number
          description: Upper bound (inclusive). Used with `BETWEEN`, `LESS_THAN`.
        value:
          type: number
          description: Exact value. Used with `EQUALS`, `NOT_EQUALS`.
    country-states-condition-v2:
      title: Country / states condition
      type: object
      description: A condition that matches a shipment geography (country, optionally constrained to specific states / cities / areas) against one or more entries.
      properties:
        operator:
          type: string
          enum:
            - IN
            - NOT_IN
            - ANY
          description: Match operator.
        values:
          type: array
          items:
            $ref: '#/components/schemas/country-states-entry'
          description: Country / states / cities / areas entries.
    country-states-entry:
      title: Country / states condition entry
      type: object
      description: A country plus an optional subset of states / cities / areas within it.
      properties:
        country:
          type: string
          description: Two-letter ISO 3166-1 alpha-2 country code.
        states:
          type: array
          items:
            type: string
        cities:
          type: array
          items:
            type: string
        areas:
          type: array
          items:
            type: string
    carrier-schedule:
      title: Carrier schedule
      type: object
      description: 'Carrier or delivery-option operating schedule: working days/hours, blackout dates.'
      properties:
        schedule_by:
          type: string
          enum:
            - DAY
            - PERIOD
          description: Whether the schedule applies per day-of-week or per fixed period.
        working_days:
          type: array
          items:
            type: object
            description: 'Working-day entry: day-of-week plus its time windows.'
            additionalProperties: true
          description: Recurring weekly working days.
        working_period:
          type: object
          description: 'Fixed date range during which the schedule is active. Shape: {from, to} dates.'
          additionalProperties: true
        blackout_days:
          type: array
          items:
            type: object
            description: 'Blackout-day entry: a date or date range.'
            additionalProperties: true
          description: Dates when the carrier or delivery option is unavailable.
    shipping-fee:
      title: Shipping fee
      type: object
      description: Pricing configuration for a delivery option.
      properties:
        pricing_strategy:
          type: string
          enum:
            - FIXED
            - TIERED
            - DYNAMIC
          description: How the fee is computed.
        calculation_method:
          type: string
          enum:
            - ORDER_VALUE
            - ORDER_WEIGHT
            - ORDER_VOLUME
          description: For tiered/dynamic strategies, the variable used.
        default_currency:
          type: string
          description: ISO 4217 currency code used when a request does not specify one.
        pricing:
          type: array
          items:
            type: object
            description: 'Per-currency pricing entry, with tier and threshold pricing.'
            additionalProperties: true
          description: Per-currency pricing definitions.
    delivery-estimation:
      title: Delivery estimation
      type: object
      description: Configuration for how Carriyo estimates the delivery time shown to customers for this option.
      properties:
        dynamic_estimation_enabled:
          type: boolean
          description: True to compute estimates dynamically from carrier SLA; false to use static service-level values.
        service_level:
          type: object
          description: 'Static service-level estimate. Shape: {min, max, unit} or richer; see EstimationSLA in the backend.'
          additionalProperties: true
    delivery-option:
      title: Delivery option
      type: object
      description: A merchant-configured delivery option presented to the customer at checkout. Drives carrier selection, pricing, schedule, and the geography in which the option is available.
      properties:
        id:
          type: string
          description: Carriyo-issued identifier. Server-assigned on create.
          readOnly: true
        code:
          type: string
          description: Merchant-supplied code used as the option's stable identifier (e.g. `EXPRESS_AE`).
        name:
          type: string
          description: Human-readable display name shown to the customer.
        description:
          type: string
          description: Optional longer description shown to the customer.
        image_url:
          type: string
          description: URL of an icon / illustration for the option.
        delivery_method:
          type: string
          enum:
            - DELIVERY
            - COLLECTION
            - DIGITAL
          description: Delivery method (home delivery, customer pickup, or digital fulfilment).
        merchant:
          type: string
          description: Merchant the option belongs to.
        carrier_account_id:
          type: string
          description: Carrier account that fulfils shipments booked via this option.
        status:
          type: string
          enum:
            - ACTIVE
            - INACTIVE
          description: Option status.
        schedule:
          allOf:
            - $ref: '#/components/schemas/carrier-schedule'
          description: Working days / blackout dates for this option.
        shipping_fee:
          allOf:
            - $ref: '#/components/schemas/shipping-fee'
          description: Pricing configuration.
        delivery_estimation:
          allOf:
            - $ref: '#/components/schemas/delivery-estimation'
          description: Customer-facing delivery-time estimation configuration.
        order_value:
          allOf:
            - $ref: '#/components/schemas/number-area-condition'
          description: Make the option visible only when order value is in range.
        weight:
          allOf:
            - $ref: '#/components/schemas/number-area-condition'
          description: Make the option visible only when total weight is in range.
        payment_type:
          allOf:
            - $ref: '#/components/schemas/string-condition'
          description: Make the option visible only for matching payment types.
        customer:
          allOf:
            - $ref: '#/components/schemas/country-states-condition-v2'
          description: Make the option visible only when the customer address falls in matching country / states / cities / areas.
        fulfillment_locations:
          type: array
          items:
            type: string
          description: Carriyo location codes/IDs eligible to fulfil this option.
        customer_collection_locations:
          type: array
          items:
            type: string
          description: 'For `COLLECTION` methods: location codes/IDs where the customer can collect from.'
        customer_collection_max_distance:
          allOf:
            - $ref: '#/components/schemas/distance'
          description: 'For `COLLECTION` methods: maximum distance from the customer to a candidate collection location.'
        updated_by_user:
          type: string
          description: User identifier (email) of the last updater. Read-only.
          readOnly: true
        creation_date:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601).
          readOnly: true
        update_date:
          type: string
          format: date-time
          description: Last update timestamp (ISO 8601).
          readOnly: true
