Storefront API

Returns the delivery options that match a cart at checkout, evaluated against the merchant's configured conditions.

Behavior

What to send

merchant and at least one line item are required. Every other field is read only when a configured condition needs it:

• order_date for working and blackout days
• customer for geography
• payment.order_total for order value
• payment.payment_on_delivery for payment type
• line-item weights for weight
• line-item categories for product and item_product_categories conditions

Line items resolve to catalog products by product_ref or product_id. sku is not a lookup key; it only supplies the line's id when you omit one. A line that matches no catalog product is not rejected: it stays unresolved and is never stock-evaluated.

customer is where the shopper is: the delivery destination for DELIVERY options and the anchor for each COLLECTION option's collection points. All three delivery methods are returned unless delivery_methods narrows them.

fulfillment_locations narrows the whole answer to the named locations: options are matched against their location allowlists, each entry lists only those locations, and its fee and estimated arrival window are computed from them. With inventory_check the stock read is narrowed too.

What comes back

Each entry carries a shipping_fee, an estimated arrival window and, for COLLECTION options, its collection points under customer_collection_locations. With inventory_check, it also carries an availability verdict per item and for the whole cart.

Each entry is a single-delivery fact: one shipping_fee, one estimated arrival window, one availability verdict, and the fulfillment_locations that can each alone provide exactly that answer. Everything it marks available ships together in one delivery from any one of those locations; an entry never claims fulfillment across several locations.

When stock was evaluated, entries are banded by availability, FULL first, then every other entry by how many line items it can supply, most first, and ordered by sort_by and sort_direction within each band. When stock was not evaluated, ordering is sort_by and sort_direction alone. With the default SPEED, the first entry is the fastest option that can deliver the whole cart, whenever stock was checked and one exists.

Shipping fee

• FREE_OF_COST options return 0.
• PAID options resolve a fixed or tiered fee.
• PASS_THROUGH options return a live carrier quote from parcels and the line items. Without parcels, or when no rate is quoted, the option is returned with an empty shipping_fee.

The request currency selects which of the option's pricing entries applies but does not force the currency of the answer. The entry is chosen in a fixed order:

1. the entry matching the request currency
2. the option's default-currency entry
3. the first configured entry, only when the option has no default currency

A configured default currency that matches no entry yields an empty fee. Always render the returned shipping_fee.currency.

• An empty shipping_fee means no price could be resolved: no tier contained the order total, no currency matched, or no carrier rate was quoted. It is not free shipping.
• A tiered fee ending in a free tier reports that tier's min_value as free_shipping_threshold, independent of the cart value, and it stays present even when the fee amount could not be resolved.
• An option whose fee lookup fails outright is dropped rather than shown unpriced.
• The fee is evaluated against the cart as sent, even on a PARTIAL entry. Requote each chosen subset with its own payment for exact per-delivery fees.

Stock (inventory_check)

The stock check runs only when inventory management is enabled and the line resolves to a catalog product. Without both, availability marks are absent, which means not evaluated rather than unavailable. A resolved product with no inventory_key reads NONE: a real answer, not an unevaluated one.

An option that can fulfill nothing is omitted. An option whose stock read failed is kept, marked UNKNOWN. The whole-cart availability is therefore FULL, PARTIAL or UNKNOWN, never NONE.

• include_variations returns each maximal single-location variation of an option as its own entry, so a caller can compose a multi-delivery checkout.
• allocation_check applies the merchant's allocation rules on top of the stock read. It defaults to the value of inventory_check; set it to false alongside inventory_check for a pure stock answer.
• fulfillment_locations narrows the stock read to the named locations.
• A radius-covered location is only eligible when customer.coords is supplied.
• An item that an option's item_product_categories condition excludes is marked NONE in every entry of that option, whether or not stock was read.

Collection points

Each COLLECTION option lists its eligible collection points. An option configured with an explicit list offers exactly those; one with no list offers every active collection location in customer.country. With customer.coords, points are sorted nearest first and bounded by the smaller of max_collection_distance and the option's configured maximum. The list is capped at max_collection_locations, 10 by default and 50 at most.

Errors

• 400 — no line items.
• 400 — a fulfillment_locations entry that resolves to no location.
• 400 — allocation_check true without inventory_check.

Validates a customer phone number and returns its parsed parts.

Behavior

Pass the number and, when the number is in national format, the country whose dialling rules apply. The call always returns 200: is_valid is always present, and country_code and national_number are omitted when the number is invalid. A blank or unparseable number returns is_valid: false.

Returns the delivery options available for each product in a list, evaluated per product from its own fulfillment location, for delivery promises on listing and product pages.

Behavior

What to send

products is required, with one to 50 entries, each naming a catalog product by product_id or product_ref and carrying between one and five fulfillment locations, its own or the request default. merchant and customer are optional. Every other field is read only when a configured condition needs it:

• order_date for working and blackout days and the estimated arrival window
• customer for geography, the allocation address and the arrival destination
• unit_price times quantity, in currency, for order value and payment type
• weight for weight
• category for product and item_product_categories conditions
• sales_channel for allocation rules only; it does not filter options

This endpoint has no delivery_methods, payment, parcels or include_variations, and no collection-point parameters.

Products resolve to catalog products by product_ref or product_id. sku is not a lookup key. Each product's category comes from the request, then from the catalog. A product that an option's item_product_categories condition excludes has that option omitted from its delivery_options.

fulfillment_locations at the top level is the default for every product, and products[].fulfillment_locations overrides it. Reference a location by partner_location_id, partner_location_code or partner_location_name.

What comes back

Every requested product is represented, even one whose delivery_options is empty. PASS_THROUGH options are omitted from this endpoint.

Each entry is a single-delivery fact: one shipping_fee, one estimated arrival window, one availability verdict, and the fulfillment_locations that can each alone provide exactly that answer. Everything it marks available ships together in one delivery from any one of those locations; an entry never claims fulfillment across several locations.

When an option's locations differ in what they can offer, the entry reports the best of them and lists only the locations sharing that answer. Best is decided in a fixed order:

• best availability verdict
• fastest estimated arrival window
• highest fulfillable_quantity
• the option's configured location order

When stock was evaluated, entries are banded by availability, FULL first, then PARTIAL, UNKNOWN and NONE, and ordered by sort_by and sort_direction within each band. When stock was not evaluated, ordering is sort_by and sort_direction alone. With the default SPEED, the first entry is the fastest option that can deliver the full quantity, whenever stock was checked and one exists.

Shipping fee

Fees resolve as they do on the cart endpoint, with the product's unit_price times quantity standing in for the order total.

The request currency selects which of the option's pricing entries applies but does not force the currency of the answer. The entry is chosen in a fixed order:

1. the entry matching the request currency
2. the option's default-currency entry
3. the first configured entry, only when the option has no default currency

A configured default currency that matches no entry yields an empty fee. Always render the returned shipping_fee.currency.

• An empty shipping_fee means no price could be resolved: no tier contained the product value, or no currency matched. It is not free shipping.
• A tiered fee ending in a free tier reports that tier's min_value as free_shipping_threshold, independent of the product value, and it stays present even when the fee amount could not be resolved.

Stock (inventory_check)

The stock check runs only when inventory management is enabled and the product resolves to a catalog product. Without both, availability and fulfillable_quantity are absent, which means not evaluated rather than unavailable. A resolved product with no inventory_key reads NONE with fulfillable_quantity 0: a real answer, not an unevaluated one.

Each entry carries an availability verdict (FULL, PARTIAL or NONE against the requested quantity) and a fulfillable_quantity capped at the requested quantity.

An option that can fulfill nothing is kept, marked NONE with fulfillable_quantity 0. An option whose stock read failed is kept, marked UNKNOWN, with no fulfillable_quantity. An option is absent only when it does not match the product or serves none of the product's fulfillment locations.

• allocation_check applies the merchant's allocation rules on top of the stock read. It defaults to the value of inventory_check; set it to false alongside inventory_check for a pure stock answer.
• Availability honors each location's fulfillment coverage: a location outside its zones or radius can only appear on entries marked NONE.
• A radius-covered location is only eligible when customer.coords is supplied.

Products not in the catalog

A product_id or product_ref that matches no product does not fail the request. The product keeps its place as an error row with delivery_options empty and error.code PRODUCT_NOT_FOUND; the row echoes the identifier you sent and omits product_id when it could not be resolved. An error row carries no availability, so treat it as not evaluated, never as out of stock. Only request-level problems fail the whole call.

Errors

• 400 — no products, or more than 50.
• 400 — a product without product_id or product_ref.
• 400 — a product requested twice.
• 400 — a quantity below 1.
• 400 — a product with no fulfillment location, or more than 5.
• 400 — a location reference resolving to nothing, or to an inactive or non-fulfillment location.
• 400 — allocation_check true without inventory_check.

Returns the active locations that can serve a customer, nearest first when coordinates are supplied, so you can choose where to fulfill from or which collection points to offer.

Behavior

What to send

merchant and customer.country are required. customer.coords is optional and unlocks distance, nearest-first order and max_distance.

Eligibility

A location qualifies when it is active, the merchant has access to it and it carries the requested function. Geography is then checked by function:

• FULFILLMENT locations are gated by their coverage. Zones qualify a location when they cover the customer's country, state, city or area. A radius needs coordinates on both sides, so a radius-covered location without coordinates, or a request without customer.coords, is ineligible. A location with neither serves everywhere.
• COLLECTION locations qualify on their collection flag alone. The only geographic constraint is max_distance.

Distance and order

With customer.coords, each location carries a distance and the list is nearest first; locations with no computable distance come last. Without coordinates the list is in location_code order. max_distance caps how far out to look and needs coordinates.

Filters

functions accepts FULFILLMENT and COLLECTION and defaults to FULFILLMENT. location_type filters by STORE or WAREHOUSE.

Cap

The call returns the complete answer capped at max_locations (default 10, maximum 50), with no paging. Receiving exactly max_locations items means more may exist, so narrow the filters or raise the cap.

Errors

• 400 — merchant missing.
• 400 — customer.country missing.
• 400 — max_distance without customer.coords.
• 400 — max_locations outside 1 to 50.
• 400 — page, page_size, sort_by or sort_direction supplied.