# Portal Object

## Overview

The Portal object provides access to Chargebee's [customer self-service portal](https://www.chargebee.com/docs/billing/2.0/hosted-capabilities/hosted-portal) functionality. This object enables you to open the complete customer portal or specific sections, allowing customers to manage their subscriptions, billing information, and account details.

## Tutorials

For a step-by-step integration, see the [self-serve portal tutorials](https://www.chargebee.com/tutorials/topics/self-serve-portal/).

## Prerequisites

Before creating the Portal object, ensure you have:

- [Enabled and configured](https://www.chargebee.com/docs/billing/2.0/hosted-capabilities/self-serve-portal) the portal in Chargebee Billing.
- [Initialized Chargebee.js](https://www.chargebee.com/docs/js/settingup-api-ref) in your application.
- [Set up a portal session](https://www.chargebee.com/docs/js/cbinstanceobj-api-ref#setportalsession-setterfunction) using `setPortalSession()`.

## Create the Portal object

To create a Portal object instance, use the [`createChargebeePortal()`](https://www.chargebee.com/docs/js/cbinstanceobj-api-ref#createchargebeeportal) method:

```js
const chargebeePortal = chargebee.createChargebeePortal();
``` 

## `open(options?, forwardOptions?)`

Opens the customer self-service portal or one of its sections in a modal or new window.

### Syntax

```js
chargebeePortal.open(options, forwardOptions);
```

### Parameters

**Parameters**

- `options` (Object)
  - `loaded` (Function) This function will be called once the portal is loaded.
  - `close` (Function) This function will be called once the portal is closed by the end user.
  - `visit` (Function) This function will be called everytime a user visits a section in the customer portal.
    - `sectionType` (String)
  - `paymentSourceAdd` (Function) This function will be called whenever a new payment source is added in portal.
    - `status` (String) Specifies whether the payment source was added successfully. Allowed: `success`, `error`.
  - `paymentSourceUpdate` (Function) This function will be called whenever a payment source is updated in portal.
    - `status` (String) Specifies whether the payment source was updated successfully. Allowed: `success`, `error`.
  - `paymentSourceRemove` (Function) This function will be called whenever a payment source is removed from portal.
  - `subscriptionChanged` (Function) This function will be called whenever a subscription is changed.
    - `data` (Object)
      - `subscription` (Object)
        - `id` (String)
  - `subscriptionCustomFieldsChanged` (Function) This function will be called whenever a subscription custom fields are changed
    - `data` (Object)
      - `subscription` (Object)
        - `id` (String)
  - `subscriptionCancelled` (Function) This function will be called when a subscription is canceled.
    - `data` (Object)
      - `subscription` (Object)
        - `id` (String)
  - `subscriptionResumed` (Function) This function will be called when a subscription is resumed.
    - `data` (Object)
      - `subscription` (Object)
        - `id` (String)
  - `subscriptionPaused` (Function) This function will be called when a subscription is paused.
    - `data` (Object)
      - `subscription` (Object)
        - `id` (String)
  - `scheduledPauseRemoved` (Function) This function will be called when a subscription that is scheduled for pause is removed.
    - `data` (Object)
      - `subscription` (Object)
        - `id` (String)
  - `scheduledCancellationRemoved` (Function) This function will be called when the schedule to cancel a subscription is removed.
    - `data` (Object)
      - `subscription` (Object)
        - `id` (String)
  - `subscriptionReactivated` (Function) This function will be called when a canceled subscription is reactivated.
    - `data` (Object)
      - `subscription` (Object)
        - `id` (String)
- `forwardOptions` (Object)
  - `sectionType` (String, required) Allowed: `All values present in Chargebee.getPortalSections()`.
  - `params` (Object)
    - `subscriptionId` (String, required if the sectionType involves a subscription related action)
    - `paymentSourceId` (String, required if the sectionType involves a payment source related action)

### Return value

This function does not return a value.

### Example

```js
const chargebee = Chargebee.getInstance();

// Set up portal session (required before creating portal).
chargebee.setPortalSession(() => {
  // Return a promise that resolves to portal session data.
  return new Promise(function(resolve, reject) {
    // Example portal session response from your server.
    const portalSessionResponse = {
      "id": "portal_XpbGElGQgEHspHB",
      "token": "<portal-session-token>",
      "access_url": "https://yourapp.chargebeeportal.com/portal/access/<portal-session-token>",
      "status": "created",
      "created_at": 1515494835,
      "expires_at": 1515498435,
      "object": "portal_session",
      "customer_id": "XpbGEt7QgEHsnL7O"
    };
    resolve(portalSessionResponse);
  });
});

// Create and open the portal.
const chargebeePortal = chargebee.createChargebeePortal();
chargebeePortal.open({
  loaded: function() {
    console.log("Portal loaded.");
  },
  close: function() {
    console.log("Portal closed.");
  }
});
```

## `openSection(options, callbacks?)`

Opens a specific section of the customer portal instead of the complete portal.

### Available section types

You can open the following section types as separate cards:

- `SUBSCRIPTION_DETAILS` - View and manage subscription information.
- `ACCOUNT_DETAILS` - Update customer account information.
- `ADDRESS` - Manage billing and shipping addresses.
- `PAYMENT_SOURCES` - Add, update, or remove payment methods.
- `BILLING_HISTORY` - View past invoices and payment history.

### Live demo

Each section opens as its own card. Try them against the demo site below.

- View / edit subscription details - 
- Manage payment methods - 
- Billing history - 
- Manage addresses - 
- Manage account information - 

### Syntax

```js
chargebeePortal.openSection(options, callbacks)
```

### Parameters

**Parameters**

- `options` (Object)
  - `sectionType` (String)
  - `params` (Object)
    - `subscriptionId` (String, required if the sectionType involves a subscription)
- `callbacks` (Object)
  - `loaded` (Function) This function will be called once the portal is loaded.
  - `close` (Function) This function will be called once the portal is closed by the end user.
  - `visit` (Function) This function will be called everytime an user visits a section in the customer portal.
    - `sectionType` (String)
  - `paymentSourceAdd` (Function) This function will be called whenever a new payment source is added in portal.
  - `paymentSourceUpdate` (Function) This function will be called whenever a payment source is updated in portal.
  - `paymentSourceRemove` (Function) This function will be called whenever a payment source is removed from portal.
  - `subscriptionChanged` (Function) This function will be called whenever a subscription is changed.
    - `data` (Object)
      - `subscription` (Object)
        - `id` (String)
  - `subscriptionCustomFieldsChanged` (Function) This function will be called whenever a subscription custom fields are changed.
    - `data` (Object)
      - `subscription` (Object)
        - `id` (String)
  - `subscriptionCancelled` (Function) This function will be called when a subscription is canceled.
    - `data` (Object)
      - `subscription` (Object)
        - `id` (String)
  - `subscriptionResumed` (Function) This function will be called when a subscription is resumed.
    - `data` (Object)
      - `subscription` (Object)
        - `id` (String)
  - `subscriptionPaused` (Function) This function will be called when a subscription is paused.
    - `data` (Object)
      - `subscription` (Object)
        - `id` (String)
  - `scheduledPauseRemoved` (Function) This function will be called when a subscription that is scheduled for pause is removed.
    - `data` (Object)
      - `subscription` (Object)
        - `id` (String)
  - `scheduledCancellationRemoved` (Function) This function will be called when the schedule to cancel a subscription is removed.
    - `data` (Object)
      - `subscription` (Object)
        - `id` (String)
  - `subscriptionReactivated` (Function) This function will be called when a canceled subscription is reactivated.
    - `data` (Object)
      - `subscription` (Object)
        - `id` (String)

### Return value

This function does not return a value.

### Example

```js
const chargebee = Chargebee.getInstance();

// Set up portal session (required before creating portal).
chargebee.setPortalSession(() => {
  // Return a promise that resolves to portal session data.
  return new Promise(function(resolve, reject) {
    // Example portal session response from your server.
    const portalSessionResponse = {
      "id": "portal_XpbGElGQgEHspHB",
      "token": "<portal-session-token>",
      "access_url": "https://yourapp.chargebeeportal.com/portal/access/<portal-session-token>",
      "status": "created",
      "created_at": 1515494835,
      "expires_at": 1515498435,
      "object": "portal_session",
      "customer_id": "XpbGEt7QgEHsnL7O"
    };
    resolve(portalSessionResponse);
  });
});

// Create and open the portal.
const chargebeePortal = chargebee.createChargebeePortal();

// Open a specific section
chargebeePortal.openSection({
  sectionType: Chargebee.getPortalSections().ACCOUNT_DETAILS
}, {
  loaded: () => {
    console.log('Account details section loaded.');
  },
  close: () => {
    console.log('Account details section closed.');
  }
});
```