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.
Note
This page covers sites on Product Catalog 1.0, where the function receives plans and addons. If your site is on Product Catalog 2.0, the function receives item prices instead, and the code on this page does not apply.
Note
fetchAllowedPlanConfig does not override mandatory addons. Include mandatory addons as part of the output JSON.
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.plans | Object | Current plan details. |
data.addons | Object | List of current addons linked to 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 plans that are available to the customer for selection, along with the constraints on the addons and quantity for each plan. |
items[].plan_id | String, required | The ID of the plan that is available to the customer for selection. For example, professional. |
items[].allowed_addons | Array<Object> | The addons that are available to the customer for selection for this plan. This set overrides the top-level allowed_addons property. |
items[].addons | Array<Object> | List of addons to be auto-attached to the new plan. |
items[].meta_data.quantity_meta | Object | A constraint on the selectable quantity of the plan. 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 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. 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. For example, sms_credits. |
meta_data.quantity_meta | Object | A constraint on the selectable quantity of the addon. 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
This function lists the per-unit plans on the site and applies a quantity range to each one, using the cf_seats custom field on the subscription as the minimum.
var chargebee = require("chargebee")
exports.fetchAllowedPlanConfig = function({subscription, customer, plan}, callback, logger){
chargebee.plan.list().request(function(error,result){
if(error){
callback(error, null);
}
else {
let selectedPlans = result.list.map((p)=> p.plan).filter(p => p.charge_model =="per_unit");
let seats = subscription.cf_seats;
let output ={};
output.items =[];
selectedPlans.forEach(p =>{
let entry ={
plan_id: p.id
}
if(p.charge_model =="per_unit"&& seats){
entry["meta_data"]={
quantity_meta:{
type:"range",
min: seats,
max:100,
step:1
}
}
}
output.items.push(entry);
});
callback(null, output);
}
});
}Sample output
{
"items":[{
"plan_id":"plan3",
"meta_data":{
"quantity_meta":{
"type":"range",
"min":5,
"max":100,
"step":1
}
}
},{
"plan_id":"basic",
"meta_data":{
"quantity_meta":{
"type":"range",
"min":5,
"max":100,
"step":1
}
}
},{
"plan_id":"no-trial",
"meta_data":{
"quantity_meta":{
"type":"range",
"min":5,
"max":100,
"step":1
}
}
},{
"plan_id":"plan1",
"meta_data":{
"quantity_meta":{
"type":"range",
"min":5,
"max":100,
"step":1
}
}
},{
"plan_id":"professional",
"meta_data":{
"quantity_meta":{
"type":"range",
"min":5,
"max":100,
"step":1
}
}
},{
"plan_id":"plan2",
"meta_data":{
"quantity_meta":{
"type":"range",
"min":5,
"max":100,
"step":1
}
}
}]
}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",
"additionalProperties": false,
"properties":{
"type":{
"type":"string",
"enum":["range"]
},
"min":{
"type":"number"
},
"max":{
"type":"number"
},
"step":{
"type":"number"
}
},
"required":["type","min","max"]
},
"addon":{
"additionalProperties": false,
"type":"object",
"required":["id"],
"properties":{
"id":{
"type":"string",
"examples":[
"sms_credits"
]
},
"meta_data":{
"additionalProperties": false,
"type":"object",
"properties":{
"quantity_meta":{
"oneOf":[{
"$ref":"#/definitions/range_quantity_meta"
},{
"$ref":"#/definitions/fixed_quantity_meta"
}]
}
}
}
}
},
"fixed_quantity_meta":{
"type":"object",
"additionalProperties": false,
"properties":{
"type":{
"type":"string",
"enum":["fixed"]
},
"values":{
"type":"array",
"items":{
"type":"number"
}
}
},
"required":["type","values"]
}
},
"properties":{
"items":{
"type":"array",
"items":{
"$id":"/properties/product-item",
"type":"object","additionalProperties": false,
"required":["plan_id"],
"properties":{
"plan_id":{
"type":"string",
"examples":["professional"]
},
"allowed_addons":{
"type":"array",
"items":{
"$ref":"#/definitions/addon"
}
},
"meta_data":{
"type":"object",
"additionalProperties": false,
"properties":{
"quantity_meta":{
"oneOf":[{
"$ref":"#/definitions/range_quantity_meta"
},{
"$ref":"#/definitions/fixed_quantity_meta"
}]
}
}
},
"addons":{
"type":"array",
"items":{
"$ref":"#/definitions/addon"
}
}
}
}
},
"allowed_addons":{
"type":"array",
"items":{
"$ref":"#/definitions/addon"
}
},
"use_existing_addons":{
"type":"boolean",
"default": false,
"examples":[ true]
}
},
"additionalProperties": false
}Was this article helpful?