Shipment Lifecycle¶

Models the lifecycle of a physical Shipment from carrier booking through delivery attempt and final outcome. A Fulfillment Order may have one or more Shipments (split shipments, re-dispatch after failed delivery). Tracks carrier milestones: label creation, collection, transit events, delivery attempt, and returns to sender.

Object: shipment · States: 10 · Transitions: 12

State Diagram¶

flowchart LR

    %% ── classDef palette ─────────────────────────────────────
    classDef stInit  fill:#0d9488,stroke:#0f766e,color:#fff,font-weight:bold
    classDef stNorm  fill:#3b82f6,stroke:#2563eb,color:#fff
    classDef stOk    fill:#16a34a,stroke:#15803d,color:#fff,font-weight:bold
    classDef stFail  fill:#dc2626,stroke:#b91c1c,color:#fff,font-weight:bold
    classDef stHold  fill:#d97706,stroke:#b45309,color:#fff

    %% ── nodes ───────────────────────────────────────────────
    pending(["Pending"])
    label_created["Label Created"]
    collected["Collected"]
    in_transit["In Transit"]
    out_for_delivery["Out for Delivery"]
    delivery_attempted["Delivery Attempted"]
    held_at_depot["Held at Depot"]
    delivered[["Delivered"]]
    returned_to_sender[["Returned to Sender"]]
    lost[["Lost"]]

    %% ── transitions ─────────────────────────────────
    pending -->|"shipment-packed"| label_created
    label_created -->|"shipment-dispatched"| collected
    collected -->|"shipment-dispatched"| in_transit
    in_transit -->|"shipment-dispatched"| out_for_delivery
    out_for_delivery -->|"shipment-delivered"| delivered
    out_for_delivery -->|"shipment-dispatched"| delivery_attempted
    delivery_attempted -->|"shipment-dispatched"| held_at_depot
    held_at_depot -->|"shipment-delivered"| delivered
    delivery_attempted -->|"shipment-dispatched"| out_for_delivery
    held_at_depot -->|"shipment-dispatched"| returned_to_sender
    delivery_attempted -->|"shipment-dispatched"| returned_to_sender
    in_transit -->|"shipment-dispatched"| lost

    %% ── class assignments ───────────────────────────
    class pending stInit
    class label_created,collected,in_transit,out_for_delivery,delivery_attempted,held_at_depot stNorm
    class delivered,returned_to_sender stOk
    class lost stFail

States¶

State	Label	Description	Initial	Terminal
`pending`	Pending	Shipment record created. Carrier not yet booked. Awaiting packing completion.	✓
`label-created`	Label Created	Carrier label generated. Tracking number assigned. Awaiting carrier collection.
`collected`	Collected	Carrier has physically collected the parcel from the dispatch location.
`in-transit`	In Transit	Parcel in carrier network. Tracking updates being received.
`out-for-delivery`	Out for Delivery	Parcel loaded on last-mile delivery vehicle. Delivery attempt imminent.
`delivery-attempted`	Delivery Attempted	Delivery attempt failed (no one home, access refused, address issue). Card left or safe location used.
`held-at-depot`	Held at Depot	Parcel held at carrier depot or collection point awaiting customer collection.
`delivered`	Delivered	Parcel confirmed delivered to recipient or safe location. Proof of delivery captured.		✓
`returned-to-sender`	Returned to Sender	Parcel returned to origin (uncollected, undeliverable, refused). Inventory re-processed.		✓
`lost`	Lost	Parcel declared lost by carrier. Claim process initiated. Customer refund/replacement triggered.		✓

Transitions¶

From	To	Trigger	Guards
`pending`	`label-created`	`shipment-packed`	Packing complete; Carrier service selected; Label printed
`label-created`	`collected`	`shipment-dispatched`	Carrier scan at collection point
`collected`	`in-transit`	`shipment-dispatched`	Parcel scanned into carrier network
`in-transit`	`out-for-delivery`	`shipment-dispatched`	Last-mile carrier scan on delivery vehicle
`out-for-delivery`	`delivered`	`shipment-delivered`	Successful delivery scan or customer signature
`out-for-delivery`	`delivery-attempted`	`shipment-dispatched`	Delivery attempt fails (no one home, access issue)
`delivery-attempted`	`held-at-depot`	`shipment-dispatched`	Parcel returned to depot; Customer notified to collect
`held-at-depot`	`delivered`	`shipment-delivered`	Customer collects from depot or collection point
`delivery-attempted`	`out-for-delivery`	`shipment-dispatched`	Re-delivery booked by customer
`held-at-depot`	`returned-to-sender`	`shipment-dispatched`	Collection window expired without customer collection
`delivery-attempted`	`returned-to-sender`	`shipment-dispatched`	Address undeliverable after all attempts exhausted
`in-transit`	`lost`	`shipment-dispatched`	Carrier declares parcel lost after investigation period