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 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.
Custom Codes supports only the Edit Subscription flow in the Self-Serve Portal, through 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

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

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.
Select an execution option from the dropdown. Depending on your code, the dropdown lists fetchChangeSubscriptionOptions, fetchAllowedPlanConfig, or both.
Enter the required input parameters. Sample input: ['sampleSubscriptionId']
Click Run and validate your results.
Click Publish.

Articles & FAQs

Operations that can be performed using Custom Code

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