docs
/
AI skills

Shipping rates and settings

Shipping configurations the checkout can quote from (flat, per item, weight tiers, live carrier rates, pickup, free), scoped by place, weight, quantity and order value, plus each product's own shipping settings, tried with a real quote before anyone checks out.

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[]):

FieldWhat it does
labelwhat the customer sees. Default: the configuration's title plus a number.
statusinactive takes the option out of every quote.
methodflat, weight, carrier, pickup or free (below). Anything else, including the old zone, quotes nothing and reports … uses an unsupported method "zone".
ratethe price for flat; for weight, the price when no tier fits.
perItemtrue: rate × the number of items.
freeOverfree when the order total is at or above this.
tiersfor weight: [{ name, maxWeight, maxLength, maxWidth, maxHeight, maxGirth, rate }], first fit wins.
carrierfor carrier: { integration, allowedServices: ["Ground", …] }.
pickupfor pickup: { locations: [<location name>], fee, readyInHours, instructions }.
countries, states, postcodeswhere it applies. All empty = anywhere.
minWeight / maxWeight / weightUnittotal basket weight bounds (lb default, or kg).
minQuantity / maxQuantitynumber of items.
minOrderTotal / maxOrderTotalorder value.
productClassesthe classes this option carries (step 4). Empty = ordinary goods only.
minDays / maxDaysthe delivery estimate shown with the option.
prioritybreaks ties between options (see the warning below).
currencyoverrides the configuration's currency.

Configuration fields that apply to every option in it:

FieldWhat it does
nameunique, letters, digits, - and _. Can't be changed later.
title, currency (default USD), statusstatus: "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.
restrictionsexcludeCountries, excludeStates: none of its options apply there. maxWeight + maxWeightUnit: over it, the options in this configuration quote nothing.
originShip 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.
isDefaultmarks 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.

  • countries and states are codes: US, TX.
  • A postcode rule is exact (75201), a prefix (752*) or a numeric range, both ends included (75000-75199). Spaces are ignored, so SW1A* matches SW1A 1AA.
  • When an option names more than one of countries, states and postcodes, 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. rate for the order, or rate × items with perItem: true.
  • weight. The first tier the basket fits is charged. Within a tier the max is inclusive: a 3 lb basket fits maxWeight: 3. Dimensions are the largest single item's. If no tier fits, rate is charged. Set rate for every weight option: with no rate, 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 with Cannot calculate shipping: "<product>" is missing parcel dimensions…. allowedServices keeps only services whose code contains one of the words. The carrier block's own markup (fixed) and markupPercent are added before the configuration's markup.
  • pickup. pickup.fee (default 0). readyInHours becomes the estimate ("Ready in 24h"). locations and instructions come 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:

FieldWhy 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, maxGirththe form edits only name, maxWeight and rate
freeOver on a method other than flatthe form shows "Free above" for flat options only
markup.fixedAmount when markup is Boththe 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.

The form's own text is wrong in two places.
  • 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:

  1. a product's shipping.shipsFrom (a location name);
  2. the configuration's origin;
  3. 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. fieldWhat it does
override: "free"this product ships free, whatever the configurations say.
override: "flat" + flatRatethis product's shipping is flatRate, once per cart line, whatever the quantity.
shipsAsa 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.
shipsAlonetrue: quoted and packed on its own, and its price added to the rest.
configthe 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.
shipsFroma location name this product ships from (carrier rates).
restrictions.excludeCountries / excludeStatesit never ships there. Checkout says We don't ship <product> to <place>. Choose another address. and holds payment.
currencythe 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 saysWhyFix
Shipping has not been set up yet — add a shipping configuration to quote ratesno active configuration existsstep 2
No shipping option covers TX, US for <SKU>no option applies to that place and sizeadd 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 classadd an option with productClasses: ["freight"], or clear shipsAs
We don't ship <product> to Alaska. Choose another address. (EXCLUDED_REGION)the product's shipping.restrictionsa 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.maxWeightraise it, or add a freight option
<label> has no origin to rate from — set "Ship From"carrier option with no originstep 3
<label>: a destination address is required for carrier ratesquoted with no addresssend a full address
<label>: <carrier error> / the carrier returned no services for this addressthe carrier refusedcheck the integration and the product sizes
Cannot calculate shipping: "<product>" is missing parcel dimensions… / …missing weightcarrier rates for a product with no sizeset 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 freethe basket's products are not found in this business's catalog (wrong SKU, deleted, another business's product); unknown items are skipped and quote nothingfix 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[] and applies. They price from the default configuration (isDefault) or the product's config, using the top-level method, flatRate, rates, freeShipping, handling and restrictions. A configuration with only options falls back to built-in weight tiers there. Current engines read both: a configuration with no options is one option built from its top-level method, flatRate.rate / perItem, rates.tiers, carrier, pickup, freeShipping, delivery.minDays / maxDays and applies.* (including applies.priority). Once options exist, the top-level method, flatRate, rates, delivery and applies are ignored. In that old shape, rates.defaultRate and rates.weightUnit are 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's restrictions.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 isDefault casually: 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.