Subscriptions and access entitlements

Subscriptions & Entitlements

Recurring billing requires clear rules for how commercial subscription states map to product access, how mid-cycle plan changes are prorated and when changes take effect.

1. Subscription Lifecycle & Entitlement Mapping

Map each subscription state to an explicit product entitlement policy:

• trialing: full trial tier entitlements until trial_end. Clarify whether a payment method is required upfront or only at conversion.
• active: full plan entitlements for [current_period_start, current_period_end).
• past_due (Grace Period): renewal payment failed, but dunning retries are in progress. Typically preserve core read/write access during a configured grace window (grace_period_ends_at) while surfacing an in-app payment-update banner, rather than locking the customer out on the first transient card decline.
• canceled with cancel_at_period_end = true: recurring renewal is stopped, but the customer already paid for the current period — preserve active entitlements until current_period_end, then transition to expired/free tier.
• unpaid / expired / immediate canceled: revoke paid feature entitlements while preserving user data read/export access according to product retention rules.

2. Upgrades, Downgrades & Proration Timing

When a subscriber changes plans (Basic -> Pro, Monthly -> Annual, or changing seat counts), define three parameters explicitly:

1. Effective timing:
   • Upgrades (Basic -> Pro, adding seats): usually take effect immediately, granting the higher entitlements right away.
   • Downgrades (Pro -> Basic, Annual -> Monthly, removing seats): usually scheduled for end of current billing period (SubscriptionSchedule / pending change) so the customer keeps what they already paid for and avoids mid-cycle refund complexity.
2. Financial calculation (Proration):
   • Calculate unused time credit on the old plan and prorated charge for the remaining time on the new plan.
   • Decide whether the prorated difference is invoiced and charged immediately (always_invoice / pending_if_incomplete so entitlements only upgrade if the charge succeeds) or added to the next renewal invoice.
3. Quota / Usage allowance reset:
   • When switching from Monthly to Annual or upgrading tiers mid-cycle, specify whether usage counters reset immediately, scale up by the tier difference, or carry over.

3. Grandfathering & Price Versioning

• Treat prices as immutable versions: when the business raises the price of the Pro plan from $29 to $39, create a new Price ID (price_pro_2026_v2) linked to the product rather than mutating the existing price in place.
• Explicit migration policy for existing subscribers: keep existing subscribers grandfathered on their contracted price version until an explicitly approved cohort migration (with required advance notice) moves them.

4. Seat-Based Billing & Downgrade Validation

• Define what counts as a billable seat (active members + pending invitations, or active members only) and enforce seat limits atomically when inviting or activating users.
• Before allowing a downgrade to a lower tier (e.g., from 25 seats to 5 seats, or 100 GB storage to 10 GB), validate current usage against the target tier's limits and guide the user to reduce seats/resources or define how over-limit resources become read-only.