--- id: CAP-COM-FUL-011 title: Quote shipping and pickup choices for a cart feature: FEAT-COM-FUL-03 product_area: commerce module: fulfillment revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: - CAP-COM-SHP-004 source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b intent_sources: - >- services-commerce:docs/migrations/shipping/README.md#D-P8S-14 (decision L, Andrew 2026-10-18) purpose: >- Buyers receive shipping choices and charges appropriate to their cart and destination. outcomes: - Shipping choices show their charges before placement. - Placement retains the buyer's selected shipping charge. concepts: - CON-COM-FUL-004 actors: - ACT-COM-008 surfaces: - api preconditions: [] postconditions: [] permissions: [] rules: - id: BR-CAP-COM-FUL-011-01 proved_by: [ATS-COM-FUL-011-01, TST-COM-FUL-075, TST-COM-FUL-081] statement: >- A cart without shippable goods requires no shipping, incurs zero charge and reads no zone. kind: policy enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-COM-FUL-011-02 proved_by: [ATS-COM-FUL-010-06, ATS-COM-FUL-011-02, ATS-COM-FUL-011-10, TST-COM-FUL-085] statement: >- 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. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/shipping/tests/unit/rating/zone-strategy-rating.spec.js#ranks a prefix over a region over a country over anywhere origin: none - id: BR-CAP-COM-FUL-011-03 proved_by: [ATS-COM-FUL-011-03, TST-COM-FUL-085] statement: >- 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. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none examples: positive: 'five shirts at 1.50 per unit plus 2.00 base: 9.50' negative: one line of five charged once per line - id: BR-CAP-COM-FUL-011-04 proved_by: [ATS-COM-FUL-011-03, TST-COM-FUL-085] statement: >- A strategy becomes free at its merchandise-subtotal threshold and is excluded when its currency differs from the cart. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-COM-FUL-011-05 proved_by: [ATS-COM-FUL-011-04, TST-COM-FUL-081] statement: >- No matching zone or no option in the cart currency produces zero shipping charge and a warning. kind: policy enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-COM-FUL-011-06 proved_by: [ATS-COM-FUL-011-05, TST-COM-FUL-075, TST-COM-FUL-084] statement: >- 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. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/shipping/tests/unit/carriers/carrier-adapters.spec.js#applies the markup in basis points, rounding half away from zero 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 - id: BR-CAP-COM-FUL-011-07 proved_by: [ATS-COM-FUL-011-06, TST-COM-FUL-075, TST-COM-FUL-081] statement: >- 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. kind: validation enforced_at: - api - service must_prove: true provenance: test source: >- 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 origin: DEF-COM-0868 (acceptance defect) - id: BR-CAP-COM-FUL-011-08 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] statement: >- Pickup options appear alongside shipped options at zero charge with collection details, except when their warehouse is inactive. kind: policy enforced_at: - service must_prove: true provenance: test source: >- 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 origin: >- Decision L, Andrew 2026-10-18 ("add it now"): services-commerce:docs/migrations/shipping/README.md#D-P8S-14 - id: BR-CAP-COM-FUL-011-09 proved_by: [ATS-COM-FUL-011-08, TST-COM-FUL-075] statement: >- Placement appends a shipping-product line, freezes destination and chosen option, and rejects placement entirely if the ordering profile lacks a required shipping product. kind: policy enforced_at: - service must_prove: true provenance: test source: >- 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 origin: DEF-COM-0873 (acceptance defect) - id: BR-CAP-COM-FUL-011-10 proved_by: [ATS-COM-FUL-011-09, TST-COM-FUL-081] statement: Shipping rating reads zones only within the current workspace. kind: invariant enforced_at: - database must_prove: true provenance: test source: >- 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 origin: none scenarios: - id: SC-CAP-COM-FUL-011-01 given: Five shirts are addressed to Texas where flat and UPS options apply. when: Preview the cart's shipping choices. then: >- Both choices appear, the flat choice is initially selected and its charge contributes to totals. provenance: test source: >- 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: SC-CAP-COM-FUL-011-02 given: The cart contains only an electronic book. when: Preview shipping. then: 'The result has no shipping requirement, options or charge.' provenance: test source: >- 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 constraints: [] depends_on: - CAP-COM-FUL-010 related: - CAP-COM-FUL-012 journeys: - JNY-COM-FUL-003 open_questions: [] evidence: - repository: services-commerce paths: - >- modules/shipping/tests/integration/services/persistence/shipping-configuration.integration.spec.js - modules/shipping/tests/unit/rating/zone-strategy-rating.spec.js - modules/shipping/tests/unit/carriers/carrier-adapters.spec.js - modules/shipping/tests/e2e/shipping.e2e.spec.js controls: [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] exercised_by: [FAS-COM-FUL-03-01, FAS-COM-FUL-03-03] suites: [TST-COM-FUL-075, TST-COM-FUL-081, TST-COM-FUL-084, TST-COM-FUL-085] --- # 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.