Record goods leaving with a carrier or collector

Purpose

Warehouse handover aligns physical departure with delivery, stock and order records.

How It Works

Staff confirm carrier handoff after manifesting or pickup handover after packing. Commerce checks the shipment's units against delivery authorization and cancellation fencing. The successful step changes the stock ledger, obligations and order shipping view together. It also calls the configured cost-relief provider within that transaction. A refusal records the problem without moving units. Collection additionally records the person receiving the goods. The product should give warehouse staff a visible departure confirmation and an actionable refusal explanation.

Relationships

Prepare an order's goods for dispatch supplies or consumes related delivery records.
Carry authorized work to its delivering application supplies or consumes related delivery records.
Allocate stock and explain what buyers can obtain 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: Physical departure connects stock, delivery and cost processing.Cancellation contention prevents the same unit from both shipping and cancelling.
Surfaces: api
Intent sources: services-commerce:docs/migrations/shipping/README.md#D-P8S-14 (decision L, Andrew 2026-10-18)

Controls

28 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-CRY-001 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-DAT-004 TC-LOG-001 TC-LOG-002 TC-LOG-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

Permissions

Key	Checked at	Scope
`commerce.shipments.handoff`	api	tenant
`commerce.shipments.handover`	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	Carrier handoff atomically advances a manifested shipment's whole line quantities, ships allocations, reduces on-hand through shipment movements, completes unit obligations, invokes cost relief and updates order shipping quantities and summary. no proof recorded yet	invariant	service, database	test services-commerce:modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js#hands off: the line handed to the carrier with its whole quantity shipped, the units shipped in the ledger, one shipment movement of minus three on the item, three fewer on hand
`02`must prove Proposed	Handoff rejects units without register authorization, moves no stock and records a refusal finding and shipment-history entry. no proof recorded yet	validation	service	test services-commerce:modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js#refuses units_not_authorized, naming the obligation still pending, and moves nothing: the unit committed, nothing shipped, the shipment still manifested
`03`must prove Proposed	Only manifested shipments accept carrier handoff, and repeated handoff is rejected and recorded. no proof recorded yet	validation	service	test services-commerce:modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js#refuses a second handoff of the same shipment (not manifested any more) and records the refusal
`04`must prove Proposed	Cancellation fences the shipment line's entire unit range, causing handoff to reject the shipment without movement and require parcel removal. no proof recorded yet	invariant	service, database	test services-commerce:modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js#refuses the handoff shipment_cancelled_pull_package, naming the fenced line, and moves nothing
`05`must prove Proposed	Shipment-line locking determines whether cancellation or handoff wins a race, and goods already handed over require a return. no proof recorded yet	invariant	service, database	test services-commerce:modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js#lets the handoff commit, and the cancellation that waited finds the line already handed off: refused, nothing fenced
`06`must prove Proposed	Committed cancellation cancels fenced lines, removes shipment stamps while retaining picked order allocations, voids labels on parcels carrying no retained lines and pulls those parcels so retained units can use a new shipment. no proof recorded yet	lifecycle	service	test services-commerce:modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js#cancels the fenced line at the cancel step: the units unstamped (still the order’s, picked), the label voided and the package pulled, the shipment cancelled
`07`must prove Proposed	Counter handover of a packed pickup records the collector and applies the same stock, obligation, cost-relief and order-quantity changes as carrier handoff. origin: Decision L, Andrew 2026-10-18 ("add it now"): services-commerce:docs/migrations/shipping/README.md#D-P8S-14 no proof recorded yet	lifecycle	service	test services-commerce:modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js#moves the stock as the handoff does: the units shipped, one shipment movement of minus two (reason handover), two fewer on hand
`08`must prove Proposed	Counter handover rejects missing collector identity, carrier shipments, shipments no longer packed and cancellation-fenced lines. 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	api, service	test services-commerce:modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js#refuses the handover of a pick-up whose line the cancellation fenced, shipment_cancelled_pull_package, and moves nothing
`09`must prove Proposed	Carrier handoff requires its handoff permission, while counter handover requires sensitive administrator authority. origin: Decision L, Andrew 2026-10-18 ("add it now"): services-commerce:docs/migrations/shipping/README.md#D-P8S-14 no proof recorded yet	permission	api	observed services-commerce:modules/shipping/aws/api/shipping.routes.ts
`10` Proposed	Handoff invokes the selected cost-relief provider within its transaction; the fixture permits deferred relief and the running layers provider determines actual cost relief. origin: Decision O, Andrew 2026-10-18 (as built, not contested): services-commerce:docs/migrations/shipping/README.md#Section 9 walkthrough	policy	service	observed services-commerce:modules/shipping/services/cost/cost-relief-port.ts:commerceCostReliefPort

Scenarios

Id	Given	When	Then	Provenance
`01`	A manifested shipment carries three shirts in two parcels.	Confirm departure with the carrier.	Stock decreases by three, obligations complete, deferred cost facts are emitted and shipped quantities update.	test services-commerce:modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js#completes every unit’s obligation through the register (the allocation as the record), and emits one deferred cost relief fact per item
`02`	A pickup shipment is packed for collection.	Record the collecting buyer and confirm handover.	The line records shipment and the order's shipping work becomes complete.	test services-commerce:modules/shipping/tests/e2e/shipping.e2e.spec.js#hands the pick-up over through the route: collected by the buyer, the line shipped, the order’s shipping complete

Planning

Record goods leaving with a carrier or collector ​

Purpose ​

How It Works ​

Relationships ​