# Cancel Page Object

A Cancel Page instance is used to control and integrate [cancel pages][cancel-pages-user-docs] during subscription cancellation flows.

[Create a `cancelPage` object](https://www.chargebee.com/docs/js/cbinstanceobj-api-ref#cancelpage) using the `chargebee` object to use the functions listed below.

> **Previous Version**
>
> The earlier version of Cancel Page was delivered via Brightback.js, which has since been deprecated. See [Migrate Cancel Pages from Brightback.js](https://www.chargebee.com/tutorials/cancel-page-migration-guide/). You can still view the [legacy documentation][cancel-pages-legacy-docs] for reference.

## Tutorials

For step-by-step integration, see the [Cancel Pages tutorials](https://www.chargebee.com/tutorials/topics/cancel-pages/).

## Attach the cancellation handler

### `attachCancelHandler()`

Attaches a click handler to the `cb‑cancel` element to initialize the cancel page flow.

> **DOM element required**
>
> There must be a DOM element with the `id` `cb‑cancel` on the page for this function to work. This element is typically an anchor element (`<a>`) with an `href` attribute, that initiates the cancellation flow.

### How it works

#### 1. Request the cancel page URL

Sends `options` to Chargebee and stores the returned cancel page URL.

#### 2. Attach the click handler

1. Finds the DOM element with the id `cb‑cancel`.
2. Registers a `click` listener that:
   - Redirects to the cancel page URL, if one was obtained and stored in the previous step.
   - Otherwise, as a fallback, redirects to the element's `href` value, if present.

### Example

```js
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
  }
});
```

### Parameters

- `account` (Object) Details about the customer.
  - `customerId` (String) The unique ID of the customer in Chargebee Billing.
  - `companyName` (String) The name of the customer's company or organization. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
  - `companyDomain` (String) The domain name of the customer's company or organization. For example: `example.com`. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
  - `firstPurchaseDate` (Date) The date when the customer made the first ever purchase. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
  - `contractValue` (Decimal) The revenue number associated with the customer. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
- `subscription` (Object, required) Details about the specific subscription of the customer.
  - `id` (String, required) The unique ID of the subscription in Chargebee Billing.
  - `plan` (String) The name or category of the subscription plan. For example: `enterprise`, `freemium`. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
  - `planTerm` (String) The billing frequency of the subscription plan. For example: `weekly`, `monthly`, `yearly`. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
- `firstName` (String) The first name of the logged-in user. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
- `lastName` (String) The last name of the logged-in user. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
- `fullName` (String) The full name of the logged-in user. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
- `email` (String) The email address of the logged-in user or the organization's primary contact. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
- `externalUserId` (String) The logged-in user's unique ID in your system. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
- `saveReturnUrl` (String) The URL to redirect the user to after they click Never mind.
- `cancelConfirmationUrl` (String) The URL to redirect the user to when they click the cancel CTA.
- `locale` (String) The user's locale (for example, `en-US`, `fr-FR`). Chargebee matches this value against the language matching rules configured in the Chargebee Growth dashboard and displays the cancel page in the matching language. If you omit this parameter, Chargebee matches the browser language instead. If no rule matches, Chargebee displays the cancel page in your site's primary language, which is English. Requires multi-language support; contact the Chargebee Support to enable it for your site. Until then, Chargebee ignores this parameter. To configure languages, add each language and its matching rules under Settings > Languages in the Chargebee Growth dashboard, then add the translated content for each language while setting up cancel pages.
- `custom` (Object) An object containing one or more custom fields defined in the Chargebee Retention dashboard dashboard. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.

### Returns

None.

## Get a cancel page

### `getPage()`

Requests a cancel page URL from Chargebee.

This function sends `options` to Chargebee and the returned [promise](https://developer.mozilla.org/en-US/docs/Glossary/Promise) resolves with the URL of the cancel page.

### Example

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

cancelPage.getPage({
  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
  }
}).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');
  }
});
```

### Parameters

- `account` (Object) Details about the customer.
  - `customerId` (String) The unique ID of the customer in Chargebee Billing.
  - `companyName` (String) The name of the customer's company or organization. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
  - `companyDomain` (String) The domain name of the customer's company or organization. For example: `example.com`. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
  - `firstPurchaseDate` (Date) The date when the customer made the first ever purchase. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
  - `contractValue` (Decimal) The revenue number associated with the customer. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
- `subscription` (Object, required) Details about the specific subscription of the customer.
  - `id` (String, required) The unique ID of the subscription in Chargebee Billing.
  - `plan` (String) The name or category of the subscription plan. For example: `enterprise`, `freemium`. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
  - `planTerm` (String) The billing frequency of the subscription plan. For example: `weekly`, `monthly`, `yearly`. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
- `firstName` (String) The first name of the logged-in user. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
- `lastName` (String) The last name of the logged-in user. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
- `fullName` (String) The full name of the logged-in user. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
- `email` (String) The email address of the logged-in user or the organization's primary contact. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
- `externalUserId` (String) The logged-in user's unique ID in your system. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.
- `saveReturnUrl` (String) The URL to redirect the user to after they click Never mind.
- `cancelConfirmationUrl` (String) The URL to redirect the user to when they click the cancel CTA.
- `locale` (String) The user's locale (for example, `en-US`, `fr-FR`). Chargebee matches this value against the language matching rules configured in the Chargebee Growth dashboard and displays the cancel page in the matching language. If you omit this parameter, Chargebee matches the browser language instead. If no rule matches, Chargebee displays the cancel page in your site's primary language, which is English. Requires multi-language support; contact the Chargebee Support to enable it for your site. Until then, Chargebee ignores this parameter. To configure languages, add each language and its matching rules under Settings > Languages in the Chargebee Growth dashboard, then add the translated content for each language while setting up cancel pages.
- `custom` (Object) An object containing one or more custom fields defined in the Chargebee Retention dashboard dashboard. Ignored if it is not mapped to a field in the Chargebee Retention dashboard.

### Returns

A promise that resolves to an object with the following properties:

- `valid` (Boolean) `true`: Indicates that the cancel page was successfully generated. See `url`.`false`: Indicates that the cancel page was not generated. See `errorMessage`.
- `url` (String) The URL of the generated cancel page. Returned only when `valid` is `true`.
- `errorMessage` (String) A message describing the reason why the cancel page failed to be generated. Returned only when `valid` is `false`.

[cancel-pages-user-docs]: https://www.chargebee.com/docs/growth/experiences/cancel-pages
[cancel-pages-legacy-docs]: https://www.chargebee.com/docs/growth/getting-started/chargebee-growth-installation#cancel-pages-legacy-integration-brightbackjs