Frontend Capabilities

# Personalized Offers ✨

Early Access

The Personalized Offers feature is in early access. To request access, write to eap@chargebee.com.

Previous Version

The earlier version of Personalized Offers was delivered via Retention.js, which has since been deprecated. You can still view the documentation (opens new window) for reference.

# Introduction

Personalized Offers (opens new window) enable contextual upselling by displaying dynamic upgrade suggestions based on customer behavior, subscription data, and targeting rules. You can initialize the experience by passing customer and subscription identifiers into the Chargebee JavaScript SDK. The offers returned include predefined content blocks and call-to-action options that trigger billing updates, hosted checkouts, or redirects. Engagement events such as views and dismissals are also tracked to refine your targeting strategies.

# Integration guide

Follow the steps below to set up Personalized Offers using the Chargebee.js SDK.

# Prerequisites

Before integrating the SDK, you must define the offers to be displayed. Create and activate plays (opens new window) in the Chargebee Retention dashboard (opens new window). Each play you create must be activated to be available for display in your application.

Plays determine:

  • When and to whom the offer is shown (targeting and triggers).
  • What the offer looks like (offer content and widget display).
  • The actions a user can take in response.

# Integrate Chargebee.js SDK

Site‑wide script execution

To ensure that offers can appear on any configured page, implement the following steps site-wide. Include the code in a shared location that is used across all pages.

This enables the Growth Manager to target specific pages via the dashboard.

# 1. Load Chargebee.js

Load Chargebee.js by adding the following script to the global <head>.

<script src="https://js.chargebee.com/v2/chargebee.js"></script>
1

# 2. Initialize Chargebee.js

Once the page loads, initialize Chargebee.js with your Chargebee site subdomain name to enable the use of the SDK.

const chargebee = window.Chargebee.init({
   site: "YOUR-CHARGEBEE-SUBDOMAIN",
})
1
2
3

# 3. Create the Personalized Offers object

Use the personalizedOffers() function to instantiate Personalized Offers.

const personalizedOffers = await chargebee.personalizedOffers();
1

# 4. Initialize the Personalized Offers experience

Call the init() function to register the user context and prepare the offers for display.

personalizedOffers.init({
  account: {
    customerId: "16CRibUdE6pV6HoU"
  },
  externalUserId: "jane_doe",
  firstName: "Jane",
  lastName: "Doe",
  roles: ['sales-manager'],
  custom: {
    viewCount: 6
  }
});
1
2
3
4
5
6
7
8
9
10
11
12

You're all set, no further steps are needed! Chargebee now processes the user interactions and automatically renders eligible offers on the page based on your play configuration (opens new window).

# JS API reference

See the Personalized Offers JS API reference for more details.

← Retention ✨ →