Subscriptions Management
Abstract
This skill covers subscription lifecycle management including cancellation, plan changes, reactivation, trial handling, and status display. Proper subscription management ensures users can upgrade, downgrade, cancel, and reactivate subscriptions with correct billing behavior.
Table of Contents
- Reload After Mutations — CRITICAL
- 1.1 Client-Side State Sync - 1.2 Server-Side Reload Pattern
- Cancel Timing Options — HIGH
- 2.1 End of Period vs Immediate - 2.2 User Communication
- 3.1 Immediate Upgrades - 3.2 Deferred Downgrades
- 4.1 Reactivating Canceled Subscriptions
- Trial Status Detection — MEDIUM
- 5.1 Checking Trial Status - 5.2 Trial Expiration Handling
- Subscription Status Display — MEDIUM
- 6.1 Status Mapping - 6.2 Pending Cancellation Display
1. Reload After Mutations
Impact: CRITICAL
After any subscription mutation (cancel, upgrade, downgrade, reactivate), the local billing state is stale. Failing to reload causes UI to show outdated subscription information.
1.1 Client-Side State Sync
Impact: CRITICAL (users see incorrect subscription status)
When using useBilling() on the client, mutations update the server but the local state remains stale until explicitly reloaded.
Incorrect: assumes state updates automatically
function CancelButton() {
const { cancelSubscription, currentSubscription } = useBilling()
const handleCancel = async () => {
await cancelSubscription({
id: currentSubscription.id,
cancellation: { timing: 'at_end_of_current_billing_period' },
})
// BUG: currentSubscription still shows old status!
// UI will not reflect cancellation until page refresh
}
return (
<div>
<button onClick={handleCancel}>Cancel Subscription</button>
{/* Shows incorrect status because we didn't reload */}
<p>Status: {currentSubscription?.status}</p>
</div>
)
}The UI continues showing the old subscription status because the local useBilling() state wasn't refreshed.
Correct: reload after mutation
function CancelButton() {
const { cancelSubscription, currentSubscription, reload } = useBilling()
const [isLoading, setIsLoading] = useState(false)
const handleCancel = async () => {
setIsLoading(true)
try {
await cancelSubscription({
id: currentSubscription.id,
cancellation: { timing: 'at_end_of_current_billing_period' },
})
// Refresh local state to reflect the cancellation
await reload()
} finally {
setIsLoading(false)
}
}
return (
<div>
<button onClick={handleCancel} disabled={isLoading}>
{isLoading ? 'Canceling...' : 'Cancel Subscription'}
</button>
{/* Now shows correct status after reload */}
<p>Status: {currentSubscription?.status}</p>
</div>
)
}1.2 Server-Side Reload Pattern
Impact: CRITICAL (server actions may return stale data)
When performing mutations server-side and returning billing data to the client, you must fetch fresh data after the mutation.
Incorrect: returns stale billing data
// Server action
export async function upgradeSubscription(priceSlug: string) {
const session = await auth()
const billing = await flowglad(session.user.id).getBilling()
await billing.adjustSubscription({ priceSlug })
// BUG: billing object still has old data!
return {
success: true,
subscription: billing.currentSubscription, // Stale!
}
}Correct: fetch fresh billing after mutation
// Server action
export async function upgradeSubscription(priceSlug: string) {
const session = await auth()
const billing = await flowglad(session.user.id).getBilling()
await billing.adjustSubscription({ priceSlug })
// Fetch fresh billing state after mutation
const freshBilling = await flowglad(session.user.id).getBilling()
return {
success: true,
subscription: freshBilling.currentSubscription, // Fresh!
}
}2. Cancel Timing Options
Impact: HIGH
Flowglad supports two cancellation timing modes. Using the wrong mode leads to billing disputes and poor user experience.
2.1 End of Period vs Immediate
Impact: HIGH (billing and access implications)
Most SaaS applications should cancel at the end of the billing period to let users keep access for time they've paid for.
Incorrect: immediately cancels without understanding impact
async function handleCancel() {
await billing.cancelSubscription({
id: billing.currentSubscription.id,
// This immediately ends access!
// User loses features they already paid for
cancellation: { timing: 'immediately' },
})
}Immediate cancellation removes access right away, even if the user paid for the full month. This often leads to support tickets and refund requests.
Correct: cancel at end of period (default for most cases)
async function handleCancel() {
await billing.cancelSubscription({
id: billing.currentSubscription.id,
// User keeps access until their paid period ends
cancellation: { timing: 'at_end_of_current_billing_period' },
})
await billing.reload()
}Use immediately only for specific cases like fraud prevention, user request for immediate refund, or account deletion.
2.2 User Communication
Impact: HIGH (user confusion)
When showing cancellation options, clearly communicate what each timing option means.
Incorrect: vague cancellation UI
function CancelModal() {
return (
<div>
<h2>Cancel Subscription</h2>
<button onClick={() => handleCancel('immediately')}>
Cancel Now
</button>
<button onClick={() => handleCancel('at_end_of_current_billing_period')}>
Cancel Later
</button>
</div>
)
}"Cancel Now" and "Cancel Later" don't explain the billing implications.
Correct: clear communication of timing
function CancelModal() {
const { currentSubscription } = useBilling()
const endDate = currentSubscription?.currentPeriodEnd
return (
<div>
<h2>Cancel Subscription</h2>
<div>
<button onClick={() => handleCancel('at_end_of_current_billing_period')}>
Cancel at End of Billing Period
</button>
<p>
You'll keep access until {formatDate(endDate)}.
No further charges will occur.
</p>
</div>
<div>
<button onClick={() => handleCancel('immediately')}>
Cancel Immediately
</button>
<p>
Access ends now. You may be eligible for a prorated refund.
</p>
</div>
</div>
)
}3. Upgrade vs Downgrade Behavior
Impact: HIGH
Upgrades and downgrades have different default behaviors. Not understanding this leads to incorrect UI and user confusion.
3.1 Immediate Upgrades
Impact: HIGH (billing timing)
By default, upgrades apply immediately with prorated billing. Users get instant access to the new plan.
Incorrect: suggests upgrade happens later
function UpgradeButton({ targetPriceSlug }: { targetPriceSlug: string }) {
const { adjustSubscription, reload } = useBilling()
return (
<button onClick={async () => {
await adjustSubscription({ priceSlug: targetPriceSlug })
await reload()
}}>
{/* Misleading: upgrade happens immediately, not next month */}
Upgrade Starting Next Month
</button>
)
}Correct: communicate immediate effect
function UpgradeButton({ targetPriceSlug }: { targetPriceSlug: string }) {
const { adjustSubscription, reload, getPrice } = useBilling()
const price = getPrice(targetPriceSlug)
return (
<div>
<button onClick={async () => {
await adjustSubscription({ priceSlug: targetPriceSlug })
await reload()
}}>
Upgrade Now to {price?.product.name}
</button>
<p>
Your new plan starts immediately.
You'll be charged a prorated amount for the remainder of this billing period.
</p>
</div>
)
}3.2 Deferred Downgrades
Impact: HIGH (user expectation mismatch)
Downgrades typically apply at the end of the current billing period. Users keep their current plan until then.
Incorrect: implies immediate downgrade
function DowngradeButton({ targetPriceSlug }: { targetPriceSlug: string }) {
const { adjustSubscription, reload } = useBilling()
return (
<button onClick={async () => {
await adjustSubscription({ priceSlug: targetPriceSlug })
await reload()
}}>
{/* Misleading: downgrade doesn't happen immediately */}
Switch to Basic Now
</button>
)
}Correct: communicate deferred effect
function DowngradeButton({ targetPriceSlug }: { targetPriceSlug: string }) {
const { adjustSubscription, currentSubscription, reload, getPrice } = useBilling()
const price = getPrice(targetPriceSlug)
const endDate = currentSubscription?.currentPeriodEnd
return (
<div>
<button onClick={async () => {
await adjustSubscription({ priceSlug: targetPriceSlug })
await reload()
}}>
Downgrade to {price?.product.name}
</button>
<p>
You'll keep your current plan until {formatDate(endDate)}.
Your new plan starts on your next billing date.
</p>
</div>
)
}4. Reactivation with uncancelSubscription
Impact: MEDIUM
Users who cancel can reactivate their subscription before the cancellation takes effect. This must be handled with the correct API.
4.1 Reactivating Canceled Subscriptions
Impact: MEDIUM (reactivation flow)
A subscription canceled with at_end_of_current_billing_period can be reactivated until the period ends.
Incorrect: tries to reactivate by creating new checkout
function ReactivateButton() {
const { currentSubscription, createCheckoutSession } = useBilling()
// Subscription is set to cancel at period end
const isPendingCancel = currentSubscription?.cancelAtPeriodEnd
if (!isPendingCancel) return null
return (
<button onClick={async () => {
// WRONG: Creates a new subscription instead of reactivating
// User may end up with overlapping subscriptions
await createCheckoutSession({
priceSlug: 'pro-monthly',
successUrl: window.location.href,
cancelUrl: window.location.href,
})
}}>
Reactivate Subscription
</button>
)
}Correct: use uncancelSubscription
function ReactivateButton() {
const { currentSubscription, uncancelSubscription, reload } = useBilling()
const [isLoading, setIsLoading] = useState(false)
// Subscription is set to cancel at period end
const isPendingCancel = currentSubscription?.cancelAtPeriodEnd
if (!isPendingCancel) return null
const handleReactivate = async () => {
setIsLoading(true)
try {
await uncancelSubscription({
id: currentSubscription.id,
})
await reload()
} finally {
setIsLoading(false)
}
}
return (
<div>
<p>Your subscription is set to cancel on {formatDate(currentSubscription.currentPeriodEnd)}</p>
<button onClick={handleReactivate} disabled={isLoading}>
{isLoading ? 'Reactivating...' : 'Keep My Subscription'}
</button>
</div>
)
}Note: Reactivation only works for subscriptions canceled with at_end_of_current_billing_period. Immediately canceled subscriptions cannot be reactivated this way.
5. Trial Status Detection
Impact: MEDIUM
Users on trial subscriptions have different needs than paying subscribers. Proper trial detection enables targeted UI and messaging.
5.1 Checking Trial Status
Impact: MEDIUM (trial-specific UI)
Incorrect: ignores trial status
function SubscriptionBanner() {
const { currentSubscription } = useBilling()
if (!currentSubscription) {
return <p>No active subscription</p>
}
// Doesn't distinguish between trial and paid
return <p>You're on the {currentSubscription.product.name} plan</p>
}Correct: check trial status
function SubscriptionBanner() {
const { currentSubscription, loaded } = useBilling()
if (!loaded) return <LoadingSkeleton />
if (!currentSubscription) {
return <p>No active subscription</p>
}
const isOnTrial = currentSubscription.status === 'trialing'
const trialEnd = currentSubscription.trialEnd
if (isOnTrial && trialEnd) {
const daysLeft = Math.ceil(
(new Date(trialEnd).getTime() - Date.now()) / (1000 * 60 * 60 * 24)
)
return (
<div>
<p>You're on a free trial of {currentSubscription.product.name}</p>
<p>{daysLeft} days remaining</p>
<button>Add Payment Method</button>
</div>
)
}
return <p>You're on the {currentSubscription.product.name} plan</p>
}5.2 Trial Expiration Handling
Impact: MEDIUM (conversion flow)
Incorrect: no trial expiration warning
function Dashboard() {
// User's trial expires silently, they lose access unexpectedly
return <MainContent />
}Correct: warn before trial expires
function Dashboard() {
const { currentSubscription } = useBilling()
const isOnTrial = currentSubscription?.status === 'trialing'
const trialEnd = currentSubscription?.trialEnd
const showTrialWarning = isOnTrial && trialEnd && (() => {
const daysLeft = Math.ceil(
(new Date(trialEnd).getTime() - Date.now()) / (1000 * 60 * 60 * 24)
)
return daysLeft <= 3
})()
return (
<div>
{showTrialWarning && (
<TrialExpirationBanner
trialEnd={trialEnd}
onUpgrade={() => {/* navigate to upgrade */}}
/>
)}
<MainContent />
</div>
)
}6. Subscription Status Display
Impact: MEDIUM
Subscriptions have multiple statuses. Displaying them clearly helps users understand their billing state.
6.1 Status Mapping
Impact: MEDIUM (user understanding)
Incorrect: shows raw status values
function SubscriptionStatus() {
const { currentSubscription } = useBilling()
// Raw status values confuse users
return <span>Status: {currentSubscription?.status}</span>
// Shows: "past_due" - not user-friendly
}Correct: map to user-friendly labels
const STATUS_LABELS: Record<string, { label: string; color: string }> = {
active: { label: 'Active', color: 'green' },
trialing: { label: 'Trial', color: 'blue' },
past_due: { label: 'Payment Failed', color: 'red' },
canceled: { label: 'Canceled', color: 'gray' },
incomplete: { label: 'Setup Required', color: 'yellow' },
incomplete_expired: { label: 'Expired', color: 'gray' },
paused: { label: 'Paused', color: 'yellow' },
unpaid: { label: 'Unpaid', color: 'red' },
}
function SubscriptionStatus() {
const { currentSubscription, loaded } = useBilling()
if (!loaded) return <LoadingSkeleton />
if (!currentSubscription) return null
const status = STATUS_LABELS[currentSubscription.status] ?? {
label: currentSubscription.status,
color: 'gray',
}
return (
<span style={{ color: status.color }}>
Status: {status.label}
</span>
)
}6.2 Pending Cancellation Display
Impact: MEDIUM (cancellation clarity)
When a subscription is set to cancel at period end, the status is still "active" but users need to know cancellation is pending.
Incorrect: doesn't show pending cancellation
function SubscriptionCard() {
const { currentSubscription } = useBilling()
return (
<div>
<h3>{currentSubscription?.product.name}</h3>
{/* Status shows "Active" even though cancellation is pending */}
<p>Status: {currentSubscription?.status}</p>
</div>
)
}Correct: show pending cancellation state
function SubscriptionCard() {
const { currentSubscription, uncancelSubscription, reload, loaded } = useBilling()
if (!loaded) return <LoadingSkeleton />
if (!currentSubscription) return null
const isPendingCancel = currentSubscription.cancelAtPeriodEnd
return (
<div>
<h3>{currentSubscription.product.name}</h3>
{isPendingCancel ? (
<div>
<p style={{ color: 'orange' }}>
Cancels on {formatDate(currentSubscription.currentPeriodEnd)}
</p>
<button onClick={async () => {
await uncancelSubscription({ id: currentSubscription.id })
await reload()
}}>
Keep Subscription
</button>
</div>
) : (
<p style={{ color: 'green' }}>
Active - Renews on {formatDate(currentSubscription.currentPeriodEnd)}
</p>
)}
</div>
)
}Quick Reference
Common Subscription Methods
// Cancel subscription
await billing.cancelSubscription({
id: billing.currentSubscription.id,
cancellation: { timing: 'at_end_of_current_billing_period' }, // or 'immediately'
})
// Change plan
await billing.adjustSubscription({
priceSlug: 'enterprise-monthly',
})
// Reactivate canceled subscription
await billing.uncancelSubscription({
id: subscription.id,
})
// Always reload after mutations
await billing.reload()Key Subscription Properties
const {
currentSubscription, // Active subscription object
loaded, // Whether billing data has loaded
reload, // Function to refresh billing state
} = useBilling()
// Subscription object properties
currentSubscription.status // 'active', 'trialing', 'past_due', etc.
currentSubscription.cancelAtPeriodEnd // true if cancellation is pending
currentSubscription.currentPeriodEnd // When current period ends
currentSubscription.trialEnd // When trial ends (if trialing)
currentSubscription.product // Associated product