Subscription Lifecycle

A subscription is not just "pay and done". Trial, activation, renewal, upgrade, downgrade, cancellation, payment failure, and expiry each have their own behavior. Pay4SaaS manages this lifecycle for you.

State Flow

                      ┌─────────┐
                      │ pending │  ← Checkout initiated
                      └────┬────┘
                           │
                ┌──────────┴──────────┐
                ▼                     ▼
          ┌──────────┐          ┌──────────┐
          │ trialing │──payment─▶│  active  │◀── Renewal success / Resume
          └────┬─────┘          └────┬─────┘
               │                     │
               │ Trial payment fails │ User cancels at period end
               ▼                     ▼
          ┌──────────┐          ┌───────────┐
          │ past_due │          │ canceling │
          └────┬─────┘          └─────┬─────┘
               │                      │ Period ends
      ┌────────┴────────┐             ▼
      ▼                 ▼       ┌──────────┐
  ┌────────┐       ┌────────┐   │ canceled │
  │ active │       │ unpaid │   └──────────┘
  └────────┘       └───┬────┘
                       │
               ┌───────┴───────┐
               ▼               ▼
          ┌────────┐      ┌──────────┐
          │ active │      │ canceled │
          └────────┘      └──────────┘

Status Descriptions

Status	Description	Can User Access Service
`pending`	Checkout initiated, awaiting payment	No
`trialing`	In trial period	Yes, while valid
`active`	Paid and active	Yes
`canceling`	User has canceled, but current period has not ended	Yes, until period ends
`canceled`	Canceled and period has ended	No
`expired`	Expired, because payment failed or the term ended	No
`past_due`	Payment failed or overdue, inside a short grace window	Yes, while inside grace
`unpaid`	Provider has confirmed long-running non-payment or suspension	No

For payment failures and short provider delays, Pay4SaaS uses a short grace window before fully removing access. This avoids immediately locking out a valid customer because a webhook was delayed or a provider retry is still in progress.

The grace window is a temporary tolerance period, not a failed-payment renewal mechanism. If payment does not recover, access is removed after the window ends.

Trial Period

After configuring a trial period, users can try the service for free on their first subscription.

Key rules:

Each user can only trial once
Users who have already trialed will automatically use the no-trial product ID at checkout
During trial, users can access the service normally in Unlimited Subscription mode
In Quota Subscription mode, there is no trial concept, but you can grant bonus credits for users to try
After the trial ends, payment is charged automatically. If payment succeeds, the subscription becomes active; if payment fails, it enters a failed-payment status such as past_due

Upgrades & Downgrades

The system determines upgrade vs downgrade by comparing actual prices. If the new price is higher than the current price, it is treated as an upgrade. Otherwise, it is treated as a downgrade.

Upgrade, Immediate Effect

New plan takes effect immediately
Payment provider automatically calculates the prorated difference
In Quota Subscription mode, quota resets to the new plan

Downgrade, Next Cycle

Current cycle remains unchanged, retaining the original plan's benefits
The downgrade is scheduled for the next billing cycle
When the next renewal succeeds, the downgrade is automatically applied
In Quota Subscription mode, the current cycle keeps the original quota

If you want to show pending downgrade information in your UI, read it from the subscription status returned by the billing or access APIs instead of duplicating downgrade logic on the frontend.

Cancellation & Resume

Cancellation

There are two types of cancellation:

Cancel at period end, default: Status becomes canceling, user can still use the service until the period ends, then becomes canceled
Cancel immediately: Status becomes canceled right away, access is revoked instantly

Resume

Users in canceling status can undo the cancellation before the current period ends:

Status reverts to active
Cancellation information is cleared
Normal billing continues

Renewal

Renewal is automatic. The payment provider charges before each billing cycle ends and notifies the system via Webhook.

When renewal succeeds:

Renewal success Webhook is received
System extends the user's current billing period
If there is a pending downgrade plan, it is applied at this point
In Quota Subscription mode, monthly quota is reset

If renewal fails:

Payment failure Webhook is received
System marks the subscription as overdue
The user can still access the service during a short grace window
If payment recovers, the subscription returns to active
If payment does not recover, access is removed after the grace window ends

Duplicate Subscription Handling

If a user initiates a new subscription while already having one:

Same plan: Extends the expiry date by stacking the new period onto the existing subscription
Different plan: Cancels the old subscription and activates the new one

Out-of-Order Protection

Payment provider Webhooks may arrive out of order, such as a cancellation event arriving before an activation event. Pay4SaaS protects the local subscription state by validating each transition, only moving billing periods forward, and ignoring stale events that should no longer change access.