chargebee js

Pricing Table Object

A Pricing Table instance is used to create dynamic, low-code pricing table that are always up-to-date with your latest product catalog information.

Pricing table is rendered on <div> elements with the id set to chargebee-pricing-table.

Create a pricingTable object using the chargebee object to use the functions listed below.

Tutorials

For a step-by-step integration, see the Pricing Tables tutorials.

Render a static pricing table

init()

Initializes and renders the pricing table based on static configuration attributes set on the pricing page <div>. You must set data-pricing-table-key on the <div>.

Examples

Render a pricing table

<div
  id="chargebee-pricing-table"
  data-pricing-table-key="YOUR-PRICING-TABLE-ID"
></div>
pricingTable.init();

Handle plan CTA clicks

<div
  id="chargebee-pricing-table"
  data-pricing-table-key="YOUR-PRICING-TABLE-ID"
></div>
pricingTable.init({
  onCtaClick: (payload) => {
    console.log('The visitor selected', payload.ctaConfig.billingSystemItemPriceId);
  },
});

Parameters

data
Object
Configuration for the pricing tables being rendered.

Returns

None.

Render a pricing table session

open()

Renders the pricing table using a pricing_page_session object. Use this function to render the pricing page using session context for a returning customer. The pricing table is only rendered at the <div> where data-pricing-table-integration-type = api is set.

Examples

Render a pricing table session

<div
  id="chargebee-pricing-table"
  data-pricing-table-integration-type="api"
></div>
pricingTable.open({
  pricingTable: function() {
    return fetch('https://YOUR_DOMAIN/create_pricing_table', {
      method: "POST",
      headers: {
        "Content-Type": "application/json"
      },
      body: JSON.stringify(data)
    }).then(response => response.json());
  },
});

Handle plan CTA clicks

<div
  id="chargebee-pricing-table"
  data-pricing-table-integration-type="api"
></div>
pricingTable.open({
  pricingTable: function() {
    return fetch('https://YOUR_DOMAIN/create_pricing_table', {
      method: "POST",
      headers: {
        "Content-Type": "application/json"
      },
      body: JSON.stringify(data)
    }).then(response => response.json());
  },
  onCtaClick: (payload) => {
    console.log('The visitor selected', payload.ctaConfig.billingSystemItemPriceId);
  },
});

Parameters

data
required, Object

Returns

None.

Handle plan CTA clicks in JavaScript

onCtaClick() callback

A callback function that is called when a visitor clicks a call-to-action (CTA) for a plan that is configured for a JavaScript callback. Use this callback when your application creates the subscription itself, or when the visitor must complete a step outside the pricing page before they can subscribe.

Pass the function to init() or open(). When a visitor clicks a plan CTA that is configured for a JavaScript callback, the pricing table calls your function with a payload describing the selected plan, and does nothing else. Your application decides what happens next.

After a visitor clicks the CTA, the pricing table disables it for a few seconds to prevent duplicate clicks. Because the pricing table shows no progress of its own, use showLoader() to tell the visitor what your application is doing.

If your function throws an error, or returns a promise that rejects, Chargebee logs the error and the pricing page continues to run. Handle errors within the function to show the visitor what went wrong.

Example

The following example shows a loader while the application creates a subscription. It sends the visitor to a confirmation page when the request succeeds, and hides the loader whether the request succeeds or fails.

async function handleCtaClick(payload) {
  pricingTable.showLoader({
    header: 'Setting things up',
    subheader: 'This will just take a moment...',
  });

  try {
    const response = await fetch('https://YOUR_DOMAIN/create_subscription', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        itemPriceId: payload.ctaConfig.billingSystemItemPriceId,
        quantity: payload.ctaConfig.quantity,
      }),
    });

    if (!response.ok) {
      throw new Error(`Response status: ${response.status}`);
    }

    window.location.href = 'https://YOUR_DOMAIN/welcome';
  } catch (error) {
    console.error('Could not create the subscription:', error);
    // Show an error message from your own application.
  } finally {
    pricingTable.showLoader(false);
  }
}

pricingTable.init({
  onCtaClick: handleCtaClick,
});

Parameters

payload
required, Object
Details of the plan the visitor selected and the context in which they selected it.

Returns

Chargebee ignores the value that your function returns.

Show a loader

showLoader()

Shows or hides a loader that covers the pricing page, with optional text. Use this function to report progress while your onCtaClick() function runs.

The loader has no timeout. It stays visible until you hide it, so hide it explicitly using showLoader(false) when your processing finishes or fails.

Examples

Show the loader without text

pricingTable.showLoader(true);

Show the loader with text

pricingTable.showLoader({
  header: 'Almost done',
  subheader: 'This will take a moment...',
});

Hide the loader

pricingTable.showLoader(false);

Parameters

data
Object
Whether to show the loader, and the text to display on it. Pass true to show the loader without text, or an object to show it with text. Pass false or null, or omit this parameter, to hide the loader. Default value is false.
options
Object
Identifies the pricing table to target. Omit this parameter to target every pricing table on the web page.

Returns

None.

Set visitor information

setVisitor()

Sets customer-related parameters to be passed to Chargebee Checkout or included in the redirect URL from the pricing table.

How these parameters are used depends on the Button Text & Behavior setting for the pricing table:

  • Open Checkout: These parameters are passed to Checkout and used to populate the new customer record in Chargebee Billing. Note: This does not update existing customer records. To update a customer, use the Update a customer API.
  • Redirect to URL: The parameters are added to the query string of the redirect URL, provided the redirect URL template includes corresponding placeholder variables.
  • Trigger JS Callback: The parameters are not included in the onCtaClick() payload. Read them from your own application instead.

Examples

Set customer details for all pricing pages

const data = {
  firstName: 'Jane',
  lastName: 'Doe',
  email: 'jane.doe@example.com',
  phone: '+1-123-456-7890',
  company: 'Acme',
  customFields: {
    cf_visit_count: 13,
  },
};

pricingTable.setVisitor(data);

Set customer details for a specific pricing page

const data = {
  firstName: 'Jane',
  lastName: 'Doe',
  email: 'jane.doe@example.com',
  phone: '+1-123-456-7890',
  company: 'Acme',
  customFields: {
    cf_visit_count: 13,
  },
};
const options = {
  pricingPageKey: 'BpQVReCOGP',
};

pricingTable.setVisitor(data,options);

Parameters

data
required, Object
Customer-related parameters.
options
Object
Identifies the pricing table to target. Omit this parameter to target every pricing table on the web page.

Returns

None.

Set billing address

setBillingAddress()

Sets customer billing address parameters to be passed to Chargebee Checkout or included in the redirect URL from the pricing table.

How these parameters are used depends on the Button Text & Behavior setting for the pricing table:

  • Open Checkout: These parameters are passed to Checkout and used to populate the billing address for the new customer record in Chargebee Billing. Note: This does not update existing customer records. To update a customer’s billing address, use the Update billing info for a customer API.
  • Redirect to URL: The parameters are added to the query string of the redirect URL, provided the redirect URL template includes corresponding placeholder variables.

Examples

Set billing address for all pricing pages

const data = {
  firstName: 'Jane',
  lastName: 'Doe',
  email: 'jane.doe@gmail.com',
  phone: '+1-123-456-7890',
  company: 'Acme',
  city: 'Los Angeles',
  stateCode: 'CA',
  country: 'US',
};

pricingTable.setBillingAddress(data);

Set billing address for a specific pricing page

const data = {
  firstName: 'Jane',
  lastName: 'Doe',
  email: 'jane.doe@gmail.com',
  phone: '+1-123-456-7890',
  company: 'Acme',
  city: 'Los Angeles',
  stateCode: 'CA',
  country: 'US',
};

const options = {
  pricingPageKey: 'BpQVReCOGP',
};

pricingTable.setBillingAddress(data,options);

Parameters

data
required, Object
Customer billing address parameters.
options
Object
Identifies the pricing table to target. Omit this parameter to target every pricing table on the web page.

Returns

None.

setShippingAddress(shippingAddress)

Sets subscription shipping address parameters to be passed to Chargebee Checkout or included in the redirect URL from the pricing table.

How these parameters are used depends on the Button Text & Behavior setting for the pricing table:

  • Open Checkout: These parameters are passed to Checkout and used to populate the shipping address of the new subscription record in Chargebee Billing. Note: This does not update existing subscription records. To update a subscription’s shipping address, use the Update a subscription API.
  • Redirect to URL: The parameters are added to the query string of the redirect URL, provided the redirect URL template includes corresponding placeholder variables.

Examples

Set shipping address for all pricing pages

const data = {
  firstName: 'Jane',
  lastName: 'Doe',
  email: 'jane.doe@gmail.com',
  phone: '+1-123-456-7890',
  company: 'Acme',
  city: 'Los Angeles',
  stateCode: 'CA',
  country: 'US',
};

pricingTable.setShippingAddress(data);

Set shipping address for a specific pricing page

const data = {
  firstName: 'Jane',
  lastName: 'Doe',
  email: 'jane.doe@gmail.com',
  phone: '+1-123-456-7890',
  company: 'Acme',
  city: 'Los Angeles',
  stateCode: 'CA',
  country: 'US',
};

const options = {
  pricingPageKey: 'BpQVReCOGP',
};

pricingTable.setShippingAddress(data,options);

Parameters

data
required, Object
Customer billing address parameters.
options
Object
Identifies the pricing table to target. Omit this parameter to target every pricing table on the web page.

Returns

None.

Set quantity

setQuantity()

Sets the initial quantity for all quantity-based plans on the pricing table.

Enable the quantity slider to allow users to change the quantity value.

Examples

Set quantity for all pricing pages

pricingTable.setQuantity(10);

Set quantity for a specific pricing page

const quantity = 10;
const options = {
  pricingPageKey: 'BpQVReCOGP',
};

pricingTable.setQuantity(quantity,options);

Parameters

quantity
required, Number
The quantity to be set for plans on the pricing table.
options
Object
Identifies the pricing table to target. Omit this parameter to target every pricing table on the web page.

Returns

None.

Set business entity

setBusinessEntity()

Sets the business entity to use for creating customer and subscription records in Chargebee Billing. If a business entity was set when creating the Chargebee object, this method overrides it.

Examples

Set business entity for all pricing pages

pricingTable.setBusinessEntity('acme-eu');

Set business entity for a specific pricing page

const businessEntityId = 'acme-eu';
const options = {
  pricingPageKey: 'BpQVReCOGP',
};

pricingTable.setBusinessEntity(businessEntityId,options);

Parameters

businessEntityId
required, String
The unique ID of the business entity.
options
Object
Identifies the pricing table to target. Omit this parameter to target every pricing table on the web page.

Returns

None.

Set price variant

setPriceVariant()

Sets the price variant for the plans displayed on the pricing page. If the specified price variant is not available for a plan, the default price variant of the plan is used. If no default price variant exists, the plan is not displayed on the pricing page.

Examples

Set a price variant for a static pricing table

pricingTable.setPriceVariant('size-m');
pricingTable.init();

Set a price variant for a specific pricing page

const priceVariantId = 'size-m';
const options = {
  pricingPageKey: 'BpQVReCOGP',
};

pricingTable.setPriceVariant(priceVariantId, options);
pricingTable.init();

Set a price variant for a pricing table session

pricingTable.setPriceVariant('size-m');

pricingTable.open({
  pricingTable: function() {
    return fetch('https://YOUR_DOMAIN/create_pricing_table', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(data),
    }).then(response => response.json());
  },
});

Parameters

priceVariantId
required, String
The unique ID of the price variant.
options
Object
Identifies the pricing table to target. Omit this parameter to target every pricing table on the web page.

Returns

None.

Set subscription attributes

setSubscriptionAttributes()

Sets subscription-level custom fields to be passed to Chargebee Checkout or included in the redirect URL from the pricing table.

How these parameters are used depends on the Button Text & Behavior setting for the pricing table:

  • Open Checkout: These parameters are passed to Checkout and used to populate the new subscription record in Chargebee Billing. Note: This does not update existing subscription records. To update a subscription’s custom fields, use the Update a subscription API.
  • Redirect to URL: The parameters are added to the query string of the redirect URL, provided the redirect URL template includes corresponding placeholder variables.

Examples

Set subscription fields for all pricing pages

const data = {
  customFields: {
    cf_campaign_id: 'monsoon98',
  },
}

pricingTable.setSubscriptionAttributes(data);

Set subscription fields for a specific pricing page

const data = {
  customFields: {
    cf_campaign_id: 'monsoon98',
  },
}

const options = {
  pricingPageKey: 'BpQVReCOGP',
};

pricingTable.setSubscriptionAttributes(data,options);

Parameters

data
required, Object
options
Object
Identifies the pricing table to target. Omit this parameter to target every pricing table on the web page.

Returns

None.

Show total price

showTotalPrice()

Displays the total price payable for the selected plan(s) when the Show price per month feature is enabled for the pricing table.

For example, if you have a 3-month plan priced at $90 with Show price per month enabled, the Pricing Table displays "$30/month". With showTotalPrice(), you can also display the total price ($90) alongside the monthly price.

Examples

The following screenshot shows how the total price is displayed on a sample pricing table.

The following code snippets implement the feature shown in the image above.

Show total price for all pricing pages

const data = [
  {
    prefix: "Total quarterly price is",
    periodUnit: "month",
    period: 3,
    suffix: "only"
  },
  {
    periodUnit: "year",
    period: 1,
    prefix: "Total Price"
  }
];

pricingTable.showTotalPrice(data);

Show total price for a specific pricing page

const data = [
  {
    prefix: "Total quarterly price is",
    periodUnit: "month",
    period: 3,
    suffix: "only"
  },
  {
    periodUnit: "year",
    period: 1,
    prefix: "Total Price"
  }
];

const options = {
  pricingPageKey: 'BpQVReCOGP',
};

pricingTable.showTotalPrice(data,options);

Parameters

Returns

None.

Data attributes

The following data-* attributes can be set on the pricing table <div>.

data-pricing-table-key

Required when data-pricing-table-integration-type is not set and when calling pricingTable.init(). Specifies the unique ID of your pricing table. To find this ID, see the documentation.

Do not set this attribute when data-pricing-table-integration-type = 'api', or the SDK will return an error.

data-pricing-table-viewport-width

Sets the maximum width of the pricing table. Accepts the following CSS units: px, em, rem, or % (for example, 100%). If not set, the pricing table uses the width of its containing element.

data-pricing-table-viewport-height

Sets the maximum height of the pricing table. Accepts the following CSS units: px, em, rem, or % (for example, 100%). If the content exceeds the height, a scrollbar appears; hence setting this attribute is not recommended. If not set, the pricing table uses the height of its containing element.

data-pricing-table-viewport-default-height

(Default value: 600px) Sets the height of the loading screen shown until the pricing page fully loads. Adjust this value based on expected screen sizes.

data-pricing-table-currency

Specifies the currency to display on the pricing table (for example, USD). If not set or if set to an invalid value, the first currency listed in the pricing table configuration page is used.

data-pricing-table-period

Specifies the number of time intervals that make up a billing cycle of the plans to be displayed. Used together with data-pricing-table-period-unit. For example, to display plans with six-month billing cycles, set data-pricing-table-period to 6 and data-pricing-table-period-unit to 'month'. When not set or set to an invalid value, the first period listed in the pricing table configuration page is selected.

data-pricing-table-period-unit

Specifies the unit of time for the billing cycle of the plans to be displayed. Used with data-pricing-table-period. Valid values are week, month, and year. When not set or set to an invalid value, the first unit listed in the pricing table configuration page is selected.

data-pricing-table-show-currency-dropdown

(Default: true) Specifies whether to show the currency selector dropdown on the pricing table.

data-pricing-table-auto-select-local-currency

(Default: false)

  • If set to true: Automatically sets a currency based on the visitor's location. For example, users in the US will see USD if available, and users in India will see INR if available. If the locale-specific currency is not available, the first currency listed in the pricing table configuration page is used.
  • When false, not set, or set to an invalid value: The first currency listed in the pricing table configuration page is used.

data-pricing-table-integration-type

Set to api to render the pricing table using pricingTable.open(). Do not set data-pricing-table-key when using this attribute; the session identifies the pricing table. Do not set this attribute on <div> elements where you want to render using pricingTable.init().

data-pricing-table-gtm-id

Sets the Google Tag Manager ID (format: GTM-xxxxx) for the pricing table and, if applicable, the Checkout pages.