Delivery previews compute delivery options for a proposed cart or pickup locations for a checkout. They do not reserve stock or change a delivery selection. Both modes require commerce.delivery.read for merchant callers. Checkout credentials can use only pickup_locations for their own checkout session.
A delivery_options preview returns the same choice-group and merchant-diagnostic vocabulary used by checkout quotes. It does not reserve inventory, invoke caller-supplied pricing, or create a selectable quote. Callback pricing participates only when the callback has preview_enabled: true.
Treat evaluated_at and expires_at as the evidence window for the result. Re-run the preview after changing cart lines, destination data, buyer location, routing input, or delivery configuration.
Route#
POST /v1/delivery-previews requires mode. Use delivery_options to evaluate a proposed cart for merchant testing. Call it before publishing configuration or after changing a profile, method, zone, location set, or callback. For example, POST /v1/delivery-previews with a physical line item and destination shows the choices the same cart could receive at checkout.
{
"mode": "delivery_options",
"currency": "USD",
"delivery_method_ids": ["dmet_01K1P6G4M7H2N8Q9R3S5T6V7WX"],
"line_items": [
{ "variant_id": "var_123", "quantity": 2 }
],
"destination_address": {
"postal_code": "11249",
"country": "US"
}
}
Use pickup_locations before quoting the buyer's chosen store. Provide checkout_session_id, and optionally buyer_location, maximum_distance, and expected_delivery_selection_id. A distance must be positive with unit meters, kilometers, or miles. The current selection ID may be omitted or null when none is selected. A different selection returns 409 DELIVERY_PICKUP_AVAILABILITY_CHANGED.
{
"mode": "pickup_locations",
"checkout_session_id": "cs_123",
"expected_delivery_selection_id": null,
"buyer_location": {
"type": "address",
"address": { "postal_code": "11249", "country": "US" }
},
"maximum_distance": { "value": 10, "unit": "kilometers" }
}
The response's data.mode matches the request. pickup_locations returns up to 25 locations, nearest first when Flint can place the buyer location. Merchant callers also receive merchant_diagnostics with codes pickup_location_inactive, pickup_location_geography_unavailable, pickup_location_inventory_unavailable, and pickup_location_dependency_failure. Checkout credentials receive buyer-safe results. A checkout credential used for another session or for delivery_options receives 403.
Delivery-option diagnostics use eligibility_no_match, method_unavailable, input_required, checkout_context_required, preview_unsupported, and dependency_failure. These are diagnostic values, separate from API error codes.