Portal Custom Code

With Custom Codes, you can tailor your customer portal to fit your business needs. Whether you want to refine the user experience or add specialized logic, this feature lets you build a customer portal that reflects how you sell.

Custom codes

Custom Codes is a Chargebee feature that lets you run your own business logic while a customer performs certain actions in the portal. Chargebee invokes the function you upload at the relevant point in the flow, passes it the current subscription and catalog data, and uses the value your function returns to control what the customer sees and how the change is applied.

Contact support to enable the Custom Codes feature.
This feature is currently supported in the customer portal's Edit Subscription flow using functions.
To apply quantity constraints through fetchAllowedPlanConfig, enable the Customize plan/addon quantity based on meta configuration setting in your Checkout and Self-Serve Portal settings.

Custom codes use case

Consider an example.

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 code

Function	Use it to
`fetchAllowedPlanConfig`	Restrict the plans and addons a customer can select, auto-attach addons when a plan is selected, and set quantity constraints for a plan or addon.
`fetchChangeSubscriptionOptions`	Decide whether each subscription change applies immediately or at the end of the term. For example, apply upgrades immediately and defer downgrades to the end of the term.

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 example, you can apply upgrades immediately and defer downgrades to the end of the term.

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 example, for customers on the Platinum plan, you can offer plans and addons from a premium group during an upgrade. For customers on the Gold plan, you can offer plans and addons from a basic group during a downgrade.

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

Execute your custom code

How it works

Write your function in JavaScript so that it runs in a Node.js v6.0 environment.
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.
Your function returns a JavaScript object through the callback. Chargebee validates the object against the expected schema and applies it to the portal flow.

If multi-decimal support is enabled for your site, quantities arrive in the *_in_decimal fields as strings, and the corresponding integer fields, such as plan_quantity, are null. Read plan_quantity_in_decimal and the addon quantity_in_decimal instead of plan_quantity and quantity, and wrap the values in Number(...) before you compare them.

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:

Upload the file that contains your business logic.
Pick an execution option. Depending on your code, fetchChangeSubscriptionOptions, fetchAllowedPlanConfig, or both appear in the dropdown.

Enter the required input parameters. Sample input: ['sampleSubscriptionId']
Click Run and validate your results.
Click Publish.

With Custom Codes, you can shape your customer portal into a tailored experience that aligns with your business goals.

Articles & FAQs

What are the events that can be tracked using Facebook Pixel?