Storefront API

Returns live shipping rates from eligible carriers for a future shipment. Stateless: no shipment is created.

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

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.

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

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

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.