Create a portal for your customers

play icon Watch Video

A customer portal allows your customers to update their information such as their card and billing information. In addition they can view and download their invoices.
You could build your own full fledged customer portal using Chargebee's extensive api  .

Alternative options

Instead of building your own customer portal you could instead use the hosted customer portal  provided by Chargebee.

Features in the sample Self Service Portal 

The following features are supported.

  • Viewing the current subscription details such as subscribed items,billing address, shipping address
  • Editing billing and shipping addresses.
  • Adding/Updating the card using the hosted updated card page.
  • Listing the invoices and support for downloading the invoices.
  • Canceling the subscription.

Setup the Chargebee client library 

You have to download and import  the client library of our choice. Then, configure the client library with your test site and its api key.

For the tutorial, we have configured the site and the credentials in a separate properties file. When the webapp is initialized, the client library gets configured.

For the tutorial, we have configured the site credentials in config/environments/development.rb

We setup the client library in config/initializers/chargebee.rb

For the tutorial, we have configured the site credentials in Config.php


The sample does not do "real" authentication. But rather just checks if the subscription id is present in your Chargebee site and subscription id is set in the session. The assumption is once you integrate the ssp into your app/website, the customer would login into your app/website you just need to integrate your authentication into sample ssp.

Building the Profile page. 

The profile page allows the customer to see his information like subcribed items, his billing and shipping addresses etc.
We use the retrieve subscription api  that returns the customer,subscription and card details.

The result is used to display the information.

Editing account,billing and shipping addresses 

The following api are used to allow the customers to add/update their information.

We have created specific forms for each of the above information as shown below.

When the customer submits the form, we call the appropriate api


We have kept the form input names to follow the chargebee's curl parameter format (example billing_address[first_name] ). Whenever error is thrown by Chargebee API due to invalid data in a parameter, the error response contains the parameter that is invalid in the error_param attribute. The parameter name sent back follows the curl parameter format. We send the error response received from back to browser client where we are able to display the error at the appropriate position near the field.

  • php
  • Ruby
  • Java
error: function(jqXHR, textStatus, errorThrown) {
    try {
        var resp = JSON.parse(jqXHR.responseText);
        if ('error_param' in resp) {
            var errorMap = {};
            var errParam = resp.error_param;
            var errMsg = resp.error_msg;
            errorMap[errParam] = errMsg;
        } else {
            var errMsg = resp.error_msg;
    } catch (err) {
        $(".alert-danger").show().text("Error while processing your request");

Adding/Updating customers card information via hosted page 

We use the Chargebee's hosted page api  to let the customers update their card information.

Listing invoices 

The list invoices for a subscription api  is used to fetch the invoices for the subscription.

We iterate through the list, skipping the pending invoices (used when you have metered billing).

and display the important details of each invoice.

Downloading invoices as PDF 

We allow users to download the invoices using download invoice as pdf api . The api returns a secure temporary url that we can forward it to the browser to trigger automatic pdf download.

Canceling subscription. 

The customers also have the option of canceling the subscription. They can choose to cancel immediately or can cancel at the end of term. We use the cancel subscription api  to cancel the subscription.

Re-activating subscription 

Incase the subscription has been canceled we allow users to re-activate the subscription using the reactivate a subscription api. 

Validation and Error Handling

Here's how we validate user inputs and handle API call errors in this demo:

  • Client Side Validation: Chargebee uses jQuery form validation  plugin to check whether the user's field inputs(email, zip code and phone number) are valid or not.

  • Server Side Validation: As this is a demo application we have skipped the server side validation of all input parameters. But we recommend you to perform the validation at your end.

  • Payment Errors: If a payment fails due to card verification or processing errors, Chargebee returns an error response  which is thrown as a payment exception by the client library. We handle the exceptions in the demo application with appropriate error messages.

  • General API Errors: Chargebee might return error responses due to various reasons such as invalid configuration, bad request etc. To identify specific reasons for all error responses you can check the API documentation . Also take a look at the error handler file to check how these errors can be handled.