Promotion Lifecycle¶

Models the lifecycle of a Promotion from creation and configuration through scheduling, activation, and expiry. Covers paused/suspended states for mid-flight corrections and early termination.

Object: promotion · States: 6 · Transitions: 9

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 ───────────────────────────────────────────────
    draft(["Draft"])
    scheduled["Scheduled"]
    active["Active"]
    paused>"Paused"]
    expired[["Expired"]]
    cancelled[["Cancelled"]]

    %% ── transitions ─────────────────────────────────
    draft -->|"promotion-evaluated"| scheduled
    scheduled -->|"promotion-applied"| active
    active -->|"promotion-evaluated"| paused
    paused -->|"promotion-applied"| active
    active -->|"promotion-evaluated"| expired
    scheduled -->|"promotion-evaluated"| expired
    draft -->|"promotion-evaluated"| cancelled
    scheduled -->|"promotion-evaluated"| cancelled
    active -->|"promotion-evaluated"| cancelled

    %% ── class assignments ───────────────────────────
    class draft stInit
    class scheduled,active stNorm
    class paused stHold
    class expired,cancelled stFail

States¶

State	Label	Description	Initial	Terminal
`draft`	Draft	Promotion being configured. Not yet scheduled or visible to customers.	✓
`scheduled`	Scheduled	Promotion approved and queued for activation. Will activate at configured start date/time.
`active`	Active	Promotion live. Eligibility evaluated at basket calculation. Discount applied to qualifying baskets.
`paused`	Paused	Promotion temporarily suspended mid-flight (e.g. unexpected margin impact). No new applications.
`expired`	Expired	Promotion end date reached or budget exhausted. No further applications possible.		✓
`cancelled`	Cancelled	Promotion withdrawn before or during activation (error, legal issue, business decision).		✓

Transitions¶

From	To	Trigger	Guards
`draft`	`scheduled`	`promotion-evaluated`	Promotion reviewed and approved by merchandising team; Start date in the future
`scheduled`	`active`	`promotion-applied`	Start date/time reached; Promotion not cancelled
`active`	`paused`	`promotion-evaluated`	Manual intervention by merchandising team
`paused`	`active`	`promotion-applied`	Issue resolved; End date not yet reached
`active`	`expired`	`promotion-evaluated`	End date reached OR budget cap exhausted
`scheduled`	`expired`	`promotion-evaluated`	Start date passed without activation (system error or cancelled before activation)
`draft`	`cancelled`	`promotion-evaluated`	Promotion abandoned before scheduling
`scheduled`	`cancelled`	`promotion-evaluated`	Withdrawn before activation
`active`	`cancelled`	`promotion-evaluated`	Emergency withdrawal (compliance, legal, error)