Chargebee plugin options
The Chargebee plugin accepts these options: chargebeeClient (Chargebee instance, required), webhookUsername (string for Basic Auth, recommended in production), webhookPassword (string for Basic Auth, recommended in production), createCustomerOnSignUp (boolean, default false), getCustomerCreateParams (function receiving user and optional ctx), onCustomerCreate (function receiving {chargebeeCustomer, user}), webhookHandler (function receiving WebhookHandler instance), subscription (object for subscription config), organization (object for org customer support).
Chargebee subscription options
Subscription configuration options: enabled (boolean, required), plans (ChargebeePlan[] or async function returning plans, required if enabled), requireEmailVerification (boolean, default false), preventDuplicateTrials (boolean, default false), authorizeReference (function receiving {user, session, referenceId, action}), getHostedPageParams (function receiving {user, session, plan, subscription}), onSubscriptionComplete (function), onSubscriptionCreated (function), onSubscriptionUpdate (function), onSubscriptionDeleted (function), onTrialStart (function), onTrialEnd (function).
Chargebee plan configuration fields
Plan configuration requires: name (string, required), itemPriceId (string, required), type (string: 'plan', 'addon', or 'charge', required). Optional fields: itemId (string), itemFamilyId (string), limits (object for plan limits), freeTrial (object with days property), trialPeriod (number), trialPeriodUnit (string: 'day' or 'month'), billingCycles (number).
Chargebee dynamic plans recommendation
Fetching plans from database is the recommended approach over static plans. It gives full control over plan data, lets you enrich plans with custom metadata (limits, features, display info), and avoids hard-coding Chargebee configuration into auth setup. Plans can be defined as an async function that returns array of plan objects.
Chargebee custom hosted page parameters
Use getHostedPageParams function to customize Chargebee Hosted Page: getHostedPageParams: async ({ user, session, plan, subscription }, request, ctx) => { return { embed: false, layout: 'in_app', pass_thru_content: JSON.stringify({...}), redirect_url: 'https://yourdomain.com/success', cancel_url: 'https://yourdomain.com/cancel' }; }
Chargebee getCustomerCreateParams usage
getCustomerCreateParams applies to both createCustomerOnSignUp and on-demand customer creation (e.g., first subscription). Example: getCustomerCreateParams: (user) => { const [firstName, ...rest] = (user.name ?? '').split(' '); return { first_name: firstName || undefined, last_name: rest.join(' ') || undefined }; }. For organizations, use organization.getCustomerCreateParams instead. Callback receives user object and optional ctx (only available during on-demand creation, not signup).
Chargebee subscription lifecycle hooks
Available lifecycle hooks: onSubscriptionComplete (called when subscription created via hosted page), onSubscriptionCreated (called when subscription created), onSubscriptionUpdate (called when subscription updated), onSubscriptionDeleted (called when subscription deleted), onTrialStart (called when trial starts), onTrialEnd (called when trial ends). Each receives relevant subscription and plan data.
Chargebee onCustomerCreate callback
onCustomerCreate callback is called after a customer is created. Example: onCustomerCreate: async ({ chargebeeCustomer, user }) => { console.log(`Customer ${chargebeeCustomer.id} created for user ${user.id}`); }. Receives chargebeeCustomer object and user object.
Chargebee static plans example
Example static plans configuration: subscription: { enabled: true, plans: [ { name: 'starter', itemPriceId: 'starter-USD-Monthly', type: 'plan', limits: { projects: 5, storage: 10 } }, { name: 'pro', itemPriceId: 'pro-USD-Monthly', type: 'plan', limits: { projects: 20, storage: 50 }, freeTrial: { days: 14 } } ] }
Chargebee dynamic plans example
Example dynamic plans from database: subscription: { enabled: true, plans: async () => { const plans = await db.query('SELECT * FROM plans'); return plans.map(plan => ({ name: plan.name, itemPriceId: plan.chargebee_item_price_id, type: 'plan' as const, limits: JSON.parse(plan.limits) })); } }