--- id: DOM-COM-FUL-004 title: Shipment realises: CON-COM-FUL-004 product_area: commerce module: fulfillment revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-COM-FUL-shipping readable_by: - SVC-COM-FUL-inventory - SVC-COM-FUL-fulfillment lifecycle: STATE-COM-FUL-005 custom_fields: none identity: >- Workspace numbers identify shipments, pick lists and return receipts. Parcels have shipment-local sequences; label attempts use carrier purchase keys, and configuration records keep stable identities. attributes: - name: number kind: text required: true computed: true notes: Provides the workspace shipment number used on warehouse documents. - name: kind kind: enum required: true computed: false notes: 'Distinguishes outbound work, return labels, replacement work and pickup.' - name: order and warehouse kind: reference required: true computed: false notes: Identifies the order and the warehouse supplying its physical units. - name: ship-to kind: collection required: false computed: false notes: >- Retains the destination snapshot selected from saved order shipping facts or the party address fallback. - name: 'carrier, service and strategy' kind: reference required: false computed: false notes: >- Retains the selected carrier account, service and strategy; pickup has no carrier. - name: customer shipping charge kind: money required: false computed: false notes: >- Retains the buyer’s order charge separately from each label’s carrier cost. - name: state and its instants kind: enum required: true computed: false notes: >- Retains warehouse progress and its timestamps through departure and later carrier outcomes. - name: collected by kind: text required: false computed: false notes: Names the person receiving a pickup at the counter. - name: lines kind: collection required: true computed: false notes: >- Retains contiguous order-line units, their allocations, SKU, weight and warehouse quantities. - name: parcels kind: collection required: false computed: false notes: >- Retains parcel sequence, dimensions, contents, tracking and current label reference. - name: carrier labels kind: collection required: false computed: false notes: >- Retains keyed carrier purchase attempts with result, tracking, cost and label format. - name: pick lists kind: collection required: false computed: false notes: >- Retains numbered warehouse picking batches with picker, location and full or short results. - name: return receipts kind: collection required: false computed: false notes: >- Retains numbered authorized receiving facts, line condition and disposition quantities. - name: history kind: collection required: true computed: false notes: >- Retains immutable shipment progression, carrier updates and refusal diagnoses. - name: shipping zones kind: collection required: false computed: false notes: 'Defines geographic coverage, priority and active selection.' - name: shipping strategies kind: collection required: false computed: false notes: >- Defines zone charging through flat, unit, weight-band, carrier-rate or pickup options with currency and promise. - name: carrier accounts kind: collection required: false computed: false notes: >- Stores carrier and connection references, service restrictions and markup while keeping secrets outside Commerce. relationships: - to: DOM-COM-FUL-005 cardinality: >- One shipment line carries one to many allocation units; one return disposition writes zero or one movement. ownership: >- The allocation units name the shipment line; the movement names the line or disposition. cross_service: true - to: DOM-COM-FUL-001 cardinality: >- A shipment line can match multiple unit obligations; the handoff implementation does not prove that every departing unit has a match. ownership: The obligation records the completion. cross_service: true invariants: - id: INV-DOM-COM-FUL-004-01 statement: >- Workspace constraints make shipment, pick-list and receipt numbers unique, along with non-null parcel tracking numbers. enforced_at: - database provenance: observed source: >- services-commerce:modules/shipping/db/shipments.table.ts; packages.table.ts; pick-lists.table.ts; return-receipts.table.ts - id: INV-DOM-COM-FUL-004-02 statement: >- A shipment line’s quantity matches its unit range, with picked, packed and shipped totals bounded by that quantity. enforced_at: - database provenance: observed source: 'services-commerce:modules/shipping/db/shipment-lines.table.ts' - id: INV-DOM-COM-FUL-004-03 statement: >- Handoff commits line departure, allocations, stock movements, matching obligation completion and cost-provider work together. enforced_at: - service provenance: test source: >- 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 - id: INV-DOM-COM-FUL-004-04 statement: >- Handoff rejects an invalid matching obligation but does not check that every allocation has a matching obligation. enforced_at: - service provenance: observed source: >- services-commerce:modules/shipping/services/fulfillment/handoff.ts:obligationsOfUnits - id: INV-DOM-COM-FUL-004-05 statement: >- The shipment-line conditional writes decide between cancellation fencing and handoff. enforced_at: - database - service provenance: observed source: >- services-commerce:modules/shipping/services/persistence/shipments.ts:fenceLinesForCancellation,handoffLinesOfShipment - id: INV-DOM-COM-FUL-004-06 statement: >- Label purchase retains intent before calling the carrier and resolves uncertainty under the existing key. enforced_at: - service - database provenance: documented source: 'services-commerce:docs/migrations/shipping/README.md#D-P8S-08' - id: INV-DOM-COM-FUL-004-07 statement: Database checks separate pickup collection from carrier shipment states. enforced_at: - database - service provenance: observed source: >- services-commerce:modules/shipping/db/shipments.table.ts:shipments_pickup_check - id: INV-DOM-COM-FUL-004-08 statement: >- Shipment-event grants permit insertion and prevent application mutation or removal. enforced_at: - database provenance: observed source: >- services-commerce:modules/shipping/db/shipment-events.table.ts (UPDATE, DELETE and TRUNCATE revoked) - id: INV-DOM-COM-FUL-004-09 statement: >- Receipt keys prevent duplicate receiving, receipts cannot be deleted, and disposition quantities are bounded by received quantities. enforced_at: - database - service provenance: observed source: >- services-commerce:modules/shipping/db/return-receipts.table.ts; return-receipt-lines.table.ts:return_receipt_lines_quantities_check - id: INV-DOM-COM-FUL-004-10 statement: >- Carrier-account configuration contains connection references rather than secrets and requires a connection for supported platform carriers. enforced_at: - service provenance: observed source: >- services-commerce:modules/shipping/services/persistence/carrier-accounts.ts - id: INV-DOM-COM-FUL-004-11 statement: >- Referenced carrier accounts and pickup warehouses cannot be deleted; removing a zone cascades to its strategies. enforced_at: - database provenance: observed source: >- services-commerce:modules/shipping/db/shipping-strategies.table.ts; modules/shipping/db/shipments.table.ts; modules/shipping/db/carrier-labels.table.ts - id: INV-DOM-COM-FUL-004-12 statement: >- Strategy validation orders weight bands, permits an unbounded final band and requires pickup to have a place and zero charge. enforced_at: - service - database provenance: observed source: >- services-commerce:modules/shipping/services/persistence/shipping-strategies.ts:validateStrategyInput physical: - shipments - shipment_lines - packages - package_lines - carrier_labels - shipment_events - pick_lists - pick_list_lines - return_receipts - return_receipt_lines - return_dispositions - shipping_zones - shipping_strategies - carrier_accounts evidence: - >- services-commerce at c8b66a98: modules/shipping/db/*.table.ts; services/persistence/*.ts; services/fulfillment/*.ts; services/returns/*.ts; services/rating/*.ts; services/carriers/*.ts; docs/migrations/shipping/README.md. --- # Shipment ## What It Models A shipment gathers an order’s physical units at one warehouse for a dispatch wave or customer collection. Its lines, parcels, pick lists and labels retain the warehouse’s progress. Return receiving records what comes back, and shipping configuration determines the options offered to buyers. ## Identity and Attributes Shipments, pick lists and return receipts use workspace numbering. A shipment line identifies a contiguous unit range. Parcels have sequences within a shipment, and each carrier-label attempt retains its own purchase key and outcome. Shipping configuration uses stable configuration identities. ## Relationships Allocation units identify the stock assigned to each shipment line. Handoff writes stock movements and completes matching delivery obligations. Return receipts link to an Orders-owned authorization and, where available, the outbound shipment line used to restore cost. ## Invariants The handoff transaction coordinates stock, cost-provider calls, order shipping quantities and matching obligation completion. Its authorization check refuses an invalid matching obligation but does not prove that every allocation has a matching obligation. Carrier purchase recovery retains uncertainty rather than starting another purchase blindly. ## How It Is Stored and Shared Shipping owns warehouse work and shipping configuration. It invokes Inventory and Fulfillment persistence inside its transactions and delegates costing through a provider. Orders controls cancellation and return documents, while carrier credentials remain with the Integration Platform. ## Open Design Questions Warehouse lifecycle enforcement, missing obligation coverage, concurrent pick lists and lost return-finance continuation remain implementation gaps. The shipment dialog also collects values that its request discards.