How to Integrate Chargebee with Your Headless CMS

What is Chargebee?

Chargebee is a subscription billing and revenue platform for companies that sell recurring products, including SaaS plans, memberships, usage-based packages, and digital subscriptions. Teams use it to handle product catalogs, invoices, payments, taxes, trials, coupons, dunning, and subscription lifecycle events. It sits in the recurring revenue category alongside tools such as Stripe Billing and Recurly, with a strong focus on subscription operations beyond the first checkout.

Why integrate Chargebee with a headless CMS?

Subscription commerce gets messy when your billing system and customer-facing content drift apart. A plan named “Pro Annual” in Chargebee might appear as “Growth yearly” on your pricing page, while a sales page references a retired trial length. That creates support tickets, failed checkouts, and awkward pricing reviews because nobody knows which system is correct.

Architecture overview

A typical Sanity and Chargebee integration starts with subscription plan content in the Content Lake. In Sanity Studio, you model fields such as plan name, slug, feature bullets, Chargebee item ID, Chargebee item price ID, item family ID, currency, price in cents, billing interval, trial days, and region. When an editor publishes a plan, a Sanity webhook can trigger on a GROQ filter like _type == "subscriptionPlan" and !(_id in path("drafts.**")). The webhook sends the document ID to a Sanity Function or an HTTPS middleware endpoint. That server-side code uses @sanity/client and GROQ to fetch exactly the fields Chargebee needs, including referenced feature groups or localized price copy. Then it calls Chargebee’s Product Catalog 2.0 API through the official Node SDK, usually item.create or item.update for the plan, and item_price.create or item_price.update for the billable price. The frontend still reads display content from Sanity, then starts checkout with Chargebee hosted pages or Chargebee.js using the synced item_price_id. The customer sees current plan copy, clicks a plan, and lands in a checkout flow tied to the right Chargebee billing object.

Common use cases

Step-by-step integration

1. 1

   Set up Chargebee

   Create a Chargebee site, choose Product Catalog 2.0, create an item family, and generate an API key from Settings > Configure Chargebee > API Keys and Webhooks. In your app, install the SDK with npm install chargebee.

2. 2

   Model subscription plans in Sanity Studio

   Create a subscriptionPlan schema with fields for title, slug, feature bullets, chargebeeItemId, chargebeeItemPriceId, itemFamilyId, currencyCode, priceCents, billingPeriod, billingPeriodUnit, trialDays, and status. Keep billing identifiers separate from marketing copy so editors can work safely.

3. 3

   Create a publish trigger

   Add a Sanity webhook with a GROQ filter for published subscriptionPlan documents. Send a small payload, for example { "documentId": _id }, to a Sanity Function or your own API route.

4. 4

   Fetch only the fields Chargebee needs

   In the handler, use @sanity/client with GROQ to fetch the plan, its billing metadata, and any referenced feature labels needed for Chargebee metadata. Don’t send draft content or presentation-only fields to Chargebee.

5. 5

   Call Chargebee’s API

   Use the Chargebee Node SDK to create or update the item and item price. Store stable IDs in Sanity, such as pro-monthly-usd, so your website, checkout flow, and billing catalog refer to the same object.

6. 6

   Test the buying path

   Publish a test plan, confirm the item and item price in Chargebee, then open checkout from your frontend with the synced item_price_id. Test at least one monthly plan, one annual plan, one coupon, and one failed payment scenario.

How Sanity + Chargebee works

CMS approaches to Chargebee

Keep building

Explore related integrations to complete your content stack.