# Fetch Allowed Plan Configuration
# Overview
Use the fetchAllowedPlanConfig function to control the plans and addons a customer can select when they change their subscription via the 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.
# 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 (opens new window).
- 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.
# Parameters
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.
items[].allowed_addons property.true, the existing addons on the subscription are auto-attached to the new plan item price. Defaults to false.# 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.
- js
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" }
]
}
]
}
2
3
4
5
6
7
8
9
10
11
12
13
# 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 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
}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
Legacy Product Catalog
For Legacy Product Catalog (opens new window), see this guide.
← Custom code Use cases →
