Portal Custom Code

Custom Codes lets you tailor the Chargebee Self-Serve Portal to how you sell by adding your own business logic to portal flows.

Custom Codes

Custom Codes is a Chargebee feature that lets you run your own business logic while a customer performs certain actions in the Self-Serve Portal. Chargebee invokes the function you upload on Chargebee infrastructure during the flow, passes it the current subscription and catalog data, and uses the value your function returns to control which plans and addons are offered and how the change is applied. It does not change the hosted portal layout or how those options are rendered.

Custom Codes use case

James runs a fitness app with three plans that his users can subscribe to: Elite, Pro, and Luxe.

James wants to show only higher-tier plans when a user changes their subscription. For example, when a user on the Pro plan changes their subscription, the portal should list only Luxe and not Elite.

Custom Codes lets James implement this logic using functions.

Supported functions for Custom Codes

Fetch change subscription options

Use fetchChangeSubscriptionOptions to control whether a subscription change takes effect immediately or at the end of the term, based on your custom logic.

Implement your logic for the subscription-change scenarios that should apply immediately and those that should apply at the end of the term, and return a value for each:

• To apply the change immediately, set end_of_term to false.
• To apply the change at the end of the term, set end_of_term to true.

For the parameters, the return value, and worked examples, see Retrieve subscription change timeline.

Fetch allowed plan config

Use fetchAllowedPlanConfig to do the following:

• Specify the allowed plans and addons.
• Auto-attach addons to a plan when it's selected.
• Set quantity constraints for a plan or addon.

This function returns the plan and addon combinations available for a subscription. The customer sees only the plans and addons in this list when they change their subscription. Write your business logic in this function to restrict the plan and addon lists for your customers.

For the parameters, the return value, and worked examples, see Fetch allowed plan configuration.

What Custom Codes does not support

Custom Codes is a decision hook for the hosted Self-Serve Portal Edit Subscription flow. It is not a way to customize the portal interface or to add new customer-facing workflows inside the portal.

Custom Codes does not let you:

• Change how the portal renders plans, addons, or other controls. For example, you cannot replace the standard plan and addon selectors with a custom product catalog, grid, or shop-style layout.
• Inject your own HTML or CSS, change portal navigation, or add new screens or steps to a portal flow.
• Run code in the end customer's browser. Your function runs on Chargebee when the customer edits a subscription, not inside the iframe or modal that Chargebee.js opens.
• Use the portal as a general-purpose layer for calling your own backend services during the flow. Retrieve data from Chargebee inside your function with the Node.js client library; do not rely on Custom Codes to orchestrate separate business workflows in your application.

When to build your own interface

If you need a subscription-change experience that goes beyond configuration and Custom Codes—for example, a bespoke product selection screen that matches your storefront—you build that interface in your application and use Chargebee as the billing engine behind it.

Typical building blocks:

• Catalog and eligibility: Use the Product Catalog and Subscriptions APIs to list items and read the customer's subscription.
• Preview before commit: Use estimate APIs to show financial impact before the customer confirms a change.
• Apply the change: Update the subscription through the API, or hand the customer to hosted checkout to confirm a change when you want card handling to stay on Chargebee.
• Card and payment method collection: Embed payment components or card components in your pages when you collect payment details yourself.

You do not have to replace the entire portal. A common pattern is to build only the catalogue and selection experience in your app, and keep the hosted Self-Serve Portal for routine actions such as invoices, payment method updates, and cancellation. Chargebee Widgets and portal integration let you open specific portal sections from your application when you use API-based access. For an overview of the hosted portal versus a custom build, see Hosted Self-Serve Portal.

Execute your custom code

How it works

1. Write your function in JavaScript so that it runs in a Node.js v6.0 environment.
2. Chargebee invokes the function and passes it the resources for the current subscription. These resources use the same format as the output of the Node.js client library. To retrieve additional resources, call the client library from within your function.
3. Your function returns a JavaScript object through the callback. Chargebee validates the object against the expected schema and applies it to the portal flow.

Upload and publish

After support enables Custom Codes, access it at https://YOUR_SITE_NAME.chargebee.com/custom_codes.

The published version of your custom code is available at this link. To make changes, select Download code to download the current custom code.

To run your custom code, follow these steps:

1. Upload the file that contains your business logic.

2. Select an execution option from the dropdown. Depending on your code, the dropdown lists fetchChangeSubscriptionOptions, fetchAllowedPlanConfig, or both.

   

3. Enter the required input parameters. Sample input: ['sampleSubscriptionId']

4. Click Run and validate your results.

5. Click Publish.