Subscriptions and eligibility
A subscription assigns one Customer to one plan version. A Customer has at most one current subscription. Assigning a new one replaces it and keeps the old one in the history.
Status and timestamps
Section titled “Status and timestamps”The status records the lifecycle condition. Timestamps carry the facts: current_period_start, current_period_end, trial_ends_at, grace_ends_at and cancel_at. All are UTC, and every interval is half-open: the start is included, the end isn’t.
Seal0 never advances the status by itself. No background job turns active into expired. Eligibility is computed from the timestamps at the instant of each evaluation.
| Status | Required | Eligible when |
|---|---|---|
trialing |
trial_ends_at |
the period has started (or has no start) and it’s before trial_ends_at |
active |
current_period_start |
at or after current_period_start, and before current_period_end if set. No end means it never expires. |
past_due |
grace_ends_at |
before grace_ends_at |
canceled |
cancel_at |
before cancel_at, and still inside the period and trial windows if set. cancel_at can shorten access, never extend it. |
paused |
none | never |
expired |
none | never |
cancel_at is accepted only with canceled. A scheduled cancellation and an immediate one look the same: status: canceled with cancel_at in the future or now. An invalid combination is refused with 422 invalid_subscription_state.
When it isn’t eligible
Section titled “When it isn’t eligible”Nothing is granted: no plan values, no overrides, no defaults. The evaluation still returns 200, with granted: false, source: none, and one of these reasons:
| Reason | Because |
|---|---|
no_subscription |
the Customer has no current subscription |
subscription_not_started |
it’s before current_period_start |
subscription_paused |
the status is paused |
subscription_expired |
the status is expired |
subscription_canceled |
at or after cancel_at |
trial_ended |
at or after trial_ends_at |
grace_ended |
past_due, at or after grace_ends_at |
period_ended |
at or after current_period_end |
Without a payment integration
Section titled “Without a payment integration”Keep a subscription active with no current_period_end, or move current_period_end forward on each renewal. When a payment fails, set past_due with a grace_ends_at. Any status change is allowed as long as the result is a valid combination.