--- id: CAP-COM-FUL-010 title: Configure shipping coverage and collection options feature: FEAT-COM-FUL-03 product_area: commerce module: fulfillment revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: - CAP-COM-SHP-001 - CAP-COM-SHP-002 - CAP-COM-SHP-003 source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b intent_sources: - >- services-commerce:docs/migrations/shipping/README.md#D-P8S-17 (Q06, Andrew 2026-10-19) - >- services-commerce:docs/migrations/shipping/README.md#D-P8S-14 (decision L, Andrew 2026-10-18) - >- services-commerce:docs/migrations/shipping/README.md#D-P8S-15 (Andrew 2026-10-18 21:10 UTC) purpose: >- Administrators establish delivery destinations, charges and carrier connections. outcomes: - Destination configuration supports the appropriate shipping charge. - Commerce retains carrier references without credentials. concepts: - CON-COM-FUL-004 actors: - ACT-COM-009 surfaces: - api preconditions: [] postconditions: [] permissions: - key: commerce.shipping-zones.read where_checked: api scope: tenant - key: commerce.shipping-zones.create where_checked: api scope: tenant - key: commerce.shipping-zones.update where_checked: api scope: tenant - key: commerce.shipping-zones.delete where_checked: api scope: tenant - key: commerce.shipping-strategies.read where_checked: api scope: tenant - key: commerce.shipping-strategies.create where_checked: api scope: tenant - key: commerce.shipping-strategies.update where_checked: api scope: tenant - key: commerce.shipping-strategies.delete where_checked: api scope: tenant - key: commerce.carrier-accounts.read where_checked: api scope: tenant - key: commerce.carrier-accounts.create where_checked: api scope: tenant - key: commerce.carrier-accounts.update where_checked: api scope: tenant - key: commerce.carrier-accounts.delete where_checked: api scope: tenant rules: - id: BR-CAP-COM-FUL-010-01 proved_by: [ATS-COM-FUL-010-01, TST-COM-FUL-075, TST-COM-FUL-077, TST-COM-FUL-083] statement: >- Shipping zones accept uppercase two-letter countries with optional regions and postal prefixes, reject blank values by field, and clear descriptions only through an explicit empty value. kind: validation enforced_at: - api - database must_prove: true provenance: test source: >- services-commerce:modules/shipping/tests/unit/api/blank-shipping-configuration-values.spec.js#refuses a zone with region_codes [""] 400 naming region_codes, instead of making a zone of no region origin: >- Q06, Andrew 2026-10-19: services-commerce:docs/migrations/shipping/README.md#D-P8S-17 - id: BR-CAP-COM-FUL-010-02 proved_by: [ATS-COM-FUL-010-02, TST-COM-FUL-077, TST-COM-FUL-081] statement: >- Zone creation uses a supplied identity or one derived from its name, uppercases stored countries, rejects duplicate identities and requires the current version for replacement. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/shipping/tests/integration/services/persistence/shipping-configuration.integration.spec.js#replaces it at the version read, and refuses the stale version 409 origin: none - id: BR-CAP-COM-FUL-010-03 proved_by: [ATS-COM-FUL-010-02, TST-COM-FUL-077, TST-COM-FUL-081] statement: Zone deletion also removes the zone's shipping strategies. kind: lifecycle enforced_at: - database must_prove: true provenance: test source: >- services-commerce:modules/shipping/tests/integration/services/persistence/shipping-configuration.integration.spec.js#refuses a taken id 400, and deletes a zone with its strategies (404 after) origin: none - id: BR-CAP-COM-FUL-010-04 proved_by: [ATS-COM-FUL-010-03, TST-COM-FUL-075, TST-COM-FUL-077, TST-COM-FUL-081] statement: >- Strategies support flat, per-unit, weight-band, carrier and pickup charging; bands ascend with an unbounded final band, and only carrier strategies reference carrier accounts. kind: validation enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/shipping/tests/integration/services/persistence/shipping-configuration.integration.spec.js#holds the rules before the row: bands in ascending order with the open one last, a carrier naming its account, no bands on a flat one origin: none - id: BR-CAP-COM-FUL-010-05 proved_by: [ATS-COM-FUL-010-03, ATS-COM-FUL-010-08, ATS-COM-FUL-016-09, TST-COM-FUL-075, TST-COM-FUL-077, TST-COM-FUL-081] statement: >- Pickup strategies identify exactly one warehouse or location, charge zero and prevent deletion of their referenced warehouse. kind: validation enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/shipping/tests/integration/db/shipping-tables.table.integration.spec.js#holds a pickup strategy to naming where the buyer collects and charging nothing, by shipping_strategies_pickup_check 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-010-06 proved_by: [ATS-COM-FUL-010-04, TST-COM-FUL-075, TST-COM-FUL-077, TST-COM-FUL-081] statement: >- Carrier accounts select one of six carriers, limit markup to 100 percent and store connection references and shipper numbers without credentials. kind: validation enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/shipping/tests/integration/db/shipping-tables.table.integration.spec.js#refuses a carrier outside the six and a markup above 100 %, by carrier_accounts_carrier_check and carrier_accounts_markup_check origin: none - id: BR-CAP-COM-FUL-010-07 proved_by: [ATS-COM-FUL-010-04, ATS-COM-FUL-010-07, ATS-COM-FUL-013-09, TST-COM-FUL-075, TST-COM-FUL-077, TST-COM-FUL-081] statement: >- UPS account creation and replacement require an Integration Platform connection reference. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/shipping/tests/integration/services/persistence/shipping-configuration.integration.spec.js#refuses a UPS account without its Integration Platform connection 400 connection_required, writing nothing 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-010-08 proved_by: [ATS-COM-FUL-010-04, TST-COM-FUL-075, TST-COM-FUL-077, TST-COM-FUL-081] statement: A carrier account referenced by a rating strategy cannot be deleted. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/shipping/tests/integration/services/persistence/shipping-configuration.integration.spec.js#writes an account with its connection reference and shipper number and no secret, lists by carrier, and refuses deleting one a strategy rates through (409) origin: none - id: BR-CAP-COM-FUL-010-09 proved_by: [ATS-COM-FUL-010-05, TST-COM-FUL-075] statement: >- Shipping-configuration reads permit readers, writes require their administrator permissions, application-denied callers are refused and missing authentication is rejected. kind: permission enforced_at: - api must_prove: true provenance: observed source: 'services-commerce:modules/shipping/aws/api/shipping.routes.ts' origin: none - id: BR-CAP-COM-FUL-010-10 proved_by: [ATS-COM-FUL-010-06, ATS-COM-FUL-011-10] statement: >- Zone lists support search and priority order, and rating reads active zones with active strategies ordered by position. kind: policy enforced_at: - service must_prove: false provenance: test source: >- services-commerce:modules/shipping/tests/integration/services/persistence/shipping-configuration.integration.spec.js#lists the zones in priority order, by search, and the active ones with their active strategies in position order origin: none scenarios: - id: SC-CAP-COM-FUL-010-01 given: A Texas zone has flat and UPS strategies. when: Read the configuration and replace the zone using its current version. then: The service returns the zone and strategies and advances its version. provenance: test source: >- services-commerce:modules/shipping/tests/e2e/shipping.e2e.spec.js#reads the zone made with the world, lists the zones in priority order, replaces one at the version read, and deletes a zone with its strategies edge_cases: [] constraints: [] depends_on: - CAP-COM-FUL-016 related: - CAP-COM-FUL-011 - CAP-COM-FUL-013 journeys: - JNY-COM-FUL-003 open_questions: [] evidence: - repository: services-commerce paths: - >- modules/shipping/tests/unit/api/blank-shipping-configuration-values.spec.js - >- modules/shipping/tests/integration/services/persistence/shipping-configuration.integration.spec.js - >- modules/shipping/tests/integration/db/shipping-tables.table.integration.spec.js - modules/shipping/aws/api/shipping.routes.ts controls: [TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, 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-DAT-004, TC-LOG-004, TC-PI-001, TC-PI-003, TC-PI-005, TC-VEN-001, TC-VEN-002, TC-VEN-003] exercised_by: [FAS-COM-FUL-03-01, FAS-COM-FUL-03-04] suites: [TST-COM-FUL-075, TST-COM-FUL-077, TST-COM-FUL-081, TST-COM-FUL-083] --- # Configure shipping coverage and collection options ## Purpose Administrators establish delivery destinations, charges and carrier connections. ## How It Works An administrator defines zones and the strategies available within them. Strategies describe charging methods or collection at a warehouse or location. Carrier accounts hold the references needed to reach the Integration Platform. Staff configuration changes use current record versions and respect existing dependencies. Cart rating later consumes the active configuration. The service provides these controls without a complete shipping-configuration console workflow. The product should provide configuration review that explains the customer choices each change affects. ## Relationships - Organize warehouses and stock locations supplies or consumes related delivery records. - Quote shipping and pickup choices for a cart supplies or consumes related delivery records. - Purchase and follow carrier labels safely supplies or consumes related delivery records.