flowglad-subscriptions

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"}

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 — CRITICAL
   • 1.1 Client-Side State Sync
   • 1.2 Server-Side Reload Pattern
2. Cancel Timing Options — HIGH
   • 2.1 End of Period vs Immediate
   • 2.2 User Communication
3. Upgrade vs Downgrade Behavior — HIGH
   • 3.1 Immediate Upgrades
   • 3.2 Deferred Downgrades
4. Reactivation with uncancelSubscription — MEDIUM
   • 4.1 Reactivating Canceled Subscriptions
5. Trial Status Detection — MEDIUM
   • 5.1 Checking Trial Status
   • 5.2 Trial Expiration Handling
6. 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