Delivery options
A delivery method is one way a buyer can receive an order, shown at checkout with its price: standard shipping, pickup at a store, or delivery in a time window. Add shipping to a checkout sets up a single flat rate. Here you set up the options a store with one warehouse and two shops usually offers:
| What the buyer sees | Method type | Pricing |
|---|---|---|
| Standard shipping in the contiguous US: $9, free on orders of $75 or more | shipment | tiered, by order subtotal |
| Standard shipping to Alaska and Hawaii for $25, or to Canada for $30 | shipment | rate_table, by region |
| Free pickup at either shop | pickup | fixed at $0 |
| Local delivery in a two-hour window within 15 km: $5 plus $1 per km, at most $20 | local_delivery | calculated, by distance |
Hosted checkout shows each buyer the options their address and cart qualify for, lets them choose a store or a window, and adds the charge and its tax to the order. To price rates on your own server, for example from a carrier API, see Live delivery rates with a callback.
With automatic tax, Flint taxes the delivery charge. With external tax from your tax calculation callback, the callback taxes each delivery charge a selection creates. With external tax you provide, the order needs tax.delivery_charge_calculation, which Flint copies onto every delivery charge a selection creates, including paid pickup. Without it, a checkout session, payment link, or invoice checkout that can offer a method charging in the order currency returns 400 INVALID_REQUEST with detail code REQUIRED. param is delivery_method_ids for methods set on the session or payment link, and settings.checkout.default_delivery_method_ids for methods inherited from the default, which invoice checkouts use. Set the template on the order, or remove the paid methods. Tax delivery charges has the details.
Before you start#
You need:
- A test API key with
commerce.delivery.writeandsettings.write. Assigning delivery profiles to products also needscommerce.products.write, orcommerce.bundles.writefor bundle components. - Active Locations for the warehouse and the shops. Delivery uses each Location's address and time zone.
- A physical product variant to test with.
The examples use loc_01K4WHSE for the warehouse and loc_01K4SHOPA and loc_01K4SHOPB for the shops, and readable IDs such as dzone_01K4CONUS for the resources you create. Replace them with the IDs from your own responses.
How the pieces fit#
Every option a buyer sees comes from a method. A method has a type (shipment, pickup, or local_delivery), an origin that says where the order leaves from or where the buyer collects it, optional eligibility rules, one pricing strategy, and an optional estimate. The other resources hold configuration that several methods share:
| Resource | Used by | Holds |
|---|---|---|
Delivery profile (dprof_) | Product variants and bundle components | Which method types can deliver the item, and where it ships from |
Delivery zone (dzone_) | Method eligibility and rate-table rates | A reusable area: countries, states, postal codes, or a radius |
Delivery location set (dls_) | Method origins | A reusable group of Locations |
Delivery method (dmet_) | Checkout sessions, payment links, and your checkout default | One choice the buyer can make |
Delivery rate callback (dcb_) | Methods with callback pricing | Your rate server's URL and signing methods |
A rate table has no endpoint of its own. It is the rate_table pricing strategy inside a method, and each of its rates gets a drate_ ID.
A checkout offers a method when all of these are true:
- The method is active, and the checkout session, payment link, or your checkout default lists it.
- The method's type is in the
allowed_typesof the item's delivery profile. - The buyer's address and details match the method's
eligibility. - The pricing produces a price. A rate table with no matching rate, for example, offers nothing.
- The origin can serve the items: a pickup store has stock, the address is inside a delivery radius, or a delivery window is still open.
Flint doesn't merge methods that overlap. Each qualifying method is a separate option, so if two shipping methods both cover an address, the buyer sees both. The zones below give each address in the contiguous US, Alaska, Hawaii, or Canada exactly one standard shipping method. An address elsewhere, such as a US territory or an APO, FPO, or DPO address, matches none of them and gets no standard shipping.
When you create a checkout, Flint pins the current revision of each listed method and everything it references. Later changes apply to checkouts created afterward, not to checkouts already open.
1. Choose which items each method can deliver#
Every physical item gets the General profile unless you assign another. General allows all three method types and ships each option from its own method's origin, so one cart can offer shipping from the warehouse and pickup at a shop. If every item can be delivered every way, skip this step.
Create a profile when some items need different rules. This one is for furniture that can be shipped or picked up but is too large for local delivery:
curl -X POST https://api.withflintpay.com/v1/delivery-profiles \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: profile-oversized-1" \
-d '{
"name": "Oversized",
"configuration": {
"requirement": "required",
"resolution_mode": "quote",
"allowed_types": ["shipment", "pickup"],
"origin_policy": { "type": "method_origin" },
"combination_policy": "combine_when_compatible",
"splitting_policy": "whole_line_item"
}
}'
allowed_types is the setting that matters here. combination_policy and splitting_policy control whether the item can share a delivery with other items, and the values shown are General's. origin_policy decides where the item leaves from:
origin_policy.type | Where the item leaves from |
|---|---|
method_origin | The origin of the method the buyer chooses. General uses this. |
inventory_routing | A stocked Location among the method's origins, chosen by Flint. Use it with tracked inventory. |
fixed_location | Always origin_policy.location_id, whichever method the buyer chooses. |
A profile is active as soon as you create it. Assign it by setting delivery_profile_id on each product variant or bundle component it covers. To make it the default for new physical items, send PATCH /v1/delivery-profiles/{delivery_profile_id} with {"is_default": true, "expected_version": 1}, using the profile's current version. The profile you replace stops being the default and its version advances too. GET /v1/delivery-profiles?is_default=true returns the current default. Delivery configuration covers conflicts and what happens when the profile is already the default.
Making a profile the default doesn't change items you already have. To give it to every physical variant and bundle component without a profile, call POST /v1/delivery-profiles/{delivery_profile_id}/assign-to-unconfigured. Flint returns 202 Accepted and assigns it in batches after responding. Read the profile until unconfigured_assignment.status is no longer processing, waiting the response's Retry-After seconds between reads:
curl -X POST https://api.withflintpay.com/v1/delivery-profiles/dprof_.../assign-to-unconfigured \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: assign-oversized-1" \
-d '{ "expected_version": 1 }'
# Repeat every 10 seconds while status is "processing"
curl https://api.withflintpay.com/v1/delivery-profiles/dprof_... \
-H "Authorization: Bearer YOUR_API_KEY" | jq '.data.unconfigured_assignment'
Follow an assignment explains each field.
2. Create zones#
A zone is an area that methods and rates can share. Its configuration is a condition on the buyer's address: country, state, postal_code, or radius, combined with all, any, and not. Each object in the tree holds exactly one of those keys.
The contiguous US is every US address outside Alaska, Hawaii, the territories, and military (APO, FPO, and DPO) addresses:
curl -X POST https://api.withflintpay.com/v1/delivery-zones \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: zone-contiguous-us-1" \
-d '{
"name": "Contiguous US",
"configuration": {
"all": [
{ "country": { "values": ["US"] } },
{ "not": { "state": { "values": ["US-AK", "US-HI", "US-AS", "US-GU", "US-MP", "US-PR", "US-UM", "US-VI", "US-AA", "US-AE", "US-AP"] } } }
]
}
}'
Delivery input constraint.supported_countries is derived from eligibility and rate-table rows. Only alternative methods in a choice group that need that address contribute their combined countries; every choice group must be able to serve the destination. A pickup method that needs no shipping address does not widen shipping country coverage. Country coverage can be broader than a method's final service area because state, postal code, radius, and customer conditions still apply. Unrestricted coverage excludes CU, IR, KP, and SY; addresses identifying Crimea, Donetsk, or Luhansk are unavailable.
For automatic-tax orders, intersect delivery coverage with order.tax.supported_countries, the countries automatic tax covers. Automatic tax covers Canada only for digital goods, software, and SaaS, so use the Canadian delivery methods below with tax off or external tax.
State values are ISO 3166-2 codes. For US states and Canadian provinces you can also send the two-letter code, such as AK or ON, and Flint stores US-AK or CA-ON. A buyer's address matches whether its state is AK, US-AK, or Alaska. Military addresses use AA, AE, and AP. Outside the US and Canada, the buyer's state must be the subdivision code, with or without the country prefix. When a condition lists states in the buyer's country but the buyer's state names none of that country's subdivisions, Flint can't decide the condition, so the method is left out as cannot_calculate rather than treated as outside the listed states.
Create the Alaska and Hawaii zone:
curl -X POST https://api.withflintpay.com/v1/delivery-zones \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: zone-alaska-hawaii-1" \
-d '{
"name": "Alaska and Hawaii",
"configuration": {
"state": { "values": ["US-AK", "US-HI"] }
}
}'
Then create the local delivery area as a 15 km radius around the method's origin:
curl -X POST https://api.withflintpay.com/v1/delivery-zones \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: zone-local-15km-1" \
-d '{
"name": "Within 15 km",
"configuration": {
"radius": {
"origin": { "method_origin": true },
"maximum_distance": { "value": 15, "unit": "kilometer" },
"measurement": "straight_line"
}
}
}'
A radius is the straight-line distance from the origin Location to the buyer's address. To measure from one Location whatever the method, send "origin": {"location_id": "loc_..."}. Flint has to place the address on a map to measure it, so a radius method isn't offered for an address Flint can't locate. Its outcome is cannot_calculate.
Each zone is active when created. Save each delivery_zone_id from the responses. Conditions about the buyer rather than the address, such as customer_segment and customer_merchant_verified, and the time-of-day condition window_time, go in a method's eligibility, not in a zone.
3. Ship in the contiguous US, free over $75#
Use tiered pricing when the price depends on the cart. This method charges $9, or nothing on orders of $75 or more, and serves only the contiguous US zone:
curl -X POST https://api.withflintpay.com/v1/delivery-methods \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: method-standard-contiguous-1" \
-d '{
"name": "Standard shipping",
"type": "shipment",
"status": "active",
"configuration": {
"origin": { "type": "fixed_location", "location_id": "loc_01K4WHSE" },
"eligibility": { "zone": { "delivery_zone_id": "dzone_01K4CONUS" } },
"pricing": {
"type": "tiered",
"tiered": {
"basis": "order.merchandise_subtotal_after_line_item_discounts",
"bands": [
{ "from": 0, "to": 7500, "currency_options": { "USD": { "amount": 900, "currency": "USD" } } },
{ "from": 7500, "currency_options": { "USD": { "amount": 0, "currency": "USD" } } }
]
}
},
"estimate": {
"type": "transit_time",
"transit_time": {
"handling_days": { "minimum": 1, "maximum": 1 },
"transit_days": { "minimum": 2, "maximum": 5 }
}
},
"public_details": { "service_level": "standard" }
}
}'
status: "active"activates the method on create. Its zone and Location must already be active, or the request fails with400 INVALID_REQUEST. Buyers see it only once a checkout lists it, in step 8. Withoutstatus, a method is createdinactive.- Bands start at
0, follow each other without gaps, and the last band has noto.fromis inclusive andtois exclusive, both in minor units for money, so7500is $75.00 and a $75.00 order ships free. A tiered method can have up to 25 bands. basisis what the bands measure.order.merchandise_subtotal_after_line_item_discountsis the merchandise total minus item discounts: promotions and manual discounts withdiscount_class: line_item. An $80 cart with a $10 item discount counts as $70 and pays $9. Order discounts and discounts on the shipping charge don't lower it, and a promotion is an order discount unless you set itsdiscount_class. To ignore discounts, useorder.merchandise_subtotal_before_discounts.estimatecountshandling_daysand thentransit_daysas business days in the origin Location's time zone, from the day of the quote. It skips Saturdays and Sundays, not holidays. For a warehouse in New York, a quote created on Thursday, October 1, 2026 carries"earliest_date": "2026-10-06"and"latest_date": "2026-10-09"inarrival_estimate, with"timezone": "America/New_York". Show the dates as they are, for example "Arrives Oct 6 to 9". Converting them to another time zone can move them by a day. When a delivery choice includes a pre-order or backordered units, counting starts from the latestrelease_date, or for backordered units their item'sbackorder.expected_ship_date, among the choice's lines, if that date is after today. Windows you or a rate callback supply, scheduled windows, and the quote's expiry don't move.service_levelfor a shipment iseconomy,standard,expedited,express,overnight, orsame_day.
Other bases price by what is in one delivery rather than the whole order: choice_group.merchandise_subtotal_before_discounts, choice_group.merchandise_subtotal_after_line_item_discounts, choice_group.fulfillment_quantity, and choice_group.total_weight, which needs unit set to gram, kilogram, ounce, or pound and reads each variant's unit_weight. A group with an item that has no weight doesn't get the option. A choice group is the whole order unless delivery profiles split it, and then each group is priced on its own items.
Note: A method can't require a minimum order
No eligibility rule or band hides a method below an order amount. Put the threshold in the method's price, as this one does, rather than adding a second method for free shipping: two methods that cover the same address both appear, so a $40 order would see two $9 options.
Ship from two warehouses#
To let Flint ship each order from whichever warehouse has the stock, give one method an allocated_origin_group origin with both Locations:
"origin": { "type": "allocated_origin_group", "location_ids": ["loc_01K4WHSE", "loc_01K4WHSE2"] }
Two more settings make it work:
- The items' profile uses
inventory_routing. Undermethod_origin, which the General profile uses, an item leaves from the chosen method's origin, so that origin must be one Location. Create a profile with"origin_policy": { "type": "inventory_routing" }, as in step 1, and assign it to the variants you stock in both warehouses. - Orders have a routing source. Track the items' inventory at both Locations, and send
inventory_routing_sourceon the order or setinventory.default_routing_sourcein settings, as Inventory describes.
If an item is still on a method_origin profile, quotes don't offer the group method for it. Its candidate outcome is cannot_calculate with failure_category: invalid_configuration and retryable: false, and its merchant_diagnostics entry has code: method_unavailable and a summary naming origin_policy. Your other methods are still offered. Retrying gives the same result until you change the profile or give the method a fixed_location origin.
4. Ship to Alaska, Hawaii, and Canada#
Use a rate table when one method charges different prices in different places. Flint checks the rates from the highest priority down and uses the first rate whose when matches. When no rate matches, the method isn't offered.
curl -X POST https://api.withflintpay.com/v1/delivery-methods \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: method-standard-remote-1" \
-d '{
"name": "Standard shipping",
"type": "shipment",
"status": "active",
"configuration": {
"origin": { "type": "fixed_location", "location_id": "loc_01K4WHSE" },
"pricing": {
"type": "rate_table",
"rate_table": {
"rates": [
{
"priority": 20,
"when": { "zone": { "delivery_zone_id": "dzone_01K4AKHI" } },
"currency_options": { "USD": { "amount": 2500, "currency": "USD" } }
},
{
"priority": 10,
"when": { "country": { "values": ["CA"] } },
"currency_options": { "USD": { "amount": 3000, "currency": "USD" } }
}
]
}
},
"estimate": {
"type": "transit_time",
"transit_time": {
"handling_days": { "minimum": 1, "maximum": 1 },
"transit_days": { "minimum": 5, "maximum": 10 }
}
},
"public_details": { "service_level": "standard" }
}
}'
Flint responds with the method, its version, and a delivery_rate_id for each rate. Abridged:
{
"data": {
"delivery_method_id": "dmet_01K4REMOTE",
"current_delivery_method_revision_id": "dmetr_01K4REMOTE1",
"type": "shipment",
"name": "Standard shipping",
"status": "active",
"version": 1,
"configuration": {
"pricing": {
"rate_table": {
"rates": [
{
"currency_options": { "USD": { "amount": 2500, "currency": "USD" } },
"delivery_rate_id": "drate_01K4AKHI",
"priority": 20,
"when": { "zone": { "delivery_zone_id": "dzone_01K4AKHI", "subject": "destination_address" } }
},
{
"currency_options": { "USD": { "amount": 3000, "currency": "USD" } },
"delivery_rate_id": "drate_01K4CANADA",
"priority": 10,
"when": { "country": { "subject": "destination_address", "values": ["CA"] } }
}
],
"unmatched_behavior": "unavailable"
},
"type": "rate_table"
}
}
},
"request_id": "req_01K4REMOTE"
}
Both methods are named "Standard shipping" because a buyer only ever sees one of them: the contiguous US zone and this rate table cover different addresses. The method has no eligibility, so the rate table alone decides where it is offered.
whentakes the same conditions aseligibility. It can name a zone, usecountry,state, orpostal_codedirectly, as the Canada rate does, or match a customer segment.priorityvalues are unique,0or more, and only matter when rates overlap. A table holds 1 to 100 rates.- A
whenthat can't be decided, for example a zone onstatefor an address with no state, leaves the method out, ascannot_calculate, rather than falling through to the next rate. unmatched_behaviordefaults tounavailable, its only value.
5. Offer pickup at your shops#
A pickup method's origin is the Locations a buyer can choose from. Put them in a location set when several methods share them:
curl -X POST https://api.withflintpay.com/v1/delivery-location-sets \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: location-set-shops-1" \
-d '{
"name": "Shops",
"configuration": { "location_ids": ["loc_01K4SHOPA", "loc_01K4SHOPB"] }
}'
Every Location in a set must be active, with an address and time zone. Otherwise the request returns 400 INVALID_REQUEST with param naming the Location, such as configuration.location_ids[1]. A Location doesn't need inventory allocation to be in a set. Stock is checked when the buyer chooses a store.
Create the pickup method. public_details.pickup_mode is required for pickup: in_store, curbside, locker, or other. Checkout shows instructions to the buyer.
curl -X POST https://api.withflintpay.com/v1/delivery-methods \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: method-pickup-shops-1" \
-d '{
"name": "Pick up in store",
"type": "pickup",
"status": "active",
"configuration": {
"origin": {
"type": "pickup_location_collection",
"delivery_location_set_id": "dls_01K4SHOPS"
},
"pricing": {
"type": "fixed",
"fixed": { "currency_options": { "USD": { "amount": 0, "currency": "USD" } } }
},
"public_details": {
"pickup_mode": "in_store",
"instructions": "Bring your order number to the front counter."
}
}
}'
Items with tracked inventory are picked up from the chosen store's own stock. When that store can't cover the cart, only pickup there becomes unavailable. The buyer can choose another store, and shipping from the warehouse is unaffected.
Show a known pickup price#
An API key's delivery quote and the session's derived delivery can report expected_amount_money on an input_required candidate. It is the fixed charge the method will quote once the missing input arrives. Rate-table and callback methods omit it.
For pickup, every pickup method that could serve a choice group must have fixed pricing with the same amount before any waiting pickup candidate reports the field. For example, with free pickup at both stores, each waiting candidate reports "expected_amount_money": {"amount": 0, "currency": "USD"}. Display "Pickup: Free" while the buyer chooses a store. Different fixed prices or a mix of fixed and non-fixed methods leave the amount unknown, so the field is omitted. Omission never means zero.
Pickup-location previews do not carry this field. An expected amount never enters the order's amounts; a delivery selection must back the charge. To include shipping in the total before a complete address, quote from the country and select an offered option.
Let the buyer choose a store#
Hosted checkout asks the buyer to choose a store. If you build your own checkout, a pickup method can't offer a selectable option until the buyer has chosen one, so list the stores that can fulfill the cart, nearest first:
curl -X POST https://api.withflintpay.com/v1/delivery-previews \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "pickup_locations",
"checkout_session_id": "cs_1kmn0aExample",
"buyer_location": {
"type": "address",
"address": { "postal_code": "11249", "country": "US" }
}
}'
Flint responds with each store, its distance, and whether it can fulfill the cart. Abridged:
{
"data": {
"mode": "pickup_locations",
"evaluation_status": "complete",
"input_requirements": [],
"locations": [
{
"location": { "location_id": "loc_01K4SHOPA", "name": "Shop A" },
"distance_meters": 1843.7,
"compatible_methods": [
{ "delivery_method_id": "dmet_01K4PICKUP", "delivery_method_revision_id": "dmetr_01K4PICKUP1" }
],
"applicable_quantities": [{ "order_line_item_id": "li_01K4MUG", "quantity": 2 }],
"candidate_outcome": { "type": "available" }
},
{
"location": { "location_id": "loc_01K4SHOPB", "name": "Shop B" },
"distance_meters": 5210.2,
"compatible_methods": [
{ "delivery_method_id": "dmet_01K4PICKUP", "delivery_method_revision_id": "dmetr_01K4PICKUP1" }
],
"applicable_quantities": [{ "order_line_item_id": "li_01K4MUG", "quantity": 2 }],
"candidate_outcome": { "type": "unavailable", "unavailable_reason": "inventory_unavailable" }
}
],
"evaluated_at": "2026-10-01T14:00:00Z"
},
"request_id": "req_01K4PICKUPSEARCH"
}
buyer_locationcan be a postal code, which Flint measures from the code's center, or a coordinate for an exact distance. Without one, stores come back in the order you configured them, with nodistance_meters. Addmaximum_distance, such as{"value": 10, "unit": "kilometer"}, to leave out stores farther away.unitismeter,kilometer, ormile.- The buyer's choice stays as it is. Searching again after the buyer picks a store doesn't change or release their selection.
- The results list at most 25 stores, and the search doesn't reserve stock. Each store's
candidate_outcomesays whether it can fulfill the cart now.
Your storefront makes this call with the checkout credential, sent as Authorization: Bearer, instead of your API key. The response is the same except that it leaves out merchant_diagnostics. With your key, the response always includes merchant_diagnostics, empty when nothing was filtered out. It explains stores that can't be offered, such as pickup_location_inventory_unavailable for a store that doesn't allocate inventory. Pass the chosen store's ID as pickup_location_id when you quote the buyer's delivery. The quote checks the store and its stock again.
6. Offer scheduled local delivery#
This method delivers within the 15 km zone, charges $5 plus $1 per kilometer, and lets the buyer choose a two-hour window on Tuesdays and Thursdays:
curl -X POST https://api.withflintpay.com/v1/delivery-methods \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: method-local-delivery-1" \
-d '{
"name": "Local delivery",
"type": "local_delivery",
"status": "active",
"configuration": {
"origin": { "type": "fixed_location", "location_id": "loc_01K4WHSE" },
"eligibility": { "zone": { "delivery_zone_id": "dzone_01K4LOCAL" } },
"pricing": {
"type": "calculated",
"calculated": {
"base_fee_currency_options": { "USD": { "amount": 500, "currency": "USD" } },
"distance": {
"unit_quantity": 1,
"unit": "kilometer",
"currency_options": { "USD": { "amount": 100, "currency": "USD" } }
},
"minimum_fee_currency_options": { "USD": { "amount": 500, "currency": "USD" } },
"maximum_fee_currency_options": { "USD": { "amount": 2000, "currency": "USD" } }
}
},
"minimum_option_lifetime_seconds": 300,
"estimate": {
"type": "schedule_window",
"schedule_window": {
"availability": {
"timezone": "America/New_York",
"weekly_intervals": [
{ "start_weekday": 2, "start_minute": 600, "end_weekday": 2, "end_minute": 720 },
{ "start_weekday": 2, "start_minute": 840, "end_weekday": 2, "end_minute": 960 },
{ "start_weekday": 4, "start_minute": 600, "end_weekday": 4, "end_minute": 720 },
{ "start_weekday": 4, "start_minute": 840, "end_weekday": 4, "end_minute": 960 }
],
"preparation_lead_time_seconds": 7200,
"maximum_scheduling_horizon_days": 7
}
}
},
"public_details": { "service_level": "scheduled" }
}
}'
Price. Flint prorates the per-kilometer charge to the straight-line distance, rounds half up, and then applies the minimum and maximum, which you set together. This method always charges between $5 and $20: an address 6.4 km away pays $11.40.
Quote lifetime. A quote that includes calculated, callback, or caller_supplied pricing lasts up to 15 minutes; other quotes last up to 24 hours. Those three pricing types require minimum_option_lifetime_seconds, from 0 to 899. Flint offers the method only when the new quote has more than that many seconds left.
Windows. Each weekly interval becomes one window on every matching day. Weekdays run from 0 for Sunday to 6 for Saturday, and minutes count from midnight in timezone:
| Interval | Window |
|---|---|
start_weekday: 2, minutes 600 to 720 | Tuesday, 10:00 to 12:00 |
start_weekday: 2, minutes 840 to 960 | Tuesday, 14:00 to 16:00 |
start_weekday: 4, minutes 600 to 720 | Thursday, 10:00 to 12:00 |
start_weekday: 4, minutes 840 to 960 | Thursday, 14:00 to 16:00 |
A buyer can choose a window until preparation_lead_time_seconds before it starts, two hours here, and quotes offer only windows that can still be chosen, up to maximum_scheduling_horizon_days ahead. A window already under way is never offered, so to take orders through a long period such as store hours, split it into shorter windows. Add same_day_cutoff_minute to stop offering same-day windows after a set time, and blackout_intervals, each with start_local and end_local such as 2026-11-26T00:00:00, to close dates like holidays.
Service level. For local delivery, service_level is on_demand, same_day, or scheduled.
In a quote, this option has window_selection: "offered" and lists its offered_windows, each with a delivery_window_id, start_at, end_at, and expires_at, the last moment the buyer can choose it. Your checkout sends the chosen window as choices[].input.delivery_window_id when it selects the option.
7. Preview what buyers will see#
A delivery preview runs a cart through your methods without creating a checkout, a selection, or an inventory hold. It needs commerce.delivery.read, and every method you list must exist and be active. A method that doesn't exist returns 404 RESOURCE_NOT_FOUND with its ID in details[0].resource_id, and an inactive one returns 409 ACTION_NOT_ALLOWED with reason unsupported_state naming the method. When any line tracks inventory, send inventory_routing_source as you would on an order; it decides where each item ships from. Try one address in each zone, and carts on both sides of $75:
curl -X POST https://api.withflintpay.com/v1/delivery-previews \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "delivery_options",
"currency": "USD",
"delivery_method_ids": ["dmet_01K4STANDARD", "dmet_01K4REMOTE", "dmet_01K4LOCAL"],
"line_items": [
{ "type": "variant", "variant_id": "var_01K4MUG", "quantity": 2 }
],
"inventory_routing_source": { "type": "fixed_location", "location_id": "loc_01K4WHSE" },
"destination_address": {
"line1": "120 Kent Avenue",
"city": "Brooklyn",
"state": "NY",
"postal_code": "11249",
"country": "US"
}
}'
Leave out delivery_method_ids to preview your checkout default, settings.checkout.default_delivery_method_ids, which every checkout without its own methods offers. The response's delivery_method_ids lists the methods Flint evaluated. With no default, the preview returns empty delivery_method_ids and choice_groups.
For two $20 mugs shipped to Brooklyn from a warehouse more than 15 km away, contiguous US shipping is offered at $9 and the other two methods are not. Abridged:
{
"data": {
"mode": "delivery_options",
"evaluation_status": "complete",
"choice_groups": [
{
"availability_status": "ready",
"allowed_types": ["shipment", "pickup", "local_delivery"],
"options": [
{
"delivery_method_id": "dmet_01K4STANDARD",
"type": "shipment",
"name": "Standard shipping",
"amount_money": { "amount": 900, "currency": "USD" },
"arrival_estimate": {
"earliest_date": "2026-10-06",
"latest_date": "2026-10-09",
"timezone": "America/New_York"
}
}
],
"candidate_outcomes": {
"dmet_01K4STANDARD": { "type": "available" },
"dmet_01K4REMOTE": { "type": "unavailable", "unavailable_reason": "pricing_unavailable" },
"dmet_01K4LOCAL": { "type": "unavailable", "unavailable_reason": "eligibility_no_match" }
}
}
],
"merchant_diagnostics": [
{
"outcome": "unavailable",
"code": "eligibility_no_match",
"delivery_method_id": "dmet_01K4LOCAL",
"summary": "The method did not match its configured eligibility conditions.",
"eligibility_mismatches": [
{ "condition": "zone", "field": "destination_address", "expression_path": "$" }
]
}
],
"evaluated_at": "2026-10-01T14:00:00Z",
"expires_at": "2026-10-01T14:15:00Z"
},
"request_id": "req_01K4PREVIEW"
}
Each choice group lists the priced options a buyer could choose, and candidate_outcomes says what happened to every method you sent:
type on delivery candidate outcome resourceunavailable_reason | What to check |
|---|---|
eligibility_no_match | The address or buyer is outside the method's eligibility, for example beyond the radius. |
pricing_unavailable | No rate in the rate table matched, or the price has no amount in the cart's currency. |
method_type_not_allowed | The item's delivery profile doesn't allow the method's type. |
no_window_available | Every window within the scheduling horizon has passed its lead time or is blocked out. |
pickup_unavailable | The chosen pickup store isn't one of the method's stores. |
inventory_unavailable | The origin doesn't have the stock. |
destination_not_served | Your rate callback said it doesn't deliver to the address. |
merchant_diagnostics has an entry for each method that wasn't offered. For an eligibility failure, eligibility_mismatches names the condition that didn't match. Buyers see the same options in a checkout quote. Your backend can also run a preview to show estimated shipping on a cart page before checkout starts.
Show estimated shipping in the cart#
To show estimated shipping before the buyer starts checkout, have your backend call POST /v1/delivery-previews with the cart lines, the ZIP code or address the buyer entered, and inventory_routing_source for tracked lines. Show the lowest available option's amount_money as "Estimated shipping".
- The call needs a key with
commerce.delivery.read, so it runs on your server. A checkout credential is refused for this mode. - A preview holds no inventory and makes no selection. Methods marked
requires_checkout_contextcan't be estimated, so they don't appear in the estimate. - Previews have their own
delivery_previewrate limit, so cache the result by cart and ZIP code. - Label the cart total as before tax. Checkout calculates tax once the buyer's address is known.
The shipping figure is an estimate. Checkout quotes the final delivery price and shows the final total.
8. Offer the methods at checkout#
List the methods in your checkout default to offer them on every checkout:
curl -X PATCH https://api.withflintpay.com/v1/settings \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"checkout": {
"default_delivery_method_ids": ["dmet_01K4STANDARD", "dmet_01K4REMOTE", "dmet_01K4PICKUP", "dmet_01K4LOCAL"]
}
}'
The default applies to checkout sessions, payment links, and invoice checkouts for orders with items to deliver. To offer different methods on one checkout, set delivery_method_ids on the checkout session or payment link. A list holds 1 to 25 methods, with no duplicates. To use the default on a checkout session, leave delivery_method_ids out; [] and null are rejected. On a payment link, [] clears the link's own list so it uses the default again.
Hosted checkout collects the address, shows the options each buyer qualifies for, and lets them choose a store or a window. To order the options, set display_position on each method; lower numbers come first. To mark one as recommended, set recommendation_priority: among the available methods that have one, the lowest value is recommended and listed first. Both are top-level method fields, not part of configuration.
Stripe Checkout has no local pickup setting. Stripe Checkout local pickup and dynamic shipping compares its workarounds with delivery methods.
Change configuration later#
Every delivery resource has a version. Send it as expected_version when a PATCH changes configuration, or a method's name, description, display_position, or recommendation_priority. Status changes, metadata, and renaming a profile, zone, location set, or rate callback don't need it.
For a method, send only the configuration keys you're changing. Each key you send replaces that key's whole value, keys you leave out keep theirs, and null clears an optional key. To change rates, send the complete rates array: include delivery_rate_id for each rate you keep, leave it out for new rates, and leave out rates to remove them. A zone, profile, or location set is different: its configuration replaces the whole configuration. This raises the Alaska and Hawaii rate to $29 and keeps the Canada rate:
curl -X PATCH https://api.withflintpay.com/v1/delivery-methods/dmet_01K4REMOTE \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"expected_version": 1,
"configuration": {
"pricing": {
"type": "rate_table",
"rate_table": {
"rates": [
{
"delivery_rate_id": "drate_01K4AKHI",
"priority": 20,
"when": { "zone": { "delivery_zone_id": "dzone_01K4AKHI" } },
"currency_options": { "USD": { "amount": 2900, "currency": "USD" } }
},
{
"delivery_rate_id": "drate_01K4CANADA",
"priority": 10,
"when": { "country": { "values": ["CA"] } },
"currency_options": { "USD": { "amount": 3000, "currency": "USD" } }
}
]
}
}
}
}'
If someone changed the method after you read it, Flint returns 409 VERSION_CONFLICT with details[0].current_version. Read the method again, rebuild the change, and send it with a new Idempotency-Key. A status-only PATCH or a DELETE can omit expected_version. If another write lands while such a request runs, Flint also returns 409 VERSION_CONFLICT, with no param. Sending the same request again isn't safe then: read the resource again, decide whether the change still applies, and send it with a new Idempotency-Key.
To stop offering a method, deactivate it with a PATCH that sends only {"status": "inactive"}, optionally with expected_version. Methods and rate callbacks can be deactivated this way; profiles, zones, and location sets can only be archived, with DELETE. Flint blocks both while something depends on the resource:
| Resource | Blocked while |
|---|---|
| Delivery method | Your checkout default or a payment link lists it, including an inactive link |
| Delivery zone, location set, or rate callback | An active method references it |
| Delivery profile | A product variant or bundle component uses it, or it is the default profile |
The error's details[0].blocking_resources lists what is blocking. Remove those references, then retry. An inactive method can keep referencing an archived zone or set, but it can't be activated again until you replace the reference.
Errors#
Errors lists every code with its remediation.
Endpoints#
List endpoints filter by related resources. For example, GET /v1/delivery-methods?delivery_zone_id=dzone_... finds every method that uses a zone, which is useful before you archive it. Delivery configuration documents every field.
For tiered pricing, use 1 to 25 contiguous numeric bands. The caller.tier_key basis matches the nonnegative tier_key your server supplies with a checkout delivery quote; omit unit for this basis. A rate table accepts 1 to 100 rates. See pricing strategies.
Next steps#
- Live delivery rates with a callback: price shipping from a carrier API on your own server.
- Build your own checkout: quote delivery, choose a store or a window, and select an option in your own storefront.
- Fulfillment and shipping: pack, ship, hand over pickups, and notify the buyer.
- Inventory: track stock at each Location so pickup and routing know what's available.