Delivery quotes are persisted, time-bounded evaluations of the delivery methods assigned to a checkout. Each required choice group contains the options that can satisfy its line items.
Create a new quote whenever the cart, destination, pickup location, current selection, or required callback input changes. Send the current expected_delivery_selection_id, including null when no selection exists, so a stale browser cannot replace a newer choice.
You can quote before the buyer gives an address. A method that needs one reports it in input_requirements with purpose quote, and the quote also lists, with purpose selection, the recipient fields that method requires, such as recipient.phone for a courier. Until an address prices the method, those requirements name its choice group but no delivery_option_ids. The same applies while the buyer must correct an address Flint could not use. Ask for these fields with the address: an Apple Pay or Google Pay sheet can request a phone only when it opens.
Buyer-authenticated responses expose only buyer-actionable buyer_reasons. Merchant-authenticated responses include method-level diagnostics and dependency evidence for configuration debugging.
In merchant-authenticated responses, each option lists execution_legs: the Locations its items leave from. Under method_origin routing each option leaves from its own method's origin, so shipping can leave from a warehouse while pickup leaves from the chosen store. A choice group lists execution_legs only when all of its methods leave from the same Locations.
A quote lasts 24 hours when every method uses fixed, tiered, or rate_table pricing, and at most 15 minutes when any method uses calculated, callback, or caller_supplied pricing. A cart with tracked inventory shortens the quote to the 5 minutes its stock check stays valid. Read expires_at from every quote.
Routes#
For example, create a quote after the buyer enters a destination:
curl -X POST https://api.withflintpay.com/v1/checkout-sessions/cs_123/delivery-quotes \
-H "X-Checkout-Session-ID: cs_123" \
-H "X-Checkout-Session-Secret: CHECKOUT_SECRET" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: quote-cart-42" \
-d '{
"expected_delivery_selection_id": null,
"destination_address": {
"postal_code": "11249",
"country": "US"
}
}'
Find pickup locations before quoting a chosen store with delivery previews using mode: "pickup_locations" and checkout_session_id.