Quote shipping and pickup choices for a cart

Purpose

Buyers receive shipping choices and charges appropriate to their cart and destination.

How It Works

Commerce first determines whether the cart contains goods needing shipment. It matches the destination against active zones and rates the available strategies. Carrier quotations arrive through the configured connection. Pickup appears as a collection choice with its location. Choosing an option changes the cart's shipping charge, and placement retains the chosen destination and charge. Missing coverage or a failed quote can produce warnings that staff must interpret. The product should make those warnings clear enough to prevent an unintended delivery promise.

Relationships

Configure shipping coverage and collection options supplies or consumes related delivery records.
Prepare an order's goods for dispatch supplies or consumes related delivery records.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: Shipping choices show their charges before placement.Placement retains the buyer's selected shipping charge.
Surfaces: api
Intent sources: services-commerce:docs/migrations/shipping/README.md#D-P8S-14 (decision L, Andrew 2026-10-18)

Controls

27 controls apply, from the corpus control catalogue.

TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-006 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-SEC-001 TC-SEC-002 TC-SEC-003 TC-SEC-004 TC-CRY-001 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-005 TC-VEN-001 TC-VEN-002 TC-VEN-003 TC-PRV-001 TC-PRV-002

Business Rules

10 rules, 10 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	A cart without shippable goods requires no shipping, incurs zero charge and reads no zone. proved by `ATS-COM-FUL-011-01`, `TST-COM-FUL-075`, `TST-COM-FUL-081`	policy	service	test services-commerce:modules/shipping/tests/integration/services/persistence/shipping-configuration.integration.spec.js#requires no shipping for a checkout of an e-book alone: no option, zero, no zone consulted
`02`must prove Proposed	An active zone must match every configured address restriction, with case-insensitive regions and space-insensitive postal prefixes; unrestricted zones match even absent addresses, and specificity ranks prefix, region, country and unrestricted matches before priority, name and identity. proved by `ATS-COM-FUL-010-06`, `ATS-COM-FUL-011-02`, `ATS-COM-FUL-011-10`, `TST-COM-FUL-085`	calculation	service	test services-commerce:modules/shipping/tests/unit/rating/zone-strategy-rating.spec.js#ranks a prefix over a region over a country over anywhere
`03`must prove Proposed	Flat strategies charge once, per-unit strategies add one base charge plus a charge per physical unit, and weight bands use the first fitting band or leave excess weight unrated. ✓ five shirts at 1.50 per unit plus 2.00 base: 9.50✗ one line of five charged once per line proved by `ATS-COM-FUL-011-03`, `TST-COM-FUL-085`	calculation	service	test services-commerce:modules/shipping/tests/unit/rating/zone-strategy-rating.spec.js#charges a per-unit strategy per UNIT shipped, never per line, plus its base once
`04`must prove Proposed	A strategy becomes free at its merchandise-subtotal threshold and is excluded when its currency differs from the cart. proved by `ATS-COM-FUL-011-03`, `TST-COM-FUL-085`	calculation	service	test services-commerce:modules/shipping/tests/unit/rating/zone-strategy-rating.spec.js#makes an option free at or above free_above_minor, measured against the merchandise subtotal
`05`must prove Proposed	No matching zone or no option in the cart currency produces zero shipping charge and a warning. proved by `ATS-COM-FUL-011-04`, `TST-COM-FUL-081`	policy	service	test services-commerce:modules/shipping/tests/integration/services/persistence/shipping-configuration.integration.spec.js#charges nothing with a warning when no zone matches (the worldwide zone inactive) and when the zone offers no option in the currency
`06`must prove Proposed	Carrier rating uses the account's Integration Platform connection and markup rounded half away from zero, with failed quotes yielding warnings and no option rather than failing checkout. origin: UPS through the Integration Platform, Andrew 2026-10-18 21:10 UTC ("move it now"): services-commerce:docs/migrations/shipping/README.md#D-P8S-15 proved by `ATS-COM-FUL-011-05`, `TST-COM-FUL-075`, `TST-COM-FUL-084`	calculation	service	test services-commerce:modules/shipping/tests/unit/carriers/carrier-adapters.spec.js#applies the markup in basis points, rounding half away from zero
`07`must prove Proposed	An absent or cleared choice selects the first option, an explicitly unavailable choice is rejected, and an obsolete saved choice falls back to the first option with a warning. origin: DEF-COM-0868 (acceptance defect) proved by `ATS-COM-FUL-011-06`, `TST-COM-FUL-075`, `TST-COM-FUL-081`	validation	api, service	test services-commerce:modules/shipping/tests/e2e/shipping.e2e.spec.js#re-rates with the buyer’s choice (five units at 150), and refuses a strategy the zone does not offer 400 shipping_option_unavailable
`08`must prove Proposed	Pickup options appear alongside shipped options at zero charge with collection details, except when their warehouse is inactive. origin: Decision L, Andrew 2026-10-18 ("add it now"): services-commerce:docs/migrations/shipping/README.md#D-P8S-14 proved by `ATS-COM-FUL-011-07`, `ATS-COM-FUL-011-11`, `ATS-COM-FUL-012-09`, `TST-COM-FUL-075`, `TST-COM-FUL-081`, `TST-COM-FUL-085`	policy	service	test services-commerce:modules/shipping/tests/integration/services/persistence/shipping-configuration.integration.spec.js#offers each pick-up at zero beside the zone’s shipped options, kind pickup, with where the buyer collects
`09`must prove Proposed	Placement appends a shipping-product line, freezes destination and chosen option, and rejects placement entirely if the ordering profile lacks a required shipping product. origin: DEF-COM-0873 (acceptance defect) proved by `ATS-COM-FUL-011-08`, `TST-COM-FUL-075`	policy	service	test services-commerce:modules/shipping/tests/e2e/shipping.e2e.spec.js#places the order with the charge, the shipping line on the shipping product after the item line, the ship-to address frozen and the choice in the snapshot
`10`must prove Proposed	Shipping rating reads zones only within the current workspace. proved by `ATS-COM-FUL-011-09`, `TST-COM-FUL-081`	invariant	database	test services-commerce:modules/shipping/tests/integration/services/persistence/shipping-configuration.integration.spec.js#never reads another tenant’s zones: the other tenant’s rating sees its own domestic zone, not this tenant’s changes

Scenarios

Id	Given	When	Then	Provenance
`01`	Five shirts are addressed to Texas where flat and UPS options apply.	Preview the cart's shipping choices.	Both choices appear, the flat choice is initially selected and its charge contributes to totals.	test services-commerce:modules/shipping/tests/e2e/shipping.e2e.spec.js#answers shipping_required true with the Texas zone’s two options, the flat one selected, the charge in the totals

Edge Cases

Id	Given	When	Then	Provenance
`02`	The cart contains only an electronic book.	Preview shipping.	The result has no shipping requirement, options or charge.	test services-commerce:modules/shipping/tests/e2e/shipping.e2e.spec.js#answers shipping_required false, no option and no charge for a cart of an e-book

Planning

Implementation

Quote shipping and pickup choices for a cart ​

Purpose ​

How It Works ​

Relationships ​