openapi: 3.0.1
info:
  title: Carriyo Storefront API
  version: '1.0'
  description: |-
    Shopper-facing lookups that power delivery choices on your webstore or app. Fetch the delivery options a shopper can pick, live carrier rates for a route, a per-product delivery promise for product pages, the eligible fulfillment or collection locations near a customer, and phone-number validation. Every call is stateless: none of them creates an order or 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: storefront
    description: |-
      Shopper-facing evaluations for your webstore or app. Given a cart, a product, or a customer location, these lookups return the delivery choices, rates, promises, and pickup or fulfillment locations to show the shopper.

      They are stateless: no order or shipment is created. Storefront frontends and headless commerce middleware call them, so they run at higher volume than the per-shipment management endpoints. To manage the delivery options behind these lookups, see the delivery-options endpoints in the Core API.
paths:
  /storefront/shipping-rates:
    post:
      summary: Get shipping rates
      tags:
        - storefront
      operationId: get-shipping-rates
      parameters:
        - name: include_errors
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Include per-carrier `error_details` for carriers that failed to return a rate.
        - name: include_breakdown
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Include the line-by-line cost `breakdown` in each rate's `estimated_shipping_cost`.
        - name: include_markup
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Include configured markup in the returned 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.
  /storefront/delivery-options:
    post:
      summary: Get delivery options
      tags:
        - storefront
      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 | Total order weight: sum of `line_items[].weight × quantity` (converted to
        kg) |

        | Payment type | Derived from `payment.payment_on_delivery`: `CASH_ON_DELIVERY` when it is
        greater than 0, otherwise `PRE_PAID` |

        | Product categories | The line-item categories in the cart. Each category is resolved
        request-first (`line_items[].category`), then from the product catalog by `product_id`. An
        includes rule matches when a listed category is present; an excludes rule matches when none
        of the listed categories are present. Matching is case-insensitive |

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


        ### Sorting the results


        Results are always **coverage-banded** first. Options that cover all line items come before
        options that cover only some; within the partial band, options are ordered by how many line
        items they cover (most first). This keeps the choices a shopper can fully order at the top.


        Within each band, `sort_by` orders the options:


        - `SPEED` (default): earliest `estimated_arrival_to` first.

        - `COST`: lowest shipping fee first.


        ### 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).


        ### Stock-aware filtering


        Set `inventory_check` to `true` to filter delivery options by real-time stock. Filtering is
        **effective** only when all of the following hold:


        1. `inventory_check` is `true` in the request.

        2. Inventory management is enabled for the tenant in Carriyo settings.

        3. The line items carry a `product_id` (the stock key).


        When effective, each delivery option in the response includes:


        - **`items`** — only the line items for which sufficient stock exists at locations eligible
        for that option. Items without available inventory are excluded.

        - **`fulfillment_locations`** — the locations that can fulfill the listed items, as
        `{partner_location_id, partner_location_code, partner_location_name}` objects. This is the
        intersection of the option's configured locations and the locations that hold stock.


        Location eligibility honors each location's fulfillment coverage, the same zone and radius
        gating described in [Get eligible locations](#operation/get-eligible-locations). Radius
        coverage is matched by distance, so it needs `customer.coords` in the request. Without
        customer coordinates, a radius-covered location is never eligible and its stock is
        invisible to this endpoint. Pass customer coordinates whenever the merchant fulfills from
        radius-covered locations.


        Delivery options that cannot fulfill **any** of the requested items are omitted entirely
        from the response.


        When stock-aware filtering is **not** effective (`inventory_check` is false or omitted,
        inventory management is disabled, or no `product_id` is supplied), the endpoint does not
        filter on stock:


        - **`items`** echoes back all request line items with a non-blank `id`.

        - **`fulfillment_locations`** returns the option's configured fulfillment locations as
        `{partner_location_id, partner_location_code, partner_location_name}` objects (or is
        omitted if none are configured).


        ### Response


        An array of matching delivery options, each with its carrier account, computed shipping fee,
        and estimated arrival window, coverage-banded then ordered by `sort_by`. 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
              Inventory-aware Checkout:
                summary: Checkout with stock filtering via inventory_check
                description: |-
                  Set `inventory_check` to `true` and supply `product_id` on each line item. With
                  inventory management enabled for the tenant, Carriyo checks real-time stock at
                  each candidate fulfillment location. The response only includes options that can
                  fulfill at least one item, and each option's `items` and `fulfillment_locations`
                  fields reflect actual stock availability.
                value:
                  merchant: ACME
                  inventory_check: true
                  sort_by: SPEED
                  payment:
                    currency: AED
                    order_total: 350
                  customer:
                    country: AE
                    state: DUBAI
                    city: DUBAI
                    area: DOWNTOWN-DUBAI
                  fulfillment_locations:
                    - partner_location_code: warehouse-dxb-01
                    - partner_location_code: store-ad-marina-mall
                  line_items:
                    - id: line-1
                      sku: TSHIRT-BLK-M
                      product_id: PROD-001
                      quantity: 2
                      weight:
                        value: 0.5
                        unit: kg
                    - id: line-2
                      sku: JEANS-W32-L32
                      product_id: PROD-002
                      quantity: 1
                      weight:
                        value: 0.6
                        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:
                Inventory-aware Response:
                  summary: Response with inventory-filtered items and fulfillment locations
                  description: |-
                    When inventory management is active, each option includes `items` (the line
                    items it can fulfill) and `fulfillment_locations` (where stock is available).
                    Options that can't fulfill any item are omitted. In this example, the
                    Same Day option only has stock for line-1 at warehouse-dxb-01, while the
                    Standard option can fulfill both items from both locations.
                  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'
                      items:
                        - line_item_id: line-1
                          quantity: 2
                        - line_item_id: line-2
                          quantity: 1
                      fulfillment_locations:
                        - partner_location_id: loc-dxb-wh-01
                          partner_location_code: warehouse-dxb-01
                          partner_location_name: ACME Dubai Warehouse
                        - partner_location_id: loc-ad-marina
                          partner_location_code: store-ad-marina-mall
                          partner_location_name: ACME Marina Mall Store
                    - delivery_method: DELIVERY
                      code: SAME_DAY
                      name: Same Day Delivery
                      description: Order before 12pm for same day
                      carrier_account_id: ca-fetchr-uae-001
                      shipping_fee:
                        amount: 35
                        currency: AED
                      estimated_arrival_from: '2026-05-05T14:00:00.000Z'
                      estimated_arrival_to: '2026-05-05T20:00:00.000Z'
                      items:
                        - line_item_id: line-1
                          quantity: 2
                      fulfillment_locations:
                        - partner_location_id: loc-dxb-wh-01
                          partner_location_code: warehouse-dxb-01
                          partner_location_name: ACME Dubai Warehouse
                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
  /storefront/validate/phone:
    post:
      summary: Validate a phone number
      tags:
        - storefront
      operationId: validate-phone
      description: |-
        Validates a customer phone number and returns its parsed parts.


        Carriyo parses the number with libphonenumber. Pass the number and, when the number is in
        national format, the country whose dialling rules apply. Use this at checkout to catch a
        mistyped number before the shopper places the order.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/validate-phone-request'
            examples:
              International format:
                summary: E.164 number, no country needed
                value:
                  phone_number: '+14155552671'
              National format:
                summary: National number with country
                value:
                  phone_number: '2079460958'
                  country: GB
      responses:
        '200':
          description: The parsed phone number and whether it is valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/validate-phone-response'
              examples:
                Valid:
                  summary: A valid UK number
                  value:
                    is_valid: true
                    national_number: '2079460958'
                    country_code: GB
                    raw_input: '2079460958'
                Invalid:
                  summary: A number that failed validation
                  value:
                    is_valid: false
  /storefront/product-delivery-options:
    post:
      summary: Get per-product delivery options
      tags:
        - storefront
      operationId: get-product-delivery-options
      description: |-
        Returns the delivery options available for each product in a list, so you can show a
        delivery promise (for example "Get it in 45 minutes") on a product listing or product
        detail page.


        Unlike [Get delivery options](#operation/get-delivery-options), which evaluates one cart as
        a whole, this endpoint evaluates each product on its own from its own fulfillment location.
        Send the products and the location each one ships from; Carriyo returns the matching
        delivery options per product.


        ### Choosing the fulfillment location


        Set `fulfillment_locations` at the top level as the default for every product, and override
        it per product under `products[].fulfillment_locations`. Reference a configured Carriyo
        location by `partner_location_id` or `partner_location_code`. To find the nearest eligible
        locations for a customer first, call [Get eligible
        locations](#operation/get-eligible-locations).


        ### Category and value


        Each product's `category` is resolved request-first (`products[].category`), then from the
        product catalog by `product_id`. The product's value is `unit_price × quantity`. Both feed
        the same option conditions as the cart endpoint. Options priced `PASS_THROUGH` (a live
        carrier quote) are omitted from this endpoint.


        ### Stock


        Set `inventory_check` to `true` to return `available_quantity` per product. It is effective
        only when inventory management is enabled for the tenant.


        When the check is effective, availability also honors each location's fulfillment coverage
        (zones or radius, as described in [Get eligible
        locations](#operation/get-eligible-locations)). A location outside coverage reports
        `available_quantity: 0` and offers no delivery options. Radius coverage is matched by
        distance, so it needs `customer.coords`: pass customer coordinates when working with
        radius-covered locations.


        ### Limits


        - At most 50 products per request.

        - At most 5 fulfillment locations per product.

        - Duplicate `product_id` values are rejected.


        ### Response


        A bare array, one entry per (product, resolved fulfillment location) pair — a product with
        several resolved locations yields one row per location. Each row carries the resolved
        `location` and its `delivery_options` sorted by `sort_by` / `sort_direction`. Rows whose
        `delivery_options` is empty are kept (for example when a location can't meet the requested
        quantity under `inventory_check`), so every requested product is represented.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/product-delivery-options-request'
            examples:
              Two products from a store:
                summary: A PLP request for two products from the nearest store
                value:
                  merchant: ACME
                  currency: AED
                  inventory_check: true
                  sort_by: SPEED
                  sort_direction: ASC
                  customer:
                    country: AE
                    state: DUBAI
                    city: DUBAI
                    area: DOWNTOWN-DUBAI
                    coords:
                      - 25.197
                      - 55.274
                  fulfillment_locations:
                    - partner_location_code: store-dxb-downtown
                  products:
                    - product_id: PROD-001
                      sku: TSHIRT-BLK-M
                      quantity: 1
                      unit_price: 79
                      category: apparel
                    - product_id: PROD-002
                      sku: SHOES-RUN-42
                      quantity: 1
                      unit_price: 320
                      category: footwear
                      weight:
                        value: 0.9
                        unit: kg
      responses:
        '200':
          description: The delivery options available for each product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/product-delivery-options-response'
              examples:
                Fastest option per product:
                  summary: Each product with its resolved location and options
                  value:
                    - product_id: PROD-001
                      quantity: 1
                      location:
                        partner_location_id: loc-dxb-downtown
                        partner_location_code: store-dxb-downtown
                        partner_location_name: ACME Downtown Dubai
                      available_quantity: 12
                      delivery_options:
                        - id: opt-express-dxb
                          delivery_method: DELIVERY
                          code: EXPRESS
                          name: Express 45 min
                          description: Delivered within the hour
                          image_url: https://cdn.example.com/icons/express.png
                          carrier_account_id: ca-fetchr-uae-001
                          shipping_fee:
                            amount: 12
                            currency: AED
                          estimated_arrival_from: '2026-05-05T14:00:00.000Z'
                          estimated_arrival_to: '2026-05-05T14:45:00.000Z'
                        - id: opt-std-dxb
                          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: 0
                            currency: AED
                          estimated_arrival_from: '2026-05-07T09:00:00.000Z'
                          estimated_arrival_to: '2026-05-09T18:00:00.000Z'
                    - product_id: PROD-002
                      quantity: 1
                      location:
                        partner_location_id: loc-dxb-downtown
                        partner_location_code: store-dxb-downtown
                        partner_location_name: ACME Downtown Dubai
                      available_quantity: 3
                      delivery_options:
                        - id: opt-std-dxb
                          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'
        '400':
          description: |-
            The request failed validation. Returned when `products` is empty or has more than 50
            entries, a `product_id` is missing or duplicated, a `quantity` is less than 1, a product
            resolves to no fulfillment locations or more than 5, or a referenced fulfillment location
            cannot be found or is not an active fulfillment location (a collection-only location is
            rejected).
  /storefront/locations:
    post:
      summary: Get eligible locations
      tags:
        - storefront
      operationId: get-eligible-locations
      description: |-
        Returns the configured Carriyo locations that can serve a customer, so you can find the
        nearest store or warehouse to fulfill from or offer for collection.


        A location is eligible when it is active, the merchant has access to it, and it carries the
        requested `functions` flag. How its geography is checked then depends on the function:


        - **`FULFILLMENT`** locations are gated by their configured coverage. Zone coverage
        (`fulfillment_zones`) qualifies a location when its zones cover the customer's country,
        state, city, or area terms. Radius coverage (`fulfillment_radius`) qualifies it when the
        customer is within the radius; this needs coordinates on both sides, so a location with
        radius coverage but no coordinates, or a request with no `customer.coords`, is ineligible. A
        fulfillment location with neither zones nor radius serves everywhere.

        - **`COLLECTION`** locations are not gated by zones or radius. A location qualifies on its
        collection flag alone; the only geographic constraint is `max_distance`, which caps how far
        a pickup point can be from the customer.


        ### Distance and selection order


        Supply `customer.coords` to get a `distance` on each location and nearest-first selection.
        The order is fixed: nearest-first when coordinates are supplied, `location_code` order
        otherwise; locations with no computable distance select last. Use `max_distance` (needs
        coordinates) to cap how far out to look.


        ### Filtering and the cap


        Filter by `location_type` (`STORE` or `WAREHOUSE`) and by `functions` (`FULFILLMENT`,
        `COLLECTION`; defaults to `[FULFILLMENT]`). One call returns the complete answer, capped by
        `max_locations` (default 10, maximum 50) — there are no pages and no way to fetch "the
        rest"; receiving exactly `max_locations` items means more may exist, so narrow the filters
        or raise the cap. `page`/`page_size` and `sort_by`/`sort_direction` are rejected with
        `400`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/eligible-locations-request'
            examples:
              Nearest stores to a customer:
                summary: Fulfillment stores near a customer, nearest first
                value:
                  merchant: ACME
                  functions:
                    - FULFILLMENT
                  location_type: STORE
                  customer:
                    country: AE
                    state: DUBAI
                    city: DUBAI
                    area: DOWNTOWN-DUBAI
                    coords:
                      - 25.197
                      - 55.274
                  max_distance:
                    value: 25
                    unit: km
                  max_locations: 20
      responses:
        '200':
          description: |-
            The eligible locations, nearest first (with coords), capped at `max_locations`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/eligible-locations-response'
              examples:
                Two nearby stores:
                  summary: Two eligible stores, nearest first
                  value:
                    - location_id: loc-dxb-downtown
                      location_code: STORE-DXB-DOWNTOWN
                      location_name: ACME Downtown Dubai
                      location_type: STORE
                      functions:
                        - FULFILLMENT
                        - COLLECTION
                      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
                      location_type: STORE
                      functions:
                        - FULFILLMENT
                      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
        '400':
          description: |-
            The request failed validation. Returned when `customer` (with a `country`) is missing,
            `max_distance` is used without `customer.coords`, `max_locations` is outside 1–50, or
            any of the unsupported `page`/`page_size`/`sort_by`/`sort_direction` fields are sent.
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_accounts
        - 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. `weight.value` is the weight of a single unit; the total weight
            for a line is `weight.value × quantity`. The total order weight used for weight range
            conditions is the sum of those per-line totals, converted to kg.


            Set `product_id` on each line to make stock-aware filtering effective (see
            `inventory_check`). Set `category` to drive product-category conditions; when omitted,
            the category is resolved from the product catalog by `product_id`.
          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*.
        inventory_check:
          type: boolean
          default: false
          description: |-
            Set to `true` to filter options by real-time stock. Effective only when inventory
            management is enabled for the tenant and the line items carry `product_id`. When not
            effective, no stock filtering is applied.
        sort_by:
          type: string
          enum:
            - SPEED
            - COST
          default: SPEED
          description: |-
            Orders the options within each coverage band. `SPEED` (default) puts the earliest
            `estimated_arrival_to` first; `COST` puts the lowest shipping fee first. Options are
            always coverage-banded before this ordering is applied.
        sort_direction:
          type: string
          enum:
            - ASC
            - DESC
          default: ASC
          description: |-
            Direction applied to `sort_by`. `ASC` (default) orders soonest/cheapest first; `DESC`
            reverses the non-null ordering. Options with no arrival estimate or fee always sort
            last regardless of direction.
        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).
        items:
          type: array
          description: |-
            The line items from the request that this delivery option can fulfill. Each entry
            identifies a line item and the quantity that can be fulfilled.


            When **stock-aware filtering is effective** (`inventory_check` is `true`, inventory
            management is enabled, and the line items carry `product_id`), this field reflects only
            the items for which sufficient stock exists at the option's eligible fulfillment
            locations. Items with insufficient stock are excluded. If no items can be fulfilled,
            the entire option is omitted from the response.


            When stock-aware filtering is **not** effective, all request line items with a
            non-blank `id` are returned here; no stock filtering is applied.


            A returned option always lists at least one fulfillable item. If the request has no
            `line_items`, the option cannot be matched to any item and is omitted from the
            response entirely rather than returned with an empty `items` list.
          items:
            $ref: '#/components/schemas/delivery-option-line-item-ref'
        fulfillment_locations:
          type: array
          description: |-
            The locations that can fulfill the items listed in `items` for this delivery option,
            each as a `{partner_location_id, partner_location_code, partner_location_name}` object.


            When **stock-aware filtering is effective**, these are the option's configured
            fulfillment locations that hold stock for the listed `items`. When at least one location
            can fulfill every listed item, only those shared locations are returned; otherwise the
            field falls back to the union of locations that can fulfill at least one item.


            When stock-aware filtering is **not** effective, this returns the option's configured
            fulfillment locations. Omitted (`null`) if the option has no configured fulfillment
            locations.
          items:
            $ref: '#/components/schemas/resolved-fulfillment-location'
        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'
    delivery-option-line-item-ref:
      title: Delivery Option Line Item
      type: object
      description: |-
        A reference to a request line item that the delivery option can fulfill, along with
        the fulfillable quantity.
      properties:
        line_item_id:
          type: string
          description: |-
            The `id` of the line item from the request's `line_items` array.
          example: line-1
        quantity:
          type: integer
          description: |-
            The quantity of this line item that can be fulfilled by this delivery option.
          example: 2
    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`, `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
          description: |-
            The product's stock identifier. Required for stock-aware filtering (see
            `inventory_check`); also used to resolve the product's category from the catalog when
            `category` is not supplied.
        product_ref:
          type: string
        category:
          type: string
          description: |-
            Product category, used to evaluate product-category conditions. Takes precedence over
            the catalog category resolved by `product_id`. Matching is case-insensitive.
        quantity:
          type: integer
          description: Number of units of this item. Defaults to 1.
        weight:
          allOf:
            - $ref: '#/components/schemas/weight'
          description: |-
            Weight of a single unit of this item. Used to evaluate weight range conditions; the
            line's contribution to total order weight is `weight.value × quantity`. Required when an
            option has a weight condition configured.
    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
    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).
    resolved-fulfillment-location:
      title: Resolved Fulfillment Location
      type: object
      description: A fulfillment location Carriyo resolved for a matched delivery option.
      properties:
        partner_location_id:
          type: string
          description: Carriyo's internal location ID.
          example: loc-dxb-wh-01
        partner_location_code:
          type: string
          description: The merchant's own location code.
          example: warehouse-dxb-01
        partner_location_name:
          type: string
          description: Display name of the location.
          example: ACME Dubai Warehouse
    validate-phone-request:
      title: Validate Phone Request
      type: object
      description: A phone number to validate, with the country whose dialling rules apply for national-format numbers.
      required:
        - phone_number
      properties:
        phone_number:
          type: string
          description: The phone number to validate. Accepts E.164 (`+<country><number>`) or national format.
          example: '+14155552671'
        country:
          type: string
          description: |-
            Two-letter ISO 3166-1 alpha-2 country code. Used to parse a national-format
            `phone_number`; not needed when the number is in E.164 format.
          example: GB
    validate-phone-response:
      title: Validate Phone Response
      type: object
      description: The result of parsing and validating a phone number with libphonenumber.
      properties:
        is_valid:
          type: boolean
          description: Whether the number is a valid, dialable number. Always present.
        national_number:
          type: string
          description: The number in national format, without the country dialling code. Present when the number parsed.
          example: '2079460958'
        country_code:
          type: string
          description: |-
            Echoes the `country` supplied in the request. Present when a country was provided
            (omitted for an E.164 number sent without a `country`).
          example: GB
        raw_input:
          type: string
          description: The `phone_number` exactly as supplied in the request. Always present.
          example: '2079460958'
    product-delivery-options-request:
      title: Product Delivery Options Request
      type: object
      description: |-
        A list of products, each with the location it ships from, to evaluate delivery options per
        product for a product listing or product detail page.
      required:
        - merchant
        - products
      properties:
        merchant:
          type: string
          description: The merchant the products belong to. The API key must have access to this merchant.
          example: ACME
        order_date:
          type: string
          format: date-time
          description: Reference date for working-day and blackout-day evaluation (ISO 8601). Defaults to the time of the request.
          example: '2026-05-05T10:30:00.000Z'
        currency:
          type: string
          description: ISO 4217 three-letter currency code for product values and returned fees.
          example: AED
        customer:
          allOf:
            - $ref: '#/components/schemas/delivery-options-address'
          description: |-
            The customer's location. Drives customer-geography conditions and the timezone for
            working-day evaluation. Supply `coords` to drive distance-based option logic.
        inventory_check:
          type: boolean
          default: false
          description: |-
            Set to `true` to return `available_quantity` per product. Effective only when inventory
            management is enabled for the tenant.
        fulfillment_locations:
          type: array
          description: |-
            Default fulfillment locations applied to every product. Reference a configured Carriyo
            location by `partner_location_id` or `partner_location_code`. Override per product under
            `products[].fulfillment_locations`.
          items:
            $ref: '#/components/schemas/location-request'
        products:
          type: array
          minItems: 1
          maxItems: 50
          description: The products to evaluate. Between 1 and 50; duplicate `product_id` values are rejected.
          items:
            $ref: '#/components/schemas/product-delivery-options-product'
        sort_by:
          type: string
          enum:
            - SPEED
            - COST
          default: SPEED
          description: Orders each product's `delivery_options`. `SPEED` by earliest arrival, `COST` by lowest fee.
        sort_direction:
          type: string
          enum:
            - ASC
            - DESC
          default: ASC
          description: Sort direction applied to `sort_by`.
    product-delivery-options-product:
      title: Product Delivery Options Product
      type: object
      description: A single product to evaluate, with its quantity, value, category, and fulfillment location.
      required:
        - product_id
      properties:
        product_id:
          type: string
          description: The product's stock identifier.
          example: PROD-001
        sku:
          type: string
          example: TSHIRT-BLK-M
        quantity:
          type: integer
          default: 1
          description: Number of units. Defaults to 1. The product value is `unit_price × quantity`.
          example: 1
        unit_price:
          type: number
          format: double
          description: Price of a single unit, in the request `currency`. Drives order-value conditions.
          example: 79
        category:
          type: string
          description: |-
            Product category, used for product-category conditions. Takes precedence over the
            catalog category resolved from `product_id`. Matching is case-insensitive.
          example: apparel
        weight:
          allOf:
            - $ref: '#/components/schemas/weight'
          description: Weight of a single unit. The total is `weight.value × quantity`.
        fulfillment_locations:
          type: array
          maxItems: 5
          description: |-
            Locations this product ships from, overriding the request-level default. At most 5.
            Reference a configured Carriyo location by `partner_location_id` or
            `partner_location_code`.
          items:
            $ref: '#/components/schemas/location-request'
    product-delivery-options-response:
      title: Product Delivery Options Response
      type: array
      description: |-
        One entry per (product, resolved fulfillment location) pair. A product with several
        resolved locations yields one row per location; every requested product is represented.
      items:
        $ref: '#/components/schemas/product-delivery-result'
    product-delivery-result:
      title: Product Delivery Result
      type: object
      description: |-
        The delivery options for one product from one of its resolved fulfillment locations. Kept
        even when `delivery_options` is empty — for example when the location can't meet the
        requested quantity under `inventory_check` — so every requested product is represented.
      properties:
        product_id:
          type: string
          example: PROD-001
        quantity:
          type: integer
          example: 1
        location:
          allOf:
            - $ref: '#/components/schemas/resolved-fulfillment-location'
          description: The fulfillment location resolved for this row.
        available_quantity:
          type: integer
          format: int64
          description: |-
            Units in stock for this product at this location. Present only when `inventory_check` is
            effective (requested and inventory management enabled for the tenant); set even when 0.
          example: 12
        delivery_options:
          type: array
          description: |-
            The delivery options for this product at this location, sorted by `sort_by` /
            `sort_direction`. Empty when no option matches or the location can't fulfill the
            requested quantity.
          items:
            $ref: '#/components/schemas/delivery-option-summary'
    delivery-option-summary:
      title: Delivery Option Summary
      type: object
      description: A delivery option available for a product, as shown on a product page.
      properties:
        id:
          type: string
        delivery_method:
          type: string
          enum:
            - DELIVERY
            - COLLECTION
            - DIGITAL
        code:
          type: string
          description: The merchant-defined code identifying the delivery option.
        name:
          type: string
          description: Display name 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).
    eligible-locations-request:
      title: Eligible Locations Request
      type: object
      description: A customer location and filters, to find the configured Carriyo locations that can serve them.
      required:
        - merchant
        - customer
      properties:
        merchant:
          type: string
          description: The merchant whose locations to search. The API key must have access to this merchant.
          example: ACME
        functions:
          type: array
          description: The location functions required. Defaults to `[FULFILLMENT]`.
          items:
            type: string
            enum:
              - FULFILLMENT
              - COLLECTION
          default:
            - FULFILLMENT
        customer:
          $ref: '#/components/schemas/eligible-locations-customer'
        location_type:
          type: string
          enum:
            - STORE
            - WAREHOUSE
          description: Restrict to stores or warehouses. Omit to include both.
        max_distance:
          allOf:
            - $ref: '#/components/schemas/distance'
          description: Upper bound on distance from the customer. Requires `customer.coords`.
        max_locations:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
          description: |-
            Cap on returned locations. The response is one complete, capped answer in fixed
            selection order (nearest-first with `customer.coords`, `location_code` order
            otherwise) — there are no pages. Receiving exactly `max_locations` items means more
            may exist; narrow the filters or raise the cap.
    eligible-locations-customer:
      title: Eligible Locations Customer
      type: object
      description: The customer location used to evaluate location coverage and distance.
      required:
        - country
      properties:
        country:
          type: string
          description: Two-letter ISO 3166-1 alpha-2 country code.
          example: AE
        state:
          type: string
          example: DUBAI
        city:
          type: string
          example: DUBAI
        area:
          type: string
          example: DOWNTOWN-DUBAI
        coords:
          type: array
          items:
            type: number
          description: Latitude and longitude as `[lat, lng]`. Required for distance sorting and radius coverage.
          example:
            - 25.197
            - 55.274
    eligible-locations-response:
      title: Eligible Locations Response
      type: array
      description: |-
        The eligible locations for the customer, capped at `max_locations`, in fixed selection
        order (nearest-first when `customer.coords` was supplied, `location_code` order
        otherwise).
      items:
        $ref: '#/components/schemas/eligible-location'
    eligible-location:
      title: Eligible Location
      type: object
      description: A configured Carriyo location eligible to serve the customer.
      properties:
        location_id:
          type: string
          description: Carriyo's internal location identifier.
          example: loc-dxb-downtown
        location_code:
          type: string
          description: The merchant's own location code.
          example: STORE-DXB-DOWNTOWN
        location_name:
          type: string
          example: ACME Downtown Dubai
        location_type:
          type: string
          enum:
            - STORE
            - WAREHOUSE
        functions:
          type: array
          items:
            type: string
            enum:
              - FULFILLMENT
              - COLLECTION
        custom_attributes:
          $ref: '#/components/schemas/custom-attributes'
        address1:
          type: string
        address2:
          type: string
        city:
          type: string
          example: DUBAI
        state:
          type: string
          example: DUBAI
        country:
          type: string
          description: Two-letter ISO 3166-1 alpha-2 country code.
          example: AE
        postcode:
          type: string
        area:
          type: string
          example: DOWNTOWN-DUBAI
        coords:
          type: array
          items:
            type: number
          description: Latitude and longitude as `[lat, lng]`.
          example:
            - 25.197
            - 55.274
        distance:
          allOf:
            - $ref: '#/components/schemas/distance'
          description: Distance from the customer. Null when either side has no coordinates.
    eligible-locations-pagination:
      title: Eligible Locations Pagination
      type: object
      description: Paging metadata for an eligible-locations result.
      properties:
        total:
          type: integer
          description: Total number of eligible locations across all pages.
        page:
          type: integer
          description: The zero-based page number returned.
        page_size:
          type: integer
          description: The page size used.
