Get Delivery Options

Returns the delivery options that match a given order or cart 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 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 — 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.

Identifying the order

Provide one of the following:

Field When to use
order Inline order details, when no order has been created in Carriyo yet — the typical live checkout flow.
order_id Carriyo's internal order ID, when the order already exists in Carriyo.
partner_order_reference Your own reference for an order that already exists in Carriyo.

When order_id or partner_order_reference is supplied, Carriyo loads the persisted order and uses its data for condition evaluation. When order is supplied, only the fields required by the conditions you've configured need to be present.

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.order_date (defaults to now); timezone derived from order.customer.country
Customer geography order.customer.{country, state, city, area}
Order value range order.payment.order_total
Weight range Sum of order.line_items[].weight (converted to kg)
Payment type Derived: CASH_ON_DELIVERY if order.payment.payment_on_delivery > 0, otherwise PRE_PAID
Fulfillment location order.fulfillment_location (free-form, or partner_location_id for a configured Carriyo location)

Response

An array of matching delivery options, each with its carrier account, computed shipping fee, and estimated arrival window. The array is empty if no configured option matches the supplied order.

SecurityOAuth2-Production or OAuth2-Demo
Request
header Parameters
x-api-key
required
string
tenant-id
required
string
Content-Type
required
string
Default: application/json
Request Body schema: application/json
required
order_id
string

The Carriyo order ID. Use this to evaluate delivery options for an order that already exists in Carriyo. When supplied, Carriyo loads the order's customer address, items, payment, and fulfillment locations from storage.

partner_order_reference
string

Your own reference for an order that already exists in Carriyo. Equivalent to order_id but uses your reference instead of Carriyo's internal ID.

object (Delivery Options Order)

Inline order details used to evaluate delivery option conditions when the order has not yet been persisted in Carriyo. Only merchant is strictly required; populate the remaining fields based on which conditions the merchant has configured (see the operation description).

Responses
200

The delivery options that match the supplied order.

post/checkout/delivery-options
Request samples
application/json

The most common scenario. A shopper is at checkout, no order yet exists in Carriyo. The request supplies 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 — Carriyo will fall back to the merchant's default sourcing.

{
  • "order": {
    }
}
Response samples
application/json

Three options are returned: two DELIVERY options and one COLLECTION option (customer collects from a store).

Known limitation: the response does not currently include the collection-point address for COLLECTION options. The shopper's UI typically resolves the collection point separately (e.g., a store locator keyed off the same merchant + customer geography). This is being tracked as a separate enhancement.

[
  • {
    },
  • {
    },
  • {
    }
]