Fetch allowed plan configuration
Use the fetchAllowedPlanConfig function to control the plans and addons a customer can select when they change their subscription in the Self-Serve Portal. With this function, you can:
- Specify the plans and addons that a customer can select.
- Restrict the addons available for a specific plan.
- Auto-attach addons to a plan when the customer selects it.
- Set quantity constraints for a plan or addon.
This function is one of the two functions supported by Portal Custom Code.
Usage and invocation
Chargebee invokes this function to get the plan and addon combinations for a subscription. The customer sees only the plans and addons that the function returns when they change the subscription. Write your business logic in the function to restrict the plans and addons for your customers.
Example
Suppose your catalog has a basic group and a premium group of plans and addons. In your function, check the customer's current plan and return only the appropriate group: for a customer on the Platinum plan, return the premium group so they can move to a higher tier; for a customer on the Gold plan, return the basic group so they see the relevant options during a downgrade.
Requirements
- Write the function in JavaScript.
- Make sure the function runs in a Node.js v6.0 environment.
- Use the resources that Chargebee passes to the function to write your business logic. These resources use the same format as the output of the Node.js client library.
- To retrieve additional resources, use Chargebee's Node.js client library, provided you've already configured it with your API key and secret key.
- Return a JavaScript object that matches the JSON schema on this page.
- To apply quantity constraints, enable the Customize plan/addon quantity based on meta configuration setting in your Checkout and Self-Serve Portal settings.
Parameters
| Parameter | Type | Description |
|---|---|---|
data | Object | The resources that Chargebee passes to your custom code. |
data.subscription | Object | The subscription object. |
data.customer | Object | The customer object. |
data.item_prices | Array<Object> | The plan and addon item prices currently part of the subscription. |
callback | Function | Function to send the output of the custom code to Chargebee. |
callback.error | Object | Error details to be sent to Chargebee when the custom code has not been successfully executed. |
callback.success | Object | Output of the custom code to be sent to Chargebee when the custom code has been successfully executed. |
logger | Function | Helps log debug information for your custom code. To emit a log entry, call logger.debug('key', 'value') in your custom code. The logs appear in Chargebee Billing on the Custom Codes page at https://YOUR_SUBDOMAIN.chargebee.com/custom_codes, under the Execution section, after you execute the custom code. |
Return value
Return a JavaScript object with the following properties to pass data to Chargebee. Chargebee then displays this data on the portal for the customer.
| Property | Type | Description |
|---|---|---|
items | Array<Object> | The plan item prices that are available to the customer for selection, along with the constraints on the addons and quantity for each plan item price. |
items[].plan_id | String, required | The ID of the plan item price that is available to the customer for selection. For example, professional. |
items[].allowed_addons | Array<Object> | The addon item prices that are available to the customer for selection for this plan item price. This set overrides the top-level allowed_addons property. |
items[].addons | Array<Object> | List of addon item prices to be auto-attached to the new plan item price. |
items[].meta_data.quantity_meta | Object | A constraint on the selectable quantity of the plan item price. See Quantity constraints. |
allowed_addons | Array<Object> | The subset of addons that the customer is allowed to select from. This set is overridden for each plan item price by the items[].allowed_addons property. |
use_existing_addons | Boolean | If true, the existing addons on the subscription are auto-attached to the new plan item price. Defaults to false. |
Every addon object—in allowed_addons, items[].allowed_addons, and items[].addons—takes the following shape.
| Property | Type | Description |
|---|---|---|
id | String, required | The ID of the addon item price. For example, sms_credits. |
meta_data.quantity_meta | Object | A constraint on the selectable quantity of the addon item price. See Quantity constraints. |
Quantity constraints
A quantity_meta object expresses the constraint either as a range (type: range) or as a fixed set of quantities (type: fixed).
| Property | Type | Description |
|---|---|---|
type | String, required | The kind of quantity constraint. One of range or fixed. |
min | Number | The minimum quantity that the customer is allowed to select. Applicable and required when type is range. |
max | Number | The maximum quantity that the customer is allowed to select. Applicable and required when type is range. |
step | Number | The step size of the quantity that the customer is allowed to select. Applicable when type is range. |
values | Array<Number> | An array of fixed quantities that the customer is allowed to select from. Applicable and required when type is fixed. |
Example
The following function offers the customer two plans and auto-attaches an onboarding addon when they select the professional plan. Because the return value is static, this function makes no API calls and is a useful starting point before you add your own business logic.
exports.fetchAllowedPlanConfig = function ({ subscription, customer, item_prices }, callback, logger) {
const output = {
items: [
{
plan_id: "standard-USD-monthly"
},
{
plan_id: "professional-USD-monthly",
addons: [
{ id: "onboarding-USD-monthly" }
]
}
]
};
callback(null, output);
};The customer sees only the standard and professional plans. When they select professional, Chargebee auto-attaches the onboarding addon.
Sample output
{
"items": [
{
"plan_id": "standard-USD-monthly"
},
{
"plan_id": "professional-USD-monthly",
"addons": [
{ "id": "onboarding-USD-monthly" }
]
}
]
}Use cases
For end-to-end examples that show how to build the return value for common scenarios, such as restricting plans by billing frequency or blocking downgrades, see Fetch allowed plan configuration use cases.
Expected JSON schema for the output
The return value must match the following JSON schema.
JSON schema
{
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"definitions": {
"range_quantity_meta": {
"type": "object",
"description": "A constraint on the selectable quantity of the item price expressed as a range.",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"range"
]
},
"min": {
"type": "number",
"description": "The minimum quantity of the item price that the customer is allowed to select."
},
"max": {
"type": "number",
"description": "The maximum quantity of the item price that the customer is allowed to select."
},
"step": {
"type": "number",
"description": "The step size of the quantity of the item price that the customer is allowed to select."
}
},
"required": [
"type",
"min",
"max"
]
},
"addon": {
"additionalProperties": false,
"type": "object",
"description": "An addon item price.",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The ID of the addon item price.",
"examples": [
"sms_credits"
]
},
"meta_data": {
"additionalProperties": false,
"type": "object",
"description": "Other details about the addon item price.",
"properties": {
"quantity_meta": {
"description": "A constraint on the selectable quantity of the addon item price.",
"oneOf": [
{
"$ref": "#/definitions/range_quantity_meta"
},
{
"$ref": "#/definitions/fixed_quantity_meta"
}
]
}
}
}
}
},
"fixed_quantity_meta": {
"type": "object",
"description": "A constraint on the selectable quantity of the item price expressed as a fixed set of quantities.",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"fixed"
]
},
"values": {
"type": "array",
"description": "An array of fixed quantities of the item price that the customer is allowed to select from.",
"items": {
"type": "number",
"description": "One of the fixed quantities of the item price that the customer is allowed to select from."
}
}
},
"required": [
"type",
"values"
]
}
},
"properties": {
"items": {
"type": "array",
"description": "",
"items": {
"$id": "/properties/product-item",
"type": "object",
"description": "A plan item price that is available to the customer for selection, and the constraints on the addons and quantity for that plan item price.",
"additionalProperties": false,
"required": [
"plan_id"
],
"properties": {
"plan_id": {
"type": "string",
"description": "The ID of the plan item price that is available to the customer for selection.",
"examples": [
"professional"
]
},
"allowed_addons": {
"type": "array",
"description": "The addon item prices that are available to the customer for selection for this plan item price. This set overrides the `allowed_addons` property.",
"items": {
"$ref": "#/definitions/addon"
}
},
"meta_data": {
"type": "object",
"description": "Other details about the plan item price.",
"additionalProperties": false,
"properties": {
"quantity_meta": {
"description": "A constraint on the selectable quantity of the plan item price.",
"oneOf": [
{
"$ref": "#/definitions/range_quantity_meta"
},
{
"$ref": "#/definitions/fixed_quantity_meta"
}
]
}
}
},
"addons": {
"type": "array",
"description": "List of addon item prices to be auto-attached to the new plan item price.",
"items": {
"$ref": "#/definitions/addon"
}
}
}
}
},
"allowed_addons": {
"type": "array",
"description": "The subset of addons that the customer is allowed to select from. This set is overridden for each plan item price by the `items[].allowed_addons` property.",
"items": {
"$ref": "#/definitions/addon"
}
},
"use_existing_addons": {
"type": "boolean",
"default": false,
"description": "If true, the existing addons on the subscription are auto-attached to the new plan item price.",
"examples": [
true
]
}
},
"additionalProperties": false
}Was this article helpful?