04.04 · Concept
The Entitlement State Machine
Model what a customer is entitled to as its own state, separate from the payment that granted it, with grace, expiry and revocation as distinct transitions.
No video curated for this lesson yet
This lesson is written, ordered and part of the path - the video slot is the only thing still open. We are working through Payments lesson by lesson; 26 of 35 have their video so far.
The written notes below cover this idea in full - you lose nothing by reading instead of watching.
Entitlement state is the product-owned record of what a customer may use now, independent of the billing event that caused it. Payments, refunds, disputes and admin actions become inputs to explicit transitions such as active, grace, expired and revoked, so feature access reads one durable product state.
What this lesson answers
- how should I model customer entitlements
- why not use payment status for access
- how do grace and revocation states work
Notes
An entitlement is the answer to a product question: what is this customer allowed to use right now? A payment, invoice, subscription, refund, chargeback, or admin action may influence that answer, but it is not the answer itself. Treating entitlement as its own state lets your application make access decisions without reinterpreting raw billing history every time a user clicks a feature.
The useful mental model is a small state machine owned by your product database. A customer might move from none to active when a paid subscription starts, from active to grace when renewal fails but you still…
Common questions
- Why should entitlement be separate from payment records?
- Payment records describe financial events, not current product access. A successful charge, failed renewal, refund, dispute or manual override may all affect access differently. Keeping entitlement as its own state gives the application a stable answer to read, instead of rebuilding access rules from billing history on every request.
- What states should an entitlement model include?
- A practical model usually separates no access, active access, temporary grace, expired access and revoked access. The exact names can vary, but the important part is that grace, expiry and revocation are not treated as the same condition. They mean different things operationally and should have distinct transition rules.
- Why is checking the latest payment or subscription status risky?
- Billing state is often transitional and incomplete from the product’s point of view. Webhooks can arrive late, renewals can retry, customers can cancel at period end, and staff can grant exceptions. If every feature gate interprets those cases directly, access logic becomes scattered, slow and difficult to test.
Short definition: what is Entitlement State Machine?