Better Auth Chargebee Plugin

This plugin integrates Chargebee with Better Auth to handle subscription and billing flows in authentication-driven products.

It supports subscription lifecycle management, webhook synchronization, secure checkout creation, and optional authorization for organization-based references.

Installation

# Using npm
npm install better-auth @crabnebula/better-auth-chargebee

# Using yarn
yarn add better-auth @crabnebula/better-auth-chargebee

# Using pnpm
pnpm add better-auth @crabnebula/better-auth-chargebee

# Using bun
bun add better-auth @crabnebula/better-auth-chargebee

Overview

This plugin replaces manual subscription logic with a fully managed integration between Better Auth sessions and Chargebee subscriptions.

It handles:

• Secure subscription creation, upgrades, and cancellations
• Customer association with user sessions
• Webhook-driven synchronization with Chargebee
• Authorization of multi-tenant (organization) references
• Automatic plan limit injection
• Basic Auth–protected webhooks

Basic Usage

Add the Plugin to Better Auth

// auth.ts
import { betterAuth } from "better-auth";
import { chargebee } from "@crabnebula/better-auth-chargebee";
import Chargebee from "chargebee";

const chargebeeClient = new Chargebee({
  site: process.env.CHARGEBEE_SITE!,
  api_key: process.env.CHARGEBEE_API_KEY!,
});

export const auth = betterAuth({
  baseURL: "https://auth.yourapp.com",
  plugins: [
    chargebee({
      chargebeeClient,
      chargebeeWebhookAuth: process.env.CHARGEBEE_WEBHOOK_AUTH,
      subscription: {
        requireEmailVerification: true,
        onSuccessfulCheckout: async ({ user, subscription }) => {
          console.log(`User ${user.id} subscribed to ${subscription.plan}`);
        },
        onWehbookEvent: async ({ event, subscription }) => {
          console.log("Webhook received:", event.event_type, subscription.status);
        },
      },
    }),
  ],
});

Endpoints

| Endpoint | Method | Description | |-----------|---------|-------------| | /subscription/checkout | POST | Creates or upgrades a subscription | | /subscription/cancel | POST | Cancels an active subscription | | /subscription/list | GET | Lists all active subscriptions for a reference | | /subscription/success | GET | Callback endpoint after Chargebee hosted page checkout | | /chargebee/webhook | POST | Webhook endpoint to synchronize subscription updates |

Example: Create or Upgrade Subscription

POST /subscription/checkout
{
  "plan": "pro",
  "annual": true,
  "seats": 1,
  "returnUrl": "https://app.yourapp.com/checkout/success"
}

Response:

{
  "url": "https://yourapp.chargebee.com/pages/v3/checkout...",
  "redirect": true
}

License

MIT or MIT/Apache 2.0 where applicable.