Gift Card Lifecycle¶

Models the lifecycle of a Gift Card stored-value instrument from activation through partial and full redemption, expiry, and cancellation. Closely related to the Voucher lifecycle but distinct in that a gift card is typically a physical or digital payment instrument with a PIN and balance, not a promotional code.

Object: gift-card · States: 7 · Transitions: 10

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 ───────────────────────────────────────────────
    inactive(["Inactive"])
    active["Active"]
    partially_spent["Partially Spent"]
    spent[["Spent"]]
    expired[["Expired"]]
    cancelled[["Cancelled"]]
    refunded[["Refunded"]]

    %% ── transitions ─────────────────────────────────
    inactive -->|"gift-card-activated"| active
    active -->|"gift-card-redeemed"| partially_spent
    partially_spent -->|"gift-card-redeemed"| partially_spent
    active -->|"gift-card-redeemed"| spent
    partially_spent -->|"gift-card-redeemed"| spent
    partially_spent -->|"gift-card-topped-up"| active
    active -->|"gift-card-expired"| expired
    partially_spent -->|"gift-card-expired"| expired
    active -->|"gift-card-cancelled"| cancelled
    active -->|"gift-card-refunded"| refunded

    %% ── class assignments ───────────────────────────
    class inactive stInit
    class active,partially_spent stNorm
    class spent,refunded stOk
    class expired,cancelled stFail

States¶

State	Label	Description	Initial	Terminal
`inactive`	Inactive	Gift card created (sold or issued as reward) but not yet activated. Cannot be used for payment.	✓
`active`	Active	Gift card activated and available for use. Full or partial balance remaining.
`partially-spent`	Partially Spent	A portion of the gift card balance has been used. Remaining balance available.
`spent`	Spent	Gift card balance fully exhausted. No value remaining.		✓
`expired`	Expired	Gift card reached its expiry date with remaining balance. Policy-dependent handling.		✓
`cancelled`	Cancelled	Gift card manually voided (reported lost/stolen, fraud, or issuer action).		✓
`refunded`	Refunded	Original purchase value refunded; gift card deactivated.		✓

Transitions¶

From	To	Trigger	Guards
`inactive`	`active`	`gift-card-activated`	Activation event received (POS scan, online registration, or auto-activation); Card not previously reported lost/stolen
`active`	`partially-spent`	`gift-card-redeemed`	Redemption amount less than available balance; Card valid and not expired
`partially-spent`	`partially-spent`	`gift-card-redeemed`	Redemption amount less than remaining balance
`active`	`spent`	`gift-card-redeemed`	Redemption amount equals full balance
`partially-spent`	`spent`	`gift-card-redeemed`	Remaining balance fully consumed
`partially-spent`	`active`	`gift-card-topped-up`	Top-up feature enabled for this card type; Top-up amount added successfully
`active`	`expired`	`gift-card-expired`	Expiry date passed
`partially-spent`	`expired`	`gift-card-expired`	Expiry date passed with remaining balance
`active`	`cancelled`	`gift-card-cancelled`	Authorised cancellation (lost/stolen report, fraud detection, or retailer action)
`active`	`refunded`	`gift-card-refunded`	Original purchaser refund request; Within refund policy window