chargebee/api-methods

11 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Chargebee subscription.create API endpoint

POST /subscription/create (requires session). Parameters: itemPriceId (string or string[] for multi-item, required), referenceId (string, defaults based on customerType), metadata (Record<string, any>), customerType (string: 'user' or 'organization', default 'user'), seats (number, default 1), successUrl (string, required), cancelUrl (string, required), disableRedirect (boolean, default false), trialEnd (number as Unix timestamp).

Chargebee subscription.update API endpoint

POST /subscription/update (requires session). Parameters: itemPriceId (string or string[] for multi-item, required), referenceId (string), subscriptionId (string), metadata (Record<string, any>), customerType (string: 'user' or 'organization', default 'user'), seats (number, default 1), successUrl (string, required), cancelUrl (string, required), returnUrl (string), disableRedirect (boolean, default false).

Chargebee subscription.list API endpoint

GET /subscription/list (requires session). Parameters: referenceId (string, defaults based on customerType), customerType (string: 'user' or 'organization', default 'user'). Returns array of active/trialing subscriptions enriched with plan limits and itemPriceId.

Chargebee subscription.cancel API endpoint

POST /subscription/cancel (requires session). Parameters: referenceId (string, defaults based on customerType), customerType (string: 'user' or 'organization', default 'user'), subscriptionId (string), returnUrl (string, required). Redirects user to Chargebee Portal for cancellation.

Chargebee subscription.portal API endpoint

POST /subscription/portal (requires session). Parameters: referenceId (string, defaults based on customerType), customerType (string: 'user' or 'organization', default 'user'), returnUrl (string, required), disableRedirect (boolean, default false). Returns portal session URL for self-service billing.

Chargebee subscription.create example

Example code to create a subscription: await authClient.subscription.create({ itemPriceId: 'pro-USD-Monthly', successUrl: '/dashboard', cancelUrl: '/pricing', }); This creates a Chargebee Hosted Page and redirects user to checkout.

Chargebee subscription.list example

Example code to list active subscriptions: const { data } = await authClient.subscription.list(); For organization subscriptions: const { data: orgSubscriptions } = await authClient.subscription.list({ query: { referenceId: 'org_123', customerType: 'organization' } });

Chargebee subscription.portal example

Example code to open billing portal: await authClient.subscription.portal({ returnUrl: '/account/billing', fetchOptions: { onSuccess: (ctx) => { window.location.href = ctx.data.url; } } }); For organization: await authClient.subscription.portal({ referenceId: 'org_123456', customerType: 'organization', returnUrl: '/org/billing' });

Chargebee subscription update vs create rules

The plugin only supports one active or trialing subscription per reference ID at a time. Use subscription.update when user already has active subscription and wants to switch plans. Use subscription.create when user has no active subscription. Attempting to create new subscription when user already has active subscription will fail with ALREADY_SUBSCRIBED error. Must provide subscriptionId parameter to subscription.update when needed.

Chargebee team subscriptions with seats

For team or organization plans, specify number of seats: await authClient.subscription.create({ itemPriceId: 'team-USD-Monthly', referenceId: 'org_123456', customerType: 'organization', seats: 10, successUrl: '/org/billing/success', cancelUrl: '/org/billing' }); The seats parameter is passed to Chargebee as quantity for subscription item and can be used in application logic to limit team members.

Chargebee checkout redirect mechanism

Plugin does not redirect straight to successUrl. Instead sets Chargebee's redirect_url to: GET {baseURL}/subscription/success?callbackURL=<your-successUrl>&subscriptionId=<id>. Chargebee lands on that endpoint after checkout, and plugin forwards user to original successUrl. This provides hook point for future middleware (session refresh, subscription sync) without changing call-site code.

Give your agent this brain