--- id: WF-COM-FUL-011 title: 'Buy, settle and void a carrier label' trigger: 'Staff request carrier purchase, resolution, void or tracking.' product_area: commerce module: fulfillment revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b implements: - CAP-COM-FUL-013 moves: - STATE-COM-FUL-006 - STATE-COM-FUL-005 crosses: - SVC-COM-FUL-shipping idempotency: >- Purchase uses the parcel attempt key and resolves a requested attempt before another purchase. Void uses a distinct attempt key, including after an unknown void outcome. concurrency: >- Intent and result transactions surround the external call. Requested-state result checks prevent two retained outcomes for one attempt; they do not turn carrier calls into database work. hops: - 'n': 1 actor_or_service: Shipping API (purchase) action: >- Validate carrier preparation, settle a retained purchase under its key and create a requested attempt only when safe to proceed. anchor: >- services-commerce:modules/shipping/services/fulfillment/labels.ts:purchaseLabelForPackage seam: sync on_failure: Refuse a purchase whose earlier outcome remains unknown. left_inconsistent: The earlier requested attempt remains; no new purchase is begun. observer: Request conflict and purchase-intent history. provenance: documented source: 'services-commerce:docs/migrations/shipping/README.md#D-P8S-08' - 'n': 2 actor_or_service: Carrier port action: >- Invoke the manual carrier with entered tracking and cost, or UPS through the account’s Integration Platform connection and stable key. anchor: 'services-commerce:modules/shipping/services/carriers/ups/ups-carrier.ts' seam: sync on_failure: >- Known pre-execution unavailability records failure and returns unavailable; unknown execution retains uncertainty. left_inconsistent: A carrier may have sold a label without a retained local result. observer: Label-attempt history and inventory findings. provenance: test source: >- services-commerce:modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js#buys the first label through UPS under package::1 (the intent then the outcome), the tracking number and the cost on the label, the package labelled - 'n': 3 actor_or_service: Shipping API (outcome) action: >- Retain purchase success, failure or uncertainty; success labels the parcel and can finish shipment labelling. anchor: >- services-commerce:modules/shipping/services/fulfillment/labels.ts:recordPurchaseOutcome seam: sync on_failure: A crash before result retention leaves the attempt requested. left_inconsistent: The parcel can remain packed despite a carrier purchase. observer: Shipment purchase history. provenance: observed source: 'services-commerce:modules/shipping/services/persistence/carrier-labels.ts' - 'n': 4 actor_or_service: Staff (settle) action: >- Settle a requested purchase from the carrier-console result supplied by staff. anchor: >- services-commerce:modules/shipping/services/fulfillment/labels.ts:resolveLabelPurchase seam: sync on_failure: Refuse when no requested purchase exists. left_inconsistent: The staff report does not itself create another carrier purchase. observer: Staff-resolution history. provenance: observed source: 'services-commerce:modules/shipping/services/fulfillment/labels.ts' - 'n': 5 actor_or_service: Shipping API (void) action: >- Retain a keyed void attempt, call the carrier and return the parcel to packed or remove it after success. anchor: >- services-commerce:modules/shipping/services/fulfillment/labels.ts:voidLabelOfPackage seam: sync on_failure: >- Unknown void returns unavailable with the local label still purchased; refused void retains cost and raises a finding. left_inconsistent: The carrier’s void state can differ from the retained local label. observer: Void findings and attempt history. provenance: observed source: 'services-commerce:modules/shipping/services/fulfillment/labels.ts' - 'n': 6 actor_or_service: Shipping API (track) action: >- Read carrier history or retain a manual delivery date and update parcel and shipment progress. anchor: >- services-commerce:modules/shipping/services/fulfillment/labels.ts:trackPackage seam: sync on_failure: Leave progress unchanged when the carrier request fails. left_inconsistent: Earlier shipping work remains committed. observer: Tracking history. provenance: observed source: 'services-commerce:modules/shipping/services/fulfillment/labels.ts' branches: - 'Pick-up shipments refuse label purchase, void, tracking and manifest.' - >- The return label shipment buys its label the existing way including the customer as ship-from. waits: - The carrier's answer; staff's settlement of an uncertain purchase. evidence: - >- services-commerce at c8b66a98: modules/shipping/services/fulfillment/labels.ts; services/carriers/*.ts; services/persistence/carrier-labels.ts; docs/migrations/shipping/README.md (D-P8S-07, D-P8S-08, D-P8S-15, D-P8S-16). controls: [TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, 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-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-003, TC-PI-005, TC-VEN-001, TC-VEN-002, TC-VEN-003, TC-PRV-001, TC-PRV-002] --- # Buy, Settle and Void a Carrier Label ## What It Does Label purchase records a carrier attempt, calls outside the database transaction and then stores the answer. Uncertainty is resolved by lookup, reuse of the same key or staff confirmation. Void and tracking remain explicit staff requests. ## The Flow ```mermaid sequenceDiagram participant S as Staff participant H as Shipping API participant L as Label record participant C as Carrier (manual or UPS via Integration Platform) S->>H: buy label H->>L: settle any requested purchase H->>L: record intent (key) H->>C: purchase under key C-->>H: purchased, failed or uncertain H->>L: record outcome S->>H: staff closure from carrier console S->>H: void (keyed attempt) ``` ## When Something Fails A purchase with unknown outcome stays requested while its parcel remains packed. A void can succeed at the carrier without a retained local success. Refused voids keep cost and create findings; no background process resolves these gaps.