Subscription Billing for Chrome Extensions

Getting a Chrome extension user to install your product is hard. Getting them to pay every month is a different challenge entirely. Subscription billing is the most profitable monetization model for extensions that deliver ongoing value, but the implementation details separate extensions that print money from ones that hemorrhage subscribers.

This guide walks through every piece of the subscription billing stack for Chrome extensions: the architecture decisions, the Stripe integration, the license validation system, trial periods, grace periods, upgrade and downgrade flows, and the churn reduction tactics that keep revenue growing month over month. Every code example is production-ready TypeScript you can adapt to your own extension.

The subscription architecture#

Subscription billing for a Chrome extension involves three systems that need to communicate reliably: the extension itself (running in the browser), your backend server (handling payments and license state), and Stripe (processing charges and managing subscription lifecycle).

The flow works like this. A user installs your free extension from the Chrome Web Store. They hit a feature gate or a trial expiration. Your extension opens a checkout page on your website. Stripe processes the payment and fires webhooks to your server. Your server generates or activates a license key. The extension validates that key and unlocks premium features.

Every piece of this chain has failure modes. The webhook might arrive before the redirect. The user might close their browser mid-checkout. Their card might decline on renewal three months later. A robust subscription system handles all of these gracefully.

Server-side license management#

Your server is the source of truth for all license state. Never store payment status solely in the extension or in chrome.storage. Users can tamper with local storage, and you have no way to revoke access if the only record of their subscription lives on their machine.

interface License {
  id: string
  key: string
  userId: string
  stripeCustomerId: string
  stripeSubscriptionId: string
  plan: "trial" | "monthly" | "annual"
  status: "active" | "past_due" | "canceled" | "expired"
  trialEndsAt: Date | null
  currentPeriodEnd: Date
  gracePeriodEnd: Date | null
  createdAt: Date
  updatedAt: Date
}
 
function generateLicenseKey(): string {
  const segments = Array.from({ length: 4 }, () =>
    crypto.randomBytes(4).toString("hex").toUpperCase()
  )
  return segments.join("-")
}
 
async function createLicense(
  userId: string,
  stripeCustomerId: string,
  stripeSubscriptionId: string,
  plan: License["plan"],
  periodEnd: Date
): Promise<License> {
  const license: License = {
    id: crypto.randomUUID(),
    key: generateLicenseKey(),
    userId,
    stripeCustomerId,
    stripeSubscriptionId,
    plan,
    status: "active",
    trialEndsAt: plan === "trial" ? periodEnd : null,
    currentPeriodEnd: periodEnd,
    gracePeriodEnd: null,
    createdAt: new Date(),
    updatedAt: new Date(),
  }
 
  await db.licenses.insert(license)
  return license
}

The status field drives everything downstream. Your extension checks this field on every validation call. Your webhook handler updates it when Stripe sends lifecycle events. Your grace period logic reads it to decide whether to degrade features or lock them entirely.

Stripe Checkout integration#

Stripe Checkout is the fastest path to accepting subscription payments. It handles the payment form, card validation, SCA/3D Secure, and even localized pricing. You create a session on your server, redirect the user to Stripe's hosted page, and handle the result.

Creating checkout sessions#

When a user clicks "Upgrade to Pro" inside your extension, the extension opens a tab to your pricing page. That page calls your server to create a Stripe Checkout session.

import Stripe from "stripe"
 
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)
 
interface CheckoutParams {
  plan: "monthly" | "annual"
  userId: string
  email: string
  extensionId?: string
}
 
async function createCheckoutSession(params: CheckoutParams) {
  const { plan, userId, email, extensionId } = params
 
  const prices: Record<string, string> = {
    monthly: process.env.STRIPE_PRICE_MONTHLY!,
    annual: process.env.STRIPE_PRICE_ANNUAL!,
  }
 
  const session = await stripe.checkout.sessions.create({
    mode: "subscription",
    customer_email: email,
    payment_method_types: ["card"],
    line_items: [{ price: prices[plan], quantity: 1 }],
    subscription_data: {
      trial_period_days: 7,
      metadata: { userId, extensionId: extensionId ?? "" },
    },
    success_url: `${process.env.BASE_URL}/checkout/success?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${process.env.BASE_URL}/pricing`,
    metadata: { userId },
    allow_promotion_codes: true,
  })
 
  return { url: session.url, sessionId: session.id }
}

A few details matter here. The trial_period_days on subscription_data gives every new subscriber a 7-day trial before their card is charged. The metadata fields let you link the Stripe subscription back to your internal user and license records. And allow_promotion_codes lets you run discount campaigns without writing custom coupon logic.

The success page handoff#

After payment, Stripe redirects to your success URL with the session ID. Your success page retrieves the session, creates or activates the license, and shows the user their license key.

async function handleCheckoutSuccess(sessionId: string) {
  const session = await stripe.checkout.sessions.retrieve(sessionId, {
    expand: ["subscription", "customer"],
  })
 
  if (session.payment_status !== "paid" && !session.subscription) {
    throw new Error("Payment not completed")
  }
 
  const subscription = session.subscription as Stripe.Subscription
  const customer = session.customer as Stripe.Customer
  const userId = session.metadata?.userId
 
  if (!userId) throw new Error("Missing userId in session metadata")
 
  const existingLicense = await db.licenses.findByUserId(userId)
 
  if (existingLicense) {
    await db.licenses.update(existingLicense.id, {
      stripeSubscriptionId: subscription.id,
      stripeCustomerId: customer.id,
      plan: subscription.items.data[0].price.recurring?.interval === "year"
        ? "annual" : "monthly",
      status: "active",
      currentPeriodEnd: new Date(subscription.current_period_end * 1000),
      updatedAt: new Date(),
    })
    return { licenseKey: existingLicense.key, isReactivation: true }
  }
 
  const license = await createLicense(
    userId,
    customer.id,
    subscription.id,
    subscription.items.data[0].price.recurring?.interval === "year"
      ? "annual" : "monthly",
    new Date(subscription.current_period_end * 1000)
  )
 
  return { licenseKey: license.key, isReactivation: false }
}

Your success page should display the license key prominently, with a one-click copy button and clear instructions for entering it in the extension. Also send the key via email as a backup. Users close tabs. They forget. The email is your safety net.

Webhook handling#

The checkout success page handles the initial purchase, but the real subscription lifecycle happens through webhooks. Renewals, cancellations, payment failures, plan changes, and trial expirations all arrive as Stripe webhook events. If you do not handle these correctly, your license states will drift out of sync with reality.

The webhook events that matter#

You do not need to handle every Stripe event. For subscription billing, these are the critical ones:

• customer.subscription.created -- New subscription activated (backup for checkout success)
• customer.subscription.updated -- Plan changed, renewed, or status changed
• customer.subscription.deleted -- Subscription fully canceled and period ended
• invoice.payment_succeeded -- Renewal payment went through
• invoice.payment_failed -- Renewal payment failed (start grace period)
• customer.subscription.trial_will_end -- Trial ending in 3 days (send reminder)

async function handleWebhook(event: Stripe.Event) {
  switch (event.type) {
    case "customer.subscription.updated": {
      const sub = event.data.object as Stripe.Subscription
      const userId = sub.metadata.userId
      if (!userId) break
 
      const license = await db.licenses.findByUserId(userId)
      if (!license) break
 
      const newPlan = sub.items.data[0].price.recurring?.interval === "year"
        ? "annual" : "monthly"
 
      const statusMap: Record<string, License["status"]> = {
        active: "active",
        past_due: "past_due",
        canceled: "canceled",
        unpaid: "expired",
        incomplete_expired: "expired",
      }
 
      await db.licenses.update(license.id, {
        plan: newPlan,
        status: statusMap[sub.status] ?? "expired",
        currentPeriodEnd: new Date(sub.current_period_end * 1000),
        gracePeriodEnd: sub.status === "past_due"
          ? new Date(Date.now() + 7 * 24 * 60 * 60 * 1000)
          : null,
        updatedAt: new Date(),
      })
      break
    }
 
    case "customer.subscription.deleted": {
      const sub = event.data.object as Stripe.Subscription
      const userId = sub.metadata.userId
      if (!userId) break
 
      await db.licenses.updateByUserId(userId, {
        status: "expired",
        gracePeriodEnd: null,
        updatedAt: new Date(),
      })
      break
    }
 
    case "invoice.payment_failed": {
      const invoice = event.data.object as Stripe.Invoice
      const subId = invoice.subscription as string
      const license = await db.licenses.findBySubscriptionId(subId)
      if (!license) break
 
      await db.licenses.update(license.id, {
        status: "past_due",
        gracePeriodEnd: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
        updatedAt: new Date(),
      })
 
      await sendPaymentFailureEmail(license.userId, license.gracePeriodEnd!)
      break
    }
 
    case "customer.subscription.trial_will_end": {
      const sub = event.data.object as Stripe.Subscription
      const userId = sub.metadata.userId
      if (!userId) break
      await sendTrialEndingEmail(userId, new Date(sub.trial_end! * 1000))
      break
    }
  }
}

Webhook reliability#

Stripe guarantees at-least-once delivery, which means your webhook handler must be idempotent. The same event can arrive multiple times. Use the event.id as a deduplication key. Store processed event IDs and skip any you have already handled.

Also verify the webhook signature on every request. Stripe signs webhooks with a secret specific to your endpoint. Without verification, anyone can send fake events to your webhook URL and manipulate license states.

License validation in the extension#

The extension needs to check the user's license status on startup, periodically during use, and after any state change (like entering a new license key). The validation endpoint should be fast, cacheable, and resilient to network failures.

interface LicenseStatus {
  valid: boolean
  plan: "free" | "trial" | "monthly" | "annual"
  status: "active" | "past_due" | "canceled" | "expired"
  features: string[]
  expiresAt: string | null
  graceUntil: string | null
}
 
const VALIDATION_INTERVAL = 4 * 60 * 60 * 1000 // 4 hours
const CACHE_KEY = "licenseCache"
 
async function validateLicense(forceRefresh = false): Promise<LicenseStatus> {
  const stored = await chrome.storage.local.get([CACHE_KEY, "licenseKey"])
  const { licenseKey } = stored
  const cache = stored[CACHE_KEY] as
    | { data: LicenseStatus; timestamp: number }
    | undefined
 
  if (!licenseKey) {
    return { valid: false, plan: "free", status: "expired", features: [], expiresAt: null, graceUntil: null }
  }
 
  if (!forceRefresh && cache && Date.now() - cache.timestamp < VALIDATION_INTERVAL) {
    return cache.data
  }
 
  try {
    const response = await fetch("https://api.yourextension.com/license/validate", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ key: licenseKey }),
    })
 
    if (!response.ok) {
      // Network error: fall back to cached status if available
      if (cache) return cache.data
      return { valid: false, plan: "free", status: "expired", features: [], expiresAt: null, graceUntil: null }
    }
 
    const data: LicenseStatus = await response.json()
    await chrome.storage.local.set({
      [CACHE_KEY]: { data, timestamp: Date.now() },
    })
    return data
  } catch {
    // Offline: use cached license for up to 72 hours
    if (cache && Date.now() - cache.timestamp < 72 * 60 * 60 * 1000) {
      return cache.data
    }
    return { valid: false, plan: "free", status: "expired", features: [], expiresAt: null, graceUntil: null }
  }
}
 
// Validate on startup and periodically
chrome.runtime.onStartup.addListener(() => validateLicense(true))
chrome.alarms.create("licenseCheck", { periodInMinutes: 240 })
chrome.alarms.onAlarm.addListener((alarm) => {
  if (alarm.name === "licenseCheck") validateLicense(true)
})

Two design decisions are important here. First, the 72-hour offline grace period. If your user's laptop loses internet on a flight, their premium features should not vanish instantly. Cache the last known license state and respect it for a reasonable window. Second, the 4-hour validation interval. Checking on every page load wastes bandwidth and slows down the extension. Checking once a day is too slow to catch cancellations. Four hours is the sweet spot for most extensions.

Trial period implementation#

Free trials are the most effective conversion mechanism for subscription extensions. A 7-day trial with full feature access converts at 8-15%, compared to 2-5% for a freemium model where users never experience the premium features.

Server-side trial tracking#

Trials should be managed through Stripe's built-in trial functionality, not through custom logic. When you set trial_period_days on the subscription, Stripe handles the timing, sends the trial_will_end event 3 days before expiration, and automatically charges the card when the trial ends.

On your server, the license record reflects the trial state:

async function startTrial(userId: string, email: string) {
  const customer = await stripe.customers.create({
    email,
    metadata: { userId },
  })
 
  const subscription = await stripe.subscriptions.create({
    customer: customer.id,
    items: [{ price: process.env.STRIPE_PRICE_MONTHLY! }],
    trial_period_days: 7,
    payment_behavior: "default_incomplete",
    payment_settings: {
      save_default_payment_method: "on_subscription",
    },
    expand: ["latest_invoice.payment_intent"],
    metadata: { userId },
  })
 
  const license = await createLicense(
    userId,
    customer.id,
    subscription.id,
    "trial",
    new Date(subscription.trial_end! * 1000)
  )
 
  return {
    licenseKey: license.key,
    trialEndsAt: license.trialEndsAt,
    clientSecret: (
      (subscription.latest_invoice as Stripe.Invoice)
        .payment_intent as Stripe.PaymentIntent
    )?.client_secret,
  }
}

Using payment_behavior: "default_incomplete" means Stripe collects payment method details upfront but does not charge until the trial ends. This is the highest-converting trial pattern. Users who enter a card at trial signup convert at nearly double the rate of users who are asked for payment only at trial expiration.

Grace periods and payment recovery#

A subscriber's card declines. Maybe it expired, maybe the bank flagged the charge, maybe the account hit its limit. What happens next determines whether you keep or lose that customer. The wrong answer is immediately revoking access.

The grace period flow#

When invoice.payment_failed fires, your server should:

1. Set the license status to past_due
2. Set a gracePeriodEnd date 7 days in the future
3. Send an email explaining the issue with a direct link to update payment
4. Show a gentle banner inside the extension (not a modal, not a lockout)

During the grace period, Stripe's Smart Retries automatically attempt the charge again on different days and at different times. Smart Retries recover about 15-20% of failed payments without any action from the user. Your grace period gives those retries time to work.

If the grace period expires and no payment has been recovered, downgrade the user to the free tier with a clear message explaining what happened and a one-click path to resubscribe. Do not delete their data or configuration. Many users who churn involuntarily (card issues, not intentional cancellation) will come back within 30 days if you make reactivation painless.

In-extension payment recovery banner#

Inside the extension, detect the past_due status and show a non-intrusive but visible banner:

function getPaymentBannerState(license: LicenseStatus): {
  show: boolean
  message: string
  urgency: "info" | "warning" | "critical"
  ctaUrl: string
} {
  if (license.status !== "past_due" || !license.graceUntil) {
    return { show: false, message: "", urgency: "info", ctaUrl: "" }
  }
 
  const graceEnd = new Date(license.graceUntil)
  const now = new Date()
  const daysLeft = Math.ceil((graceEnd.getTime() - now.getTime()) / (1000 * 60 * 60 * 24))
 
  if (daysLeft > 3) {
    return {
      show: true,
      message: "Your payment method needs updating. Premium features remain active.",
      urgency: "info",
      ctaUrl: "https://yourextension.com/account/billing",
    }
  }
 
  if (daysLeft > 0) {
    return {
      show: true,
      message: `Payment issue: premium access expires in ${daysLeft} day${daysLeft > 1 ? "s" : ""}. Update your payment method now.`,
      urgency: "warning",
      ctaUrl: "https://yourextension.com/account/billing",
    }
  }
 
  return {
    show: true,
    message: "Premium access has been paused. Update your payment method to reactivate instantly.",
    urgency: "critical",
    ctaUrl: "https://yourextension.com/account/billing",
  }
}

The escalating urgency pattern is intentional. Early in the grace period, you gently inform. As the deadline approaches, the language becomes more direct. After expiration, you make reactivation feel instant and easy, not punitive.

Upgrade and downgrade flows#

Users change plans. They upgrade from monthly to annual to save money. They downgrade from Pro to Basic. They switch seats in a team plan. Each transition has billing implications that Stripe handles well, but only if you set it up correctly.

Handling plan changes#

For upgrades (monthly to annual, Basic to Pro), apply the change immediately and prorate. The user pays the difference for the remainder of their current billing period, and the new plan takes effect right away. Immediate value delivery reinforces the upgrade decision.

For downgrades, apply the change at the end of the current billing period. The user already paid for their current tier, so let them use it until the period ends. This feels fair and avoids the frustration of paying for features that disappear mid-cycle.

Stripe's proration_behavior parameter controls this:

async function changePlan(
  subscriptionId: string,
  newPriceId: string,
  direction: "upgrade" | "downgrade"
) {
  const subscription = await stripe.subscriptions.retrieve(subscriptionId)
  const currentItemId = subscription.items.data[0].id
 
  if (direction === "upgrade") {
    const updated = await stripe.subscriptions.update(subscriptionId, {
      items: [{ id: currentItemId, price: newPriceId }],
      proration_behavior: "always_invoice",
    })
    return { effectiveNow: true, subscription: updated }
  }
 
  // Downgrade: apply at period end
  const updated = await stripe.subscriptions.update(subscriptionId, {
    items: [{ id: currentItemId, price: newPriceId }],
    proration_behavior: "none",
    billing_cycle_anchor: "unchanged",
  })
 
  // Schedule the actual plan change for period end
  await stripe.subscriptionSchedules.create({
    from_subscription: subscriptionId,
    phases: [
      {
        items: [{ price: newPriceId, quantity: 1 }],
        start_date: subscription.current_period_end,
      },
    ],
  })
 
  return { effectiveNow: false, effectiveDate: new Date(subscription.current_period_end * 1000) }
}

Communicate clearly inside the extension when a downgrade is pending. Show a message like "Your plan changes to Basic on April 15. Pro features remain active until then." Users who understand the timeline are less likely to contact support or feel confused.

Churn reduction tactics#

Acquiring a new subscriber costs 5-7 times more than retaining an existing one. Every percentage point of churn you eliminate compounds into significant revenue over 12 months. Here are the tactics that move the needle for extension subscriptions.

Cancellation flow with save offers#

When a user clicks "Cancel subscription," do not just process the cancellation. Show a cancellation flow that asks why they are leaving and offers a relevant counter:

• "Too expensive" -- Offer a discounted annual plan or a 30% discount for the next 3 months
• "Not using it enough" -- Suggest a downgrade to a cheaper plan instead of full cancellation
• "Missing a feature" -- Capture the feedback and offer to notify them when the feature ships
• "Switching to a competitor" -- Ask which competitor and what they offer that you do not

Save offers recover 10-25% of cancellation attempts. A 30% discount for 3 months is vastly cheaper than losing the customer and the compounding revenue they would have generated.

Engagement-based retention#

Track feature usage within your extension. When a paying user's engagement drops significantly (they go from daily use to once a week), send a re-engagement email highlighting features they have not tried yet. Users who forget about your extension cancel passively. Reminding them of value they are not extracting prevents that drift.

Dunning email sequence#

When a payment fails, send a sequence of emails, not just one:

• Day 0: "Your payment didn't go through. Here's a link to update your card." (casual, helpful)
• Day 3: "Reminder: your premium access will pause in 4 days unless we can process your payment." (clear urgency)
• Day 6: "Last day: update your payment method to keep premium features active." (final notice)
• Day 7: "Your premium access has been paused. Click here to reactivate instantly." (immediate recovery path)

This sequence, combined with Stripe Smart Retries, recovers 30-50% of involuntary churn. Without it, every failed payment is a lost customer.

Common pitfalls and how to avoid them#

Validating licenses only on install. If you check the license once and cache it forever, users can pay for one month, extract a valid license, cancel, and keep using premium features indefinitely. Validate periodically (every 4 hours is the sweet spot) and enforce server-side expiration.

Storing Stripe API keys in the extension. Your extension code is publicly accessible. Anyone can extract your Stripe secret key from the extension bundle and make API calls on your behalf. All Stripe communication must go through your server. The extension talks to your server. Your server talks to Stripe. No exceptions.

Ignoring timezone issues in trial expiration. A user signs up at 11:59 PM in their timezone but your server is in UTC. If your trial expiration logic uses raw date comparison without accounting for timezone differences, users will perceive the trial as shorter than advertised. Use Stripe's built-in trial management, which handles this correctly.

Not handling subscription reactivation. A user cancels, then wants to come back two months later. If your system treats them as a brand new customer, they lose their settings, usage history, and any custom configurations. Always check for existing license records during checkout and reactivate rather than recreate.

Skipping the customer portal. Stripe's Customer Portal lets users update payment methods, view invoices, and manage their subscription without you building any UI. Set it up. It reduces support tickets dramatically and gives users a sense of control over their billing.

Putting it all together#

The subscription billing system for a Chrome extension is not one feature. It is a stack of interlocking systems: Stripe Checkout for acquisition, webhooks for lifecycle management, license validation for enforcement, grace periods for retention, and save offers for churn reduction. Each layer depends on the others.

Start with the minimum viable version: Stripe Checkout, a simple license key, and a validation endpoint. Then layer on trial periods, grace periods, and cancellation flows as your subscriber count grows. You do not need all of this on day one, but you need to know it is coming so your initial architecture does not paint you into a corner.

The extensions that generate sustainable recurring revenue are not the ones with the best features. They are the ones that treat billing as a product unto itself, with the same care and iteration they give to their core functionality.