How to Integrate Recurly with Your Headless CMS

What is Recurly?

Recurly is a subscription billing platform for companies that sell recurring products, memberships, digital subscriptions, SaaS plans, and usage-based services. It handles subscription plans, billing accounts, invoicing, renewals, dunning, coupons, taxes, and payment gateway connections. Teams use Recurly when subscription logic needs to live in a dedicated billing system while product, pricing, and merchandising content live in a separate publishing workflow.

Why integrate Recurly with a headless CMS?

Subscription commerce gets messy when billing data and customer-facing content drift apart. A pricing page might say a plan costs $19 per month, while Recurly charges $24 because finance updated the plan in billing first. Or editorial teams may update plan descriptions, trial messaging, FAQs, and localization in a publishing workflow, but developers still need to manually copy plan codes and prices into the checkout app.

Architecture overview

A typical Recurly and Sanity integration starts with subscription plan content modeled in Sanity Studio. Editors publish a plan document that includes fields such as plan name, Recurly plan code, billing interval, price display text, currency, feature list, trial messaging, legal footnotes, and channel-specific copy. When the document is published, a Sanity webhook or Function receives the mutation event. The handler uses GROQ to fetch only the fields needed for billing sync, including referenced feature groups or localized copy if needed. The server-side code then calls Recurly's Node SDK with the Recurly API key, checks whether a plan with the same code already exists, and creates or updates the plan through Recurly's Plans API. Your frontend reads display content from Sanity and uses the Recurly plan code when sending the shopper into checkout or creating a subscription. The end user sees the latest approved content, while Recurly continues to handle subscription creation, renewals, invoicing, payment collection, and account state.

Common use cases

Step-by-step integration

1. 1

   Set up Recurly access

   Create or use an existing Recurly site, then generate a private API key from Integrations > API Credentials in Recurly. Install the Node SDK with npm install recurly, and keep the key in server-side environment variables only.

2. 2

   Model subscription plans in Sanity Studio

   Create a plan schema with fields such as title, recurlyPlanCode, billingInterval, currency, unitAmount, trialLength, featureList, checkoutDisclaimer, and market. Keep Recurly identifiers in explicit fields so editors don't paste plan codes into rich text.

3. 3

   Decide field ownership

   Use Sanity for customer-facing content and planned changes. Use Recurly for subscription lifecycle data, payment state, invoices, accounts, and active customer subscriptions. Avoid syncing live subscriber state back into editable content documents.

4. 4

   Create the sync trigger

   Use a Sanity webhook filtered to published plan documents, or a Sanity Function triggered by content mutations. Include the document ID in the payload, then fetch the current published document with GROQ before calling Recurly.

5. 5

   Call Recurly's Plans API

   In the handler, use the Recurly SDK to look up the plan by code. If it exists, update editable plan fields such as name and description. If it doesn't exist, create it with the plan code, billing interval, currency, and unit amount.

6. 6

   Test the customer journey

   Publish a draft plan in a non-production Sanity dataset, sync it to a Recurly sandbox site, and run checkout with Recurly.js or your commerce backend. Test create, update, archive, currency, and coupon cases before connecting production.

How Sanity + Recurly works

CMS approaches to Recurly

Keep building

Explore related integrations to complete your content stack.