home / skills / flowglad / skills / subscriptions
This skill helps you manage subscription lifecycles, enabling upgrades, downgrades, cancellations, and reactivations with correct billing behavior.
npx playbooks add skill flowglad/skills --skill subscriptionsReview the files below or copy the command above to add this skill to your agents.
---
name: flowglad-subscriptions
description: Manage subscription lifecycle including cancellation, plan changes, reactivation, and status display. Use this skill when users need to upgrade, downgrade, cancel, or reactivate subscriptions.
license: MIT
metadata:
author: flowglad
version: "1.0.0"
---
<!--
@flowglad/skill
sources_reviewed: 2026-01-21T12:00:00Z
source_files:
- platform/docs/features/subscriptions.mdx
- platform/docs/sdks/subscription-management.mdx
-->
# 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
1. [Reload After Mutations](#1-reload-after-mutations) — **CRITICAL**
- 1.1 [Client-Side State Sync](#11-client-side-state-sync)
- 1.2 [Server-Side Reload Pattern](#12-server-side-reload-pattern)
2. [Cancel Timing Options](#2-cancel-timing-options) — **HIGH**
- 2.1 [End of Period vs Immediate](#21-end-of-period-vs-immediate)
- 2.2 [User Communication](#22-user-communication)
3. [Upgrade vs Downgrade Behavior](#3-upgrade-vs-downgrade-behavior) — **HIGH**
- 3.1 [Immediate Upgrades](#31-immediate-upgrades)
- 3.2 [Deferred Downgrades](#32-deferred-downgrades)
4. [Reactivation with uncancelSubscription](#4-reactivation-with-uncancelsubscription) — **MEDIUM**
- 4.1 [Reactivating Canceled Subscriptions](#41-reactivating-canceled-subscriptions)
5. [Trial Status Detection](#5-trial-status-detection) — **MEDIUM**
- 5.1 [Checking Trial Status](#51-checking-trial-status)
- 5.2 [Trial Expiration Handling](#52-trial-expiration-handling)
6. [Subscription Status Display](#6-subscription-status-display) — **MEDIUM**
- 6.1 [Status Mapping](#61-status-mapping)
- 6.2 [Pending Cancellation Display](#62-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**
```tsx
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**
```tsx
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**
```typescript
// 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**
```typescript
// 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**
```typescript
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)**
```typescript
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**
```tsx
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**
```tsx
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**
```tsx
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**
```tsx
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**
```tsx
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**
```tsx
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**
```tsx
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**
```tsx
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**
```tsx
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**
```tsx
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**
```tsx
function Dashboard() {
// User's trial expires silently, they lose access unexpectedly
return <MainContent />
}
```
**Correct: warn before trial expires**
```tsx
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**
```tsx
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**
```tsx
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**
```tsx
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**
```tsx
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
```typescript
// 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
```typescript
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
```
This skill manages the full subscription lifecycle: cancellation, plan changes (upgrades and downgrades), reactivation, trial handling, and status display. It ensures billing behavior is correct and the UI reflects the true subscription state after any mutation. Use it to implement clear, predictable subscription flows and reduce billing-related support issues.
The skill performs subscription mutations via the billing API and enforces a reload pattern so client and server states stay in sync after changes. It exposes explicit semantics for cancellation timing (immediate vs end-of-period), default behaviors for upgrades (immediate, prorated) and downgrades (deferred), and a reactivation path that uncancels subscriptions canceled at period end. It also surfaces trial detection and status mapping for accurate UI messaging.
What happens if I don't reload billing data after a change?
The UI or API responses can show stale subscription status, causing user confusion and incorrect actions; always fetch fresh billing state after mutations.
When should I use immediate cancellation?
Use immediate cancellation only for fraud prevention, explicit refund requests, or account deletion — otherwise cancel at period end to honor paid access.