Skip to content

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.

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.

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

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.