Frontend Capabilities

# Retrieve Subscription Change Timeline

# Overview

Use the fetchChangeSubscriptionOptions function to control when a subscription change made in the Portal takes effect: either immediately or at the end of the current term. Chargebee invokes this function when a customer changes their subscription and uses the value you return to schedule the change.

# Usage and invocation

Write your business logic to classify each subscription change, and return end_of_term to tell Chargebee when to apply it:

  • Set end_of_term to false to apply the change immediately.
  • Set end_of_term to true to apply the change at the end of the term.

Example

Apply upgrades immediately so the customer gets the added value right away, and defer downgrades to the end of the term so the customer keeps what they paid for until the term ends.

Multi-decimal quantities

If multi-decimal support (opens new window) is enabled for your site, read the plan quantity from subscription_changes.plan_quantity_in_decimal and each addon quantity from subscription_changes.addons[].quantity_in_decimal. On these sites, the portal sends the quantity in the *_in_decimal fields, and plan_quantity is null. Custom code that reads plan_quantity receives null and applies the change incorrectly.

These *_in_decimal fields are strings, so wrap them in Number(...) before you compare them.

# 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

data
Object View properties
The resources that Chargebee passes to your custom code.
callback
Function
Function to send the output of the custom code to Chargebee.
Arguments - View
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.

# Example

This function treats a change as a downgrade when the customer reduces the quantity of the current plan or moves to a lower-priced plan, and defers those downgrades to the end of the term. All other changes apply immediately.

  • js
Sample output 
{
  "end_of_term": true
}
1
2
3

# Apply upgrades immediately and downgrades at the end of the term

The basic example inspects the plan only. This version also treats a change as a downgrade when the customer reduces an addon quantity or removes an addon. Any of these changes is deferred to the end of the term; otherwise, the change applies immediately. Use this approach when your subscriptions include quantity-based addons.

Custom code 
let chargebee = require("chargebee");

exports.fetchChangeSubscriptionOptions = function ({ subscription, subscription_changes, item_prices }, callback, logger) {

    try {

        // On multi-decimal sites, quantities are in the *_in_decimal fields; fall back to the integer fields otherwise.
        const qty = (item) => Number(item.quantity_in_decimal || item.quantity);

        // Current plan item on the subscription.
        const subPlanItemPrice = subscription.subscription_items.find(subItem => subItem.item_type === 'plan');
        // Addons currently on the subscription.
        const addonsBefore = subscription.subscription_items.filter(item => item.item_type === 'addon');
        // Addons selected in the change.
        const addonsAfter = subscription_changes.addons || [];

        let downgrade = false;

        // Same plan, quantity reduced.
        if (Number(subscription_changes.plan_quantity_in_decimal || subscription_changes.plan_quantity) < qty(subPlanItemPrice)) {
            downgrade = true;
        }

        // Any addon removed or reduced in quantity.
        for (const before of addonsBefore) {
            const after = addonsAfter.find(a => a.id === before.item_price_id);

            if (!after || qty(after) < qty(before)) {
                downgrade = true;
                break;
            }
        }

        callback(null, { end_of_term: downgrade });
    } catch (err) {
        callback(err);
    }

}
1
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
Sample output 
{
  "end_of_term": true
}
1
2
3

# 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": {},
  "properties": {
    "end_of_term": {
      "type": "boolean",
      "default": false,
      "examples": [
        true
      ]
    }
  },
  "additionalProperties": false
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Legacy Product Catalog

For Legacy Product Catalog (opens new window), see this guide.

← Set up Chargebee.js →