Cancel Page Quickstart

Chargebee Cancel Pages help you retain customers by intercepting cancel flows and presenting alternatives such as discounts, plan changes, or feedback forms. This guide walks through integrating them into your application with the Chargebee.js SDK.

1. Prerequisites

Set up cancel pages in Chargebee.

2. Load Chargebee.js

Add the following script to the <head> element of the page that contains the cancel button for the subscription.

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

3. Initialize Chargebee.js

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

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

4. Create the Cancel Page object

Use the cancelPage() function to instantiate Cancel Page.

const cancelPage = await chargebee.cancelPage();

5. Choose your integration approach

You can implement the cancel page in one of two ways:

Attach a cancellation handler. Replace an existing cancel link with almost no code.
Prefetch and redirect. Run custom logic before redirecting — analytics, dialogs, feature flags — or trigger cancellation from more than one place in your application.

Set the id of the cancellation CTA to cb-cancel

Define a cancellation CTA in your application with the id set to cb-cancel. This must be a link that the user clicks to cancel their subscription.

Required step

The integration does not work without this id.

<a id="cb-cancel" href="https://app.yourcompany.com/cancel" class="btn btn-danger">
  Cancel Subscription
</a>

Connect the cancel page URL to the CTA

Call the cancelPage.attachCancelHandler() function as soon as the cancellation CTA is displayed to the user. This attaches a click handler to the cb-cancel CTA and initializes the cancel page flow.

cancelPage.attachCancelHandler({
  account: {
    firstPurchaseDate: "2024-06-26"
  },
  subscription: {
    id: "16CRibUdE6pV6HoU"
  },
  externalUserId: "jane_doe",
  firstName: "Jane",
  lastName: "Doe",
  locale: "fr-FR",
  saveReturnUrl: "https://app.yourcompany.com/save?id=jane_doe",
  cancelConfirmationUrl: "https://app.yourcompany.com/cancel_confirm?id=jane_doe",
  custom: {
    emailCount: 4208
  }
});

Your application is now wired up to deflect cancellation attempts. When the customer clicks the cancellation link, they are redirected to a personalized cancel page hosted by Chargebee.

Set the parameters for the cancel page

let options = {
  account: {
    firstPurchaseDate: "2024-06-26"
  },
  subscription: {
    id: "16CRibUdE6pV6HoU"
  },
  externalUserId: "jane_doe",
  firstName: "Jane",
  lastName: "Doe",
  locale: "fr-FR",
  saveReturnUrl: "https://app.yourcompany.com/save?id=jane_doe",
  cancelConfirmationUrl: "https://app.yourcompany.com/cancel_confirm?id=jane_doe",
  custom: {
    emailCount: 4208
  }
}

Write a helper to handle clicks on the cancellation CTA

function bindLink(id, url) {
    document.getElementById(id).addEventListener('click', () => {
        window.location.assign(url);
    });
}

Prefetch the cancel page and prepare for redirection

Call the cancelPage.getPage() function as soon as the cancellation CTA is displayed. Prefetching reduces latency so the cancel page loads promptly when the user decides to cancel.

Use the helper above to bind the click event to the CTA. If the page is valid, redirect to the Chargebee cancel page URL; otherwise, redirect to a fallback cancellation page.

cancelPage
  .getPage(options)
  .then((result) => {
    if (result.valid) {
      // Do any additional processing here.
      bindLink('cancel-btn', result.url);
    } else {
      // Read and process result.errorMessage or redirect to cancellation page:
      bindLink(
        'cancel-btn',
        'https://app.yourcompany.com/cancel?id=jane_doe'
      );
    }
  });

Your application is now wired up to deflect cancellation attempts. When the customer clicks the cancellation CTA, they are redirected to a personalized cancel page hosted by Chargebee.

Best practices

Local development

For security reasons, Chargebee does not respond to cancel page API requests from localhost. For local development, temporarily map a domain to your localhost to verify the XHR request, or use a tunnel service such as ngrok or localtunnel. Watch the network tab in your browser's developer tools to diagnose any remaining issues.

Render within iframes

You can embed the Chargebee cancel page in your application using an iframe. To do so securely, configure a vanity domain that matches your website's domain. If your app runs at https://app.yourcompany.com, the iframe must load from a domain such as https://cancel.yourcompany.com. Domains like yourcompany.chargebee.com cannot be embedded in an iframe because of cross-origin restrictions.

Next steps

Cancel Page reference for the full parameter list and remaining methods.
Migrate Cancel Pages from Brightback.js if you have an existing Retention integration.