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.

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: Destination configuration supports the appropriate shipping charge.Commerce retains carrier references without credentials.
Surfaces: api
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)

Controls

21 controls apply, from the corpus control catalogue.

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

Permissions

Key	Checked at	Scope
`commerce.shipping-zones.read`	api	tenant
`commerce.shipping-zones.create`	api	tenant
`commerce.shipping-zones.update`	api	tenant
`commerce.shipping-zones.delete`	api	tenant
`commerce.shipping-strategies.read`	api	tenant
`commerce.shipping-strategies.create`	api	tenant
`commerce.shipping-strategies.update`	api	tenant
`commerce.shipping-strategies.delete`	api	tenant
`commerce.carrier-accounts.read`	api	tenant
`commerce.carrier-accounts.create`	api	tenant
`commerce.carrier-accounts.update`	api	tenant
`commerce.carrier-accounts.delete`	api	tenant

Business Rules

10 rules, 9 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	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. origin: Q06, Andrew 2026-10-19: services-commerce:docs/migrations/shipping/README.md#D-P8S-17 no proof recorded yet	validation	api, database	test 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
`02`must prove Proposed	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. no proof recorded yet	validation	service	test 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
`03`must prove Proposed	Zone deletion also removes the zone's shipping strategies. no proof recorded yet	lifecycle	database	test 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)
`04`must prove Proposed	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. no proof recorded yet	validation	service, database	test 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
`05`must prove Proposed	Pickup strategies identify exactly one warehouse or location, charge zero and prevent deletion of their referenced warehouse. origin: Decision L, Andrew 2026-10-18 ("add it now"): services-commerce:docs/migrations/shipping/README.md#D-P8S-14 no proof recorded yet	validation	service, database	test 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
`06`must prove Proposed	Carrier accounts select one of six carriers, limit markup to 100 percent and store connection references and shipper numbers without credentials. no proof recorded yet	validation	service, database	test 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
`07`must prove Proposed	UPS account creation and replacement require an Integration Platform connection reference. 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 no proof recorded yet	validation	service	test 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
`08`must prove Proposed	A carrier account referenced by a rating strategy cannot be deleted. no proof recorded yet	invariant	service, database	test 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)
`09`must prove Proposed	Shipping-configuration reads permit readers, writes require their administrator permissions, application-denied callers are refused and missing authentication is rejected. no proof recorded yet	permission	api	observed services-commerce:modules/shipping/aws/api/shipping.routes.ts
`10` Proposed	Zone lists support search and priority order, and rating reads active zones with active strategies ordered by position.	policy	service	test 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

Scenarios

Id	Given	When	Then	Provenance
`01`	A Texas zone has flat and UPS strategies.	Read the configuration and replace the zone using its current version.	The service returns the zone and strategies and advances its version.	test 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

Planning

Configure shipping coverage and collection options ​

Purpose ​

How It Works ​

Relationships ​