The checkout cannot take payment until it has a delivery quote for the basket and the address. The quote comes from the store's shipping configurations. With none, every checkout of a physical product stops. Set shipping up before payments: see Take payments on the site.
The built-in checkout charges the cheapest option. It has no shipping picker. It asks the server for one figure, and the server returns the cheapest option that applies. So every option you add that applies to an address can become the price for that address. A free pickup option open to everyone makes every order's shipping free. Scope the options so that, for each address, the cheapest one left is the one you mean to charge.
Ask first
- Where do they ship? Countries; any states or postcodes that cost more or less; anywhere they never ship.
- How do they charge? One price per order, a price per item, by weight, live carrier rates, free over an amount, local pickup.
- Faster services? Only a custom page can let the shopper choose (see What it can't do yet). The built-in checkout charges the cheapest.
- Products that ship differently: always free, their own flat price, freight or oversize, always in their own box, never to some places.
- For live carrier rates: which carrier account, and where they ship from (a business location with a full address, and a sender phone).
- Handling fees or markup on top of the rate.
Steps
1. Storefront › Shipping: see what exists
Open Storefront › Shipping at /shipping?tab=settings, then the Shipping Methods sub-tab. The sub-tabs (Overview, Shipping Methods, Providers, Product Shipping) aren't in the URL, so say which one to click. call_appengine GET shipping/admin/configs lists every configuration with a summary worked out by the server (headline, rateLabel, one line per option). Read them before adding anything. Configurations are named (name, unique), and every admin call takes the name, not the record id.
If one already covers the job, change it rather than adding a second one: two configurations that both apply to an address are both quoted, and the cheaper wins.
Hands on: the names of the existing configurations. Check: the list on screen matches what the call returned.
2. Storefront › Shipping: the configuration and its options
A configuration holds a list of options. Each option says where it applies, for what size of order, and how it is priced. Create one with call_appengine POST shipping/admin/configs (staff only):
{
"name": "standard-shipping",
"title": "Standard shipping",
"currency": "USD",
"status": "active",
"options": [
{ "label": "Dallas delivery", "method": "flat", "rate": 6, "postcodes": ["752*"], "minDays": 1, "maxDays": 2 },
{ "label": "Texas", "method": "flat", "rate": 8, "countries": ["US"], "states": ["TX"], "minDays": 2, "maxDays": 4 },
{ "label": "US", "method": "flat", "rate": 10, "countries": ["US"], "freeOver": 100, "minDays": 3, "maxDays": 6 },
{ "label": "International", "method": "flat", "rate": 35 }
]
}It answers with the saved record. A second configuration with the same name is refused: Shipping configuration 'standard-shipping' already exists. One with neither options nor a top-level method is refused: Add at least one shipping option, or set a method for the whole configuration.
Option fields (options[]):
| Field | What it does |
|---|---|
label | what the customer sees. Default: the configuration's title plus a number. |
status | inactive takes the option out of every quote. |
method | flat, weight, carrier, pickup or free (below). Anything else, including the old zone, quotes nothing and reports … uses an unsupported method "zone". |
rate | the price for flat; for weight, the price when no tier fits. |
perItem | true: rate × the number of items. |
freeOver | free when the order total is at or above this. |
tiers | for weight: [{ name, maxWeight, maxLength, maxWidth, maxHeight, maxGirth, rate }], first fit wins. |
carrier | for carrier: { integration, allowedServices: ["Ground", …] }. |
pickup | for pickup: { locations: [<location name>], fee, readyInHours, instructions }. |
countries, states, postcodes | where it applies. All empty = anywhere. |
minWeight / maxWeight / weightUnit | total basket weight bounds (lb default, or kg). |
minQuantity / maxQuantity | number of items. |
minOrderTotal / maxOrderTotal | order value. |
productClasses | the classes this option carries (step 4). Empty = ordinary goods only. |
minDays / maxDays | the delivery estimate shown with the option. |
priority | breaks ties between options (see the warning below). |
currency | overrides the configuration's currency. |
Configuration fields that apply to every option in it:
| Field | What it does |
|---|---|
name | unique, letters, digits, - and _. Can't be changed later. |
title, currency (default USD), status | status: "inactive" takes the whole configuration out of quoting. |
freeShipping | { enabled: true, threshold: 150 }: every option free at or above threshold. |
handling | { feePerOrder, feePerItem }, added to every option's price. |
markup | { type: "none" | "fixed" | "percentage" | "both", fixedAmount, percentage, roundUp }, applied to price + handling, for every method. roundUp rounds up to the next whole unit. |
restrictions | excludeCountries, excludeStates: none of its options apply there. maxWeight + maxWeightUnit: over it, the options in this configuration quote nothing. |
origin | Ship From for carrier rates: { type: "location", location: "<location name>" } or { type: "manual", address: {…} }. |
boxSizes | { source: "custom", boxes: [{ name, length, width, height, dimensionUnit, maxWeight, weightUnit }] }: boxes for packing carrier parcels. Otherwise standard carrier boxes. |
isDefault | marks one configuration as the site default. Setting it clears it on every other configuration. |
How a place is matched. The address's country, state (or region) and zip (or postalCode, postcode) are compared without regard to case.
countriesandstatesare codes:US,TX.- A postcode rule is exact (
75201), a prefix (752*) or a numeric range, both ends included (75000-75199). Spaces are ignored, soSW1A*matchesSW1A 1AA. - When an option names more than one of
countries,statesandpostcodes, all of them must match.
How size is matched. Every min is inclusive and every max is exclusive. So an option with maxWeight: 50 and another with minWeight: 50 meet with no gap and no overlap. Weight is the sum of each product's parcel.weight × quantity, and a product with no parcel.weight weighs 0. The order total is the products' subtotal.
A place-scoped option pushes every "anywhere" option aside, in every configuration. When any option that names a country, state or postcode applies to the address, options that name no place are not offered there at all, even in other configurations. All the scoped options that match stay, the country one with the postcode one, and the cheapest wins. A Dallas rule beats a Texas rule only by being cheaper. priority and isDefault only order options before the final sort by price, so they never make a dearer option the one charged.
"Free" still carries handling and markup. Free shipping (method: "free", freeOver, freeShipping.threshold), and pickup, price the base at 0 and then add the configuration's handling and markup. A configuration with a $2 handling fee charges $2 for "free" shipping. Keep free options in a configuration with no handling or markup.
The options for each method:
flat.ratefor the order, orrate× items withperItem: true.weight. The first tier the basket fits is charged. Within a tier the max is inclusive: a 3 lb basket fitsmaxWeight: 3. Dimensions are the largest single item's. If no tier fits,rateis charged. Setratefor every weight option: with norate, a basket heavier than every tier is quoted $399.99.carrier. Live rates from the shipping integration, one option per service, cheapest first. It needs a full destination address and a Ship From (step 3). Products need a weight and all three dimensions, or their own boxes, or the quote fails withCannot calculate shipping: "<product>" is missing parcel dimensions….allowedServiceskeeps only services whose code contains one of the words. The carrier block's ownmarkup(fixed) andmarkupPercentare added before the configuration'smarkup.pickup.pickup.fee(default 0).readyInHoursbecomes the estimate ("Ready in 24h").locationsandinstructionscome back with the option for the page to show.free. 0, plus handling and markup (see the warning).
On screen. The Shipping Methods form writes the same record: title (the name is made from it and locked after the first save), Active, Use as the site default (isDefault), currency, the options, Ship From, handling, markup and Never ship to (restrictions.excludeCountries / excludeStates, typed as comma-separated codes). It never writes the old top-level method, flatRate, rates or applies. It won't save a carrier option with no integration chosen.
Some fields can only be set through the API, not on this form:
| Field | Why it matters |
|---|---|
the price for a weight option when no tier fits (rate) | without it, a heavy basket is quoted $399.99 |
tier maxLength, maxWidth, maxHeight, maxGirth | the form edits only name, maxWeight and rate |
freeOver on a method other than flat | the form shows "Free above" for flat options only |
markup.fixedAmount when markup is Both | the form shows only the percent box |
markup.roundUp | |
restrictions.maxWeight / maxWeightUnit | |
boxSizes |
Set them with POST shipping/admin/configs/<name>, which updates only the fields sent. A field sent replaces that whole field: options is replaced as a list, so send every option.
- It says "Several can match one order — that is how a customer gets a choice". The built-in checkout gives no choice: it charges the cheapest.
- Never ship to says such an order "is turned down with a reason". On a configuration, those lists only remove its options. The shopper sees "No shipping option covers …". Only a product's own restrictions give the "We don't ship …" reason (step 4).
An old-shape configuration (top-level method, no options) opens on this form with no options. It still quotes. But the moment one option is added and saved, the old top-level fields stop counting (see What it can't do yet).
Hands on: the configuration's name.
Check: GET shipping/admin/configs/<name> returns it, and summary.options reads back as intended (e.g. $10.00 · US, free over $100.00). Studio has no rate preview: test with a quote (step 5).
3. Business locations: Ship From (live carrier rates only)
Carrier rates are priced from an origin, found in this order:
- a product's
shipping.shipsFrom(a location name); - the configuration's
origin; - the business's only location. With two or more locations and no origin set, none is chosen.
With no origin the option quotes nothing: <label> has no origin to rate from — set "Ship From". Add or complete the location in Business locations (/business-locations): street, city, state, zip and country. Carriers also need a sender phone, read from the location's data.phone. The location form has no phone field: set it with repo_update on the location (data.phone), or type it when Ship in one click asks for it, which saves it on the location. Without one, the business's own phone is used. See Business locations, hours and sales tax.
A carrier account must also be connected (Storefront › Shipping › settings › Providers), or the business must use the platform's shipping account and have accepted its agreement (Setup wizard, Shipping labels). A person does both; the AI does neither. See Ship an order for labels.
carrier.integration on an option doesn't choose the carrier account. Rates always come from the business's first active shipping integration, or else the platform's. The option's value is only copied into the quote as provider. A provider saved on the Providers tab starts inactive. While it stays inactive it is never used, and it also blocks the platform account: "Shipping integration not configured. Please configure EasyPost or another shipping provider."
Hands on: the location's name.
Check: POST shipping/options for a real address (step 5) shows one option per carrier service.
4. Products: how each product ships
Most products need only a weight and size in parcel: { weight, weightUnit, length, width, height, dimensionUnit }. Weight tiers and weight bounds use it, and carrier rates need it. The rest goes in the product's shipping. Save it with call_appengine POST shipping/admin/product/shipping:
{ "productId": "<product sk or SKU>", "shipping": { "override": "flat", "flatRate": 12.5 } }It changes only the shipping fields sent, each saved as data.shipping.<field>. For many products at once, use POST shipping/admin/products/shipping with { "productIds": [...], "shipping": {...} }. It answers with updated, failed and a row per product.
shipping. field | What it does |
|---|---|
override: "free" | this product ships free, whatever the configurations say. |
override: "flat" + flatRate | this product's shipping is flatRate, once per cart line, whatever the quantity. |
shipsAs | a class: freight, oversize, fragile, hazmat or refrigerated. A classed product is quoted only by options whose productClasses include that class, and ordinary products never by those options. |
shipsAlone | true: quoted and packed on its own, and its price added to the rest. |
config | the name of one configuration. Only that configuration's options quote this product. Rarely needed; prefer shipsAs. |
boxSizes | [{ name, quantity, length, width, height, dimensionUnit, weight, weightUnit }]: how many units fit in one box (quantity) and the box size. Carrier rates use these boxes. |
shipsFrom | a location name this product ships from (carrier rates). |
restrictions.excludeCountries / excludeStates | it never ships there. Checkout says We don't ship <product> to <place>. Choose another address. and holds payment. |
currency | the quote's currency for this product. |
A product with override doesn't use any configuration. When every item in a basket has an override, it is quoted with no configuration at all ("Free shipping", or "Shipping included in the items"). A gift card that isn't physical has nothing to ship.
When the basket holds products that ship differently (a class, shipsAlone, a pinned config), each group is quoted on its own. The options shown are those of the ordinary goods, with the cheapest price of every other group added to each, and groups[] says what ships how. Any group with no option makes the whole quote fail.
On screen. Every field is in the product editor's Shipping section (/product?openId=<sk>): weight and size, Ships As, configuration, ships alone, packaging ("Fits" is quantity), override and flat rate, ships from, and the excluded countries and states. The Product Shipping sub-tab of Storefront › Shipping sets override, flat rate, configuration and ships-from for many products at once. "Use site default" there means no configuration is pinned: every active configuration competes, and isDefault only breaks the last tie.
The editor's Requires signature, Hazmat and Fragile switches don't change shipping. Use shipsAs for anything that must travel differently.
Hands on: the products changed.
Check: open each product on its Shipping section, or repo_find_one on sf_product: data.shipping and data.parcel hold what was sent.
5. Try the quote
Quote a real basket to a real address, with the call the checkout uses:
call_appengine POST shipping/options (no sign-in needed; the site sends the business's orgid):
{
"items": [{ "sku": "<product SKU>", "quantity": 2 }],
"toAddress": { "name": "Test", "street1": "1500 Marilla St", "city": "Dallas", "state": "TX", "zip": "75201", "country": "US" }
}It returns { served, options[], currency, problems?, message? }, cheapest first. Each option has config, label, method, amount, freeShipping, etaDays, breakdown: { base, handling, markup, forced } and groups[]. The first option is what the built-in checkout charges. Items can be named by sku or productId; a variant's SKU finds its product.
The checkout's own figure is POST shipping/calculate with the same body: customerPrice is what it charges. POST shipping/product-cost with { sku, quantity, toAddress } gives one product's shipping, for a product page.
Try at least: an address in each area named, one outside them, a basket over each freeOver, and one heavy basket.
Check: each answer's first option is the price the person expects for that address. Then put the product in the cart on the site and open /checkout with that address: the order summary's Shipping line shows the same amount.
When something goes wrong
| What the checkout or the quote says | Why | Fix |
|---|---|---|
Shipping has not been set up yet — add a shipping configuration to quote rates | no active configuration exists | step 2 |
No shipping option covers TX, US for <SKU> | no option applies to that place and size | add an option that covers it, or widen one (check min/max bounds and restrictions) |
No shipping option carries class "freight" to TX, US (<SKU>) | the product has shipsAs, and no option lists that class | add an option with productClasses: ["freight"], or clear shipsAs |
We don't ship <product> to Alaska. Choose another address. (EXCLUDED_REGION) | the product's shipping.restrictions | a shop rule: the shopper changes the address, or the restriction is removed |
Order is over the 5 lb limit for <label> | the configuration's restrictions.maxWeight | raise it, or add a freight option |
<label> has no origin to rate from — set "Ship From" | carrier option with no origin | step 3 |
<label>: a destination address is required for carrier rates | quoted with no address | send a full address |
<label>: <carrier error> / the carrier returned no services for this address | the carrier refused | check the integration and the product sizes |
Cannot calculate shipping: "<product>" is missing parcel dimensions… / …missing weight | carrier rates for a product with no size | set parcel or shipping.boxSizes |
| Checkout: Delivery quote unavailable and "Payment is unavailable until this order has a valid quote" | any of the above for a full address (code SHIPPING_UNAVAILABLE) | fix it, then Retry quote |
| Shipping shows $0 / Free shipping but nothing was set free | the basket's products are not found in this business's catalog (wrong SKU, deleted, another business's product); unknown items are skipped and quote nothing | fix the cart lines' SKUs; never read a $0 quote as proof shipping works |
The checkout doesn't quote shipping until the address has a name, street, city, state, zip and country. Until then the summary is priced without shipping.
When it's done
Tell the person:
- each configuration's name and what it charges, in plain words ("$10 anywhere in the US, free over $100; $35 international");
- which products ship differently and how;
- the quotes tried: address, basket, price;
- that checkout now quotes, and that the cheapest matching option is what customers pay.
Open Storefront › Shipping on the configuration.
What it can't do yet
- No shipping choice in the built-in checkout. It charges the cheapest option. Offering Standard and Express needs a custom page that lists
shipping/options; the order is still charged what the server's cart calculation decides. - Older engines read only the old shape. Engines before 0.133 (September 2026) ignore
options[]andapplies. They price from the default configuration (isDefault) or the product'sconfig, using the top-levelmethod,flatRate,rates,freeShipping,handlingandrestrictions. A configuration with onlyoptionsfalls back to built-in weight tiers there. Current engines read both: a configuration with nooptionsis one option built from its top-levelmethod,flatRate.rate/perItem,rates.tiers,carrier,pickup,freeShipping,delivery.minDays/maxDaysandapplies.*(includingapplies.priority). Onceoptionsexist, the top-levelmethod,flatRate,rates,deliveryandappliesare ignored. In that old shape,rates.defaultRateandrates.weightUnitare not read either, so a heavy basket on the old shape is quoted $399.99. - Fields saved but never used by the quote:
defaultParcel,delivery.displayText,freeShipping.countries,restrictions.requiresSignature/allowPOBox, and a product'srestrictions.requiresSignature/isHazmat/isFragile. - Classes are a fixed list in Studio (
freight,oversize,fragile,hazmat,refrigerated). The server compares any text, but Studio offers only these. - Free shipping by promotion (a coupon or an automatic campaign) is a discount, not a shipping setting: see Discount codes and automatic discounts. An automatic one frees the cheapest option in the quote, or every option with
freeShippingScope: "any". A free-shipping code takes the whole shipping charge off the checkout total.
Don'ts
- Don't add a free or pickup option open to every address unless every order should ship free: the checkout charges the cheapest.
- Don't invent weights or sizes to get a carrier quote; wrong sizes buy wrong labels later.
- Don't set
isDefaultcasually: it clears the default on every other configuration. - Don't delete a configuration that orders were quoted from without asking.
POST shipping/admin/configs/delete/<name>is permanent. - Don't treat a $0 quote as working shipping until a real product's SKU has been quoted.