--- id: SVC-COM-FUL-shipping title: Shipping Service Module product_area: commerce module: fulfillment repository: services-commerce source_module: modules/shipping revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-COM-FUL-004 does_not_own: - >- Orders owns return authorization and money timing and requests return-label work. - >- Checkout owns shipping option selection at preview and placement, then retains its choice on the order. - Inventory owns the ledgers invoked by handoff and return disposition. - >- The separately registered costing service owns cost layers and relief history. - 'Platform owns carrier connections, secrets and the UPS adapter.' - CRM owns the fallback customer and organization address records. operations: - operation_id: getShippingHealth intent: >- Return API reachability and deployment identity without reading business records. access: public permission: none realises: [] published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: createShippingZone intent: >- Create shipping zone using the supplied configuration or eligible order work. access: console permission: commerce.shipping-zones.create realises: - CAP-COM-FUL-010 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: listShippingZones intent: >- Return the permitted shipping zones records with the route’s supported filters. access: console permission: commerce.shipping-zones.read realises: - CAP-COM-FUL-010 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: getShippingZone intent: Read the requested shipping zone record within the current workspace. access: console permission: commerce.shipping-zones.read realises: - CAP-COM-FUL-010 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: updateShippingZone intent: >- Replace shipping zone using its current version and allowed writable properties. access: console permission: commerce.shipping-zones.update realises: - CAP-COM-FUL-010 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: deleteShippingZone intent: Delete an unlocked shipping zone and its dependent strategies. access: console permission: commerce.shipping-zones.delete realises: - CAP-COM-FUL-010 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: createShippingStrategy intent: >- Create shipping strategy using the supplied configuration or eligible order work. access: console permission: commerce.shipping-strategies.create realises: - CAP-COM-FUL-010 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: listShippingStrategies intent: >- Return the permitted shipping strategies records with the route’s supported filters. access: console permission: commerce.shipping-strategies.read realises: - CAP-COM-FUL-010 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: getShippingStrategy intent: Read the requested shipping strategy record within the current workspace. access: console permission: commerce.shipping-strategies.read realises: - CAP-COM-FUL-010 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: updateShippingStrategy intent: >- Replace shipping strategy using its current version and allowed writable properties. access: console permission: commerce.shipping-strategies.update realises: - CAP-COM-FUL-010 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: deleteShippingStrategy intent: >- Remove shipping strategy only when locking and reference constraints permit. access: console permission: commerce.shipping-strategies.delete realises: - CAP-COM-FUL-010 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: createCarrierAccount intent: >- Create carrier account using the supplied configuration or eligible order work. access: console permission: commerce.carrier-accounts.create realises: - CAP-COM-FUL-010 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: listCarrierAccounts intent: >- Return the permitted carrier accounts records with the route’s supported filters. access: console permission: commerce.carrier-accounts.read realises: - CAP-COM-FUL-010 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: getCarrierAccount intent: Read the requested carrier account record within the current workspace. access: console permission: commerce.carrier-accounts.read realises: - CAP-COM-FUL-010 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: updateCarrierAccount intent: >- Replace carrier account using its current version and allowed writable properties. access: console permission: commerce.carrier-accounts.update realises: - CAP-COM-FUL-010 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: deleteCarrierAccount intent: Remove carrier account only when locking and reference constraints permit. access: console permission: commerce.carrier-accounts.delete realises: - CAP-COM-FUL-010 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: createShipment intent: Create shipment using the supplied configuration or eligible order work. access: console permission: commerce.shipments.create realises: - CAP-COM-FUL-012 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: listShipments intent: Return the permitted shipments records with the route’s supported filters. access: console permission: commerce.shipments.read realises: - CAP-COM-FUL-012 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: getShipment intent: Read the requested shipment record within the current workspace. access: console permission: commerce.shipments.read realises: - CAP-COM-FUL-012 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: listShipmentEvents intent: >- Return the permitted shipment events records with the route’s supported filters. access: console permission: commerce.shipments.read realises: - CAP-COM-FUL-012 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: listShipmentPackages intent: >- Return the permitted shipment packages records with the route’s supported filters. access: console permission: commerce.shipments.read realises: - CAP-COM-FUL-012 - CAP-COM-FUL-013 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: releaseShipment intent: Release shipment through the permitted state transition. access: console permission: commerce.shipments.update realises: - CAP-COM-FUL-012 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: packShipment intent: Assign eligible picked quantities to parcels and update packing progress. access: console permission: commerce.shipments.update realises: - CAP-COM-FUL-012 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: purchasePackageLabel intent: >- Retain a carrier purchase intent and resolve its outcome under the attempt key. access: console permission: commerce.shipments.update realises: - CAP-COM-FUL-013 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: resolvePackageLabel intent: >- Settle a requested label purchase from the result staff see in the carrier console. access: console permission: commerce.shipments.update realises: - CAP-COM-FUL-013 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: voidPackageLabel intent: >- Record a separate void attempt and update the label from the carrier’s result. access: console permission: commerce.shipments.update realises: - CAP-COM-FUL-013 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: trackPackage intent: Read carrier history or record a manual delivery date. access: console permission: commerce.shipments.update realises: - CAP-COM-FUL-013 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: manifestShipment intent: Close carrier preparation for a labelled shipment. access: console permission: commerce.shipments.update realises: - CAP-COM-FUL-012 - CAP-COM-FUL-013 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: handoffShipment intent: 'Commit carrier departure and its stock, order and delivery effects.' access: console permission: commerce.shipments.handoff realises: - CAP-COM-FUL-014 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: handoverShipment intent: >- Commit pickup collection with the named collector and its departure effects. access: console permission: commerce.shipments.handover realises: - CAP-COM-FUL-014 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: cancelShipment intent: Cancel shipment while retaining its completed or shipped work. access: console permission: commerce.shipments.cancel realises: - CAP-COM-FUL-012 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: createPickList intent: Create pick list using the supplied configuration or eligible order work. access: console permission: commerce.pick-lists.create realises: - CAP-COM-FUL-012 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: listPickLists intent: >- Return the permitted pick lists records with the route’s supported filters. access: console permission: commerce.pick-lists.read realises: - CAP-COM-FUL-012 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: getPickList intent: Read the requested pick list record within the current workspace. access: console permission: commerce.pick-lists.read realises: - CAP-COM-FUL-012 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: claimPickList intent: Assign the open pick list to its picker. access: console permission: commerce.pick-lists.update realises: - CAP-COM-FUL-012 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: pickPickListLine intent: Record a full or short result for the specified pick-list line. access: console permission: commerce.pick-lists.update realises: - CAP-COM-FUL-012 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: completePickList intent: Record completion of pick list under its state and request checks. access: console permission: commerce.pick-lists.update realises: - CAP-COM-FUL-012 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: cancelPickList intent: Cancel pick list while retaining its completed or shipped work. access: console permission: commerce.pick-lists.update realises: - CAP-COM-FUL-012 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: receiveReturn intent: >- Record keyed receiving against remaining return authorization without moving stock. access: console permission: commerce.return-receipts.create realises: - CAP-COM-FUL-015 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: listReturnReceipts intent: >- Return the permitted return receipts records with the route’s supported filters. access: console permission: commerce.return-receipts.read realises: - CAP-COM-FUL-015 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: getReturnReceipt intent: Read the requested return receipt record within the current workspace. access: console permission: commerce.return-receipts.read realises: - CAP-COM-FUL-015 published_to_submissions: >- not published: no Submissions intake contract is declared for this read operation. - operation_id: inspectReturnReceipt intent: Retain condition and discrepancy for the received return lines. access: console permission: commerce.return-receipts.update realises: - CAP-COM-FUL-015 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. - operation_id: dispositionReturnReceipt intent: >- Apply permitted return dispositions and their stock effects before money continuation. access: console permission: commerce.return-receipts.update realises: - CAP-COM-FUL-015 - CAP-COM-FUL-017 published_to_submissions: >- not published: no Submissions contract is declared for this staff or application operation. events: - name: shipment history events direction: produced when: >- Warehouse progression, carrier attempts and updates, cancellation and departure refusal. payload_summary: >- Internal shipment history retains actor, correlation and the affected warehouse records. - name: cost relief and restore facts direction: produced when: >- Handoff invokes cost relief, or restock disposition invokes original-cost restoration. payload_summary: >- The provider receives shipment-line, item, quantity and movement references within the owning transaction. jobs: [] integrations: - system: Integration Platform (UPS) direction: outbound contract: >- Carrier rating, purchase, lookup, void and tracking use the account’s Integration Platform connection and each request’s stable key. Platform transport is the default; tests can install the fixture. - system: Shipping rating port direction: inbound contract: >- Checkout preview and placement ask the zone-and-strategy provider for applicable options, amounts and warnings. - system: Returns handling port direction: inbound contract: >- Orders’ return workflow creates and cancels return-label shipments through the returns port. - system: Cancellation fence port direction: inbound contract: >- Orders fences shipment lines inside cancellation’s transaction and continues shipment cancellation afterward. - system: Cost provider direction: outbound contract: >- Cost relief uses purchasing layers by default. Tests can select the fixture that defers relief. - system: Workspace data export direction: outbound contract: >- Workspace export includes shipping data while excluding carrier connection references. consistency: - rule: >- Handoff retains stock, matching obligation, order and selected cost-provider work in one transaction. kind: transactional compensation: >- A failed transaction rolls back, then refusal diagnosis is retained separately. - rule: >- Conditional line writes determine whether handoff or cancellation fencing succeeds. kind: transactional compensation: Departed goods use a return rather than cancellation release. - rule: >- Carrier purchase retains intent and result in separate transactions around the call. kind: eventual compensation: >- Lookup, existing-key reuse or staff confirmation settles unknown purchase outcomes. - rule: >- Disposition retains its movements and applicable cost effects with receiving and return quantities. kind: transactional compensation: >- Financial continuation follows commit without automatic retry on the recorded failure paths. evidence: - >- services-commerce at c8b66a98: modules/shipping/aws/api/shipping.routes.ts; aws/shipping.module.ts; services/**; aws/commerce.service.ts (shipping-zones, shipping-strategies, carrier-accounts, shipments, pick-lists, return-receipts); docs/migrations/shipping/README.md. - 'services-commerce:modules/shipping/aws/api/shipping.routes.ts' - >- services-commerce:package-lock.json:@rhythmsoftware/macroservice-http; node_modules/@rhythmsoftware/macroservice-http/dist/health-route.js:healthRoute controls: [TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, 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-CRY-001, TC-CRY-002, TC-CRY-003, 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-AVL-002, TC-AVL-003, TC-MON-001, TC-MON-003, TC-MON-004, TC-PI-001, TC-PI-003, TC-PI-005, TC-VEN-001, TC-VEN-002, TC-VEN-003, TC-PRV-001, TC-PRV-002] --- # Shipping Service Module ## What This Service Is For Carry an order’s physical units through warehouse preparation, departure and return receiving. ## Boundary Shipping owns shipment work and shipping configuration. Inventory owns stock, Fulfillment owns delivery coordination, Orders owns post-sale documents, and carrier secrets stay with the Integration Platform. ## Operations in Words Administrators configure coverage, strategies and carrier accounts. Warehouse routes create, release, pick, pack, label, manifest, hand over and cancel shipment work, then receive and disposition returns. ## Events and Jobs Carrier calls perform rating, purchase, lookup, void and tracking on explicit requests. Shipping retains internal history and calls cost providers; it has no background tracking or label recovery schedule. ## Consistency Guarantees Departure coordinates its participating writes in one transaction. Carrier purchase has separate intent and result commits. Return money work follows warehouse commits and has no automatic continuation after the recorded failure paths.