Settings
API Version
Product Catalog
Library

Portal sessions

Customer Portal lets your customers to manage their account and billing themselves. Chargebee supports Single Sign-on (SSO) to access the customer portal. If you already have your own authentication for your website, it allows your authenticated customers to access their portal without having to login again.

Note: You can instead allow your customers to access the portal via login page provided by Chargebee. Read more.

Please follow the below steps for supporting portal access via SSO:

  1. To enable the "Allow access to customer portal via API", click Settings > Configure Chargebee > Customer Facing Essentials > Checkout and Self Serve Portal > Portal.
  2. Provide a link in your website/application which your authenticated customers can use to access the portal (For example, {your_website_url}/portal_link).
  3. Handle the link request in your server code and create a portal session for the customer by calling Chargebee's "Create a portal session" API
  4. Forward the user to the access URL present in the "Portal Session" resource returned by the above API call.

Notes about access URL:

  • The access URL should be accessed by the customer within one hour from the time it was created.
  • Once accessed, the session is valid until the user logs out from the portal UI or logout API is called from your application for this session.
  • Once accessed, the access url cannot be reused. Hence do not persist this URL. Whenever you need to provide access to the portal, you need to create a new portal session.

Using Chargebee's authentication

Note: This feature is not supported in in-app portal.

Chargebee allows you to integrate your website by building user authentication on top of Chargebee. You can also use the portal login to provide authenticated access for your customers to your website pages.

Workflow:
Users should be redirected to the portal login URL - https://yourdomain.chargebeeportal.com/portal/login by passing the following parameters:

  • return_url - URL the users should be redirected to upon successful authentication.
  • cancel_url - URL the users should be redirected to when they want to go back to your website during login.

The domain name used in the Return/Cancel URL should be added as a 'Whitelisted Domain' in Chargebee. Add just the domain name in Chargebee and not the entire URL: E.g. yourdomain.com.

Upon successful authentication, a session is created for the user and Chargebee redirects the user to the return_url along with the following parameters:

  • auth_session_id - Identifier to the authenticated session.
  • auth_session_token - Token for the session which should be sent later to activate this session.

Using the auth_session_id & auth_session_token, you should call Activate a Portal Session API to validate the session details and create a session for that user in your website.

Note: The process of setting up the portal account will take place along with the authentication process.

Sample portal session [ JSON ]

{ "access_url": "https://yourapp.chargebeeportal.com/portal/access/__test__cdBbQgJg5fPSTw9qBPDIaQiVEEx0Gsrrc", "created_at": 1517505973, "customer_id": "__test__KyVnHhSBWm8kA2sT", "expires_at": 1517509573, "id": "portal___test__KyVnHhSBWm8l82sV", "linked_customers": [ { "customer_id": "__test__KyVnHhSBWm8kA2sT", "has_active_subscription": false, "has_billing_address": false, "has_payment_method": false, "object": "linked_customer" } ], "object": "portal_session", "redirect_url": "https://yourdomain.com/users/3490343", "status": "created", "token": "__test__cdBbQgJg5fPSTw9qBPDIaQiVEEx0Gsrrc" }

API Index URL GET

https://{site}.chargebee.com/api/v2/portal_sessions

Model Class

 

      Portal session attributes
      
 
id
 

      string, max chars=70
 Unique identifier for the portal session. 
 
 
token
 

      string, max chars=70
 Unique pre-authenticated portal session token to access customer portal directly. 
 
 
access_url
 

      string, max chars=550
 Unique URL for accessing the customer portal. Once accessed, this cannot be reused. 
 
 
redirect_url
 

      optional, string, max chars=250
 URL to redirect when the user logs out from the portal. 
 
 
status
 

      enumerated string, default=created
 Indicates the current status of the portal session. 
 
Possible values are
 
createdIndicates that the portal session is just created and not yet accessed by the user.logged_inIndicates that the portal session URL has been accessed by the user and the session is active.logged_outIndicates that the portal session is logged out either by user or via API.not_yet_activatedIndicates that the portal session is created and not yet activated for the customer to allow access to your website. This is applicable when you use Chargebee’s authentication for your websiteactivatedIndicates that the portal session is activated for the customer to allow access to your website. This is applicable when you use Chargebee’s authentication for your website.
 
createdIndicates that the portal session is just created and not yet accessed by the user.logged_inIndicates that the portal session URL has been accessed by the user and the session is active.logged_outIndicates that the portal session is logged out either by user or via API.not_yet_activatedIndicates that the portal session is created and not yet activated for the customer to allow access to your website. This is applicable when you use Chargebee’s authentication for your website
 
activatedIndicates that the portal session is activated for the customer to allow access to your website. This is applicable when you use Chargebee’s authentication for your website.
 Show all values[+]
 
created_at
 

      timestamp(UTC) in seconds
 Timestamp indicating when this portal session was generated. 
 
 
expires_at
 

      optional, timestamp(UTC) in seconds
 Timestamp indicating when the access URL will expire. Once expired, the URL cannot be used to login into the portal. 
 
 
customer_id
 

      string, max chars=50
 Identifier of the customer. 
 
 
login_at
 

      optional, timestamp(UTC) in seconds
 Timestamp indicating when this portal session URL was accessed by the user. 
 
 
logout_at
 

      optional, timestamp(UTC) in seconds
 Timestamp indicating when this portal session was logged out either by user or via API. 
 
 
login_ipaddress
 

      optional, string, max chars=50
 IP Address from which the portal session URL was accessed. 
 
 
logout_ipaddress
 

      optional, string, max chars=50
 IP Address from which the portal session was logged out either by user or via API. 
 
 
 

      linked_customers
 Show attributes [+]
 
 optional, list of linked_customer
 The list of customers for this session
 
 
 
 
id id
 

          string, max chars=70
 Unique identifier for the portal session. 
 
token token
 

          string, max chars=70
 Unique pre-authenticated portal session token to access customer portal directly. 
 
access_url access_url
 

          string, max chars=550
 Unique URL for accessing the customer portal. Once accessed, this cannot be reused. 
 
redirect_url redirect_url
 

          optional, string, max chars=250
 URL to redirect when the user logs out from the portal. 
 
status status
 

          enumerated string, default=created
 Indicates the current status of the portal session. 
 
Possible values are
 
createdIndicates that the portal session is just created and not yet accessed by the user.logged_inIndicates that the portal session URL has been accessed by the user and the session is active.logged_outIndicates that the portal session is logged out either by user or via API.not_yet_activatedIndicates that the portal session is created and not yet activated for the customer to allow access to your website. This is applicable when you use Chargebee’s authentication for your websiteactivatedIndicates that the portal session is activated for the customer to allow access to your website. This is applicable when you use Chargebee’s authentication for your website.
 
createdIndicates that the portal session is just created and not yet accessed by the user.logged_inIndicates that the portal session URL has been accessed by the user and the session is active.logged_outIndicates that the portal session is logged out either by user or via API.not_yet_activatedIndicates that the portal session is created and not yet activated for the customer to allow access to your website. This is applicable when you use Chargebee’s authentication for your website
 
activatedIndicates that the portal session is activated for the customer to allow access to your website. This is applicable when you use Chargebee’s authentication for your website.
 Show all values[+]
created_at created_at
 

          timestamp(UTC) in seconds
 Timestamp indicating when this portal session was generated. 
 
expires_at expires_at
 

          optional, timestamp(UTC) in seconds
 Timestamp indicating when the access URL will expire. Once expired, the URL cannot be used to login into the portal. 
 
customer_id customer_id
 

          string, max chars=50
 Identifier of the customer. 
 
login_at login_at
 

          optional, timestamp(UTC) in seconds
 Timestamp indicating when this portal session URL was accessed by the user. 
 
logout_at logout_at
 

          optional, timestamp(UTC) in seconds
 Timestamp indicating when this portal session was logged out either by user or via API. 
 
login_ipaddress login_ipaddress
 

          optional, string, max chars=50
 IP Address from which the portal session URL was accessed. 
 
logout_ipaddress logout_ipaddress
 

          optional, string, max chars=50
 IP Address from which the portal session was logged out either by user or via API. 
 
linked_customers 
 

          optional, list of linked_customer
 The list of customers for this session 
 
 
 
Consent Fields for Portal session
 
 
Custom Fields for Portal session
 
 

      Create a portal session
      
 
Idempotency Supported
 
 
 Creates a portal session for a customer. The session resource in the response contains the access URL. Forward the customer to that access URL. If you would like to logout the customer later via API call, you need to store the id of the portal session resource returned by this API. While creating a session, you also need to pass the redirect URL to which your customers will be sent to upon logout from the portal UI. 
  
Notes
 
 

      Sample Request
    
 
 
curl  https://{site}.chargebee.com/api/v2/portal_sessions \
     -u {site_api_key}:\
     -d redirect_url="https://yourdomain.com/users/3490343" \
     -d "customer[id]"="__test__KyVnHhSBWm8kA2sT" 
 

      copy
      
Click to Copy
 
 
curl  https://{site}.chargebee.com/api/v2/portal_sessions \
     -u {site_api_key}:\
     -d redirect_url="https://yourdomain.com/users/3490343" \
     -d "customer[id]"="__test__KyVnHhSBWm8kA2sT" 
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "portal_session": {
        "access_url": "https://yourapp.chargebeeportal.com/portal/access/__test__cdBbQgJg5fPSTw9qBPDIaQiVEEx0Gsrrc",
        "created_at": 1517505973,
        "customer_id": "__test__KyVnHhSBWm8kA2sT",
        "expires_at": 1517509573,
        "id": "portal___test__KyVnHhSBWm8l82sV",
        "linked_customers": [
            {
                "customer_id": "__test__KyVnHhSBWm8kA2sT",
                "has_active_subscription": false,
                "has_billing_address": false,
                "has_payment_method": false,
                "object": "linked_customer"
            },
            {..}
        ],
        "object": "portal_session",
        "redirect_url": "https://yourdomain.com/users/3490343",
        "status": "created",
        "token": "__test__cdBbQgJg5fPSTw9qBPDIaQiVEEx0Gsrrc"
    }
}
 

      URL Format
      POST
 

      https://{site}.chargebee.com/api/v2/portal_sessions
    
 
Method
 
 
Input Parameters
 
  
 
redirect_url[]
 

      Required if customer portal is not integrated via iframe, string, max chars=250 
 URL to redirect when the user logs out from the portal. 
 
forward_url[]
 

      optional, string, max chars=250 
 By default access_url redirects the customer to the portal home page. If you would like to redirect the customer to a different URL, you can use this parameter to do so.

Note: This parameter is not applicable for in-app portal. 
 
 
 
 
 
customer[id]
 
required, string, max chars=50 
 Identifier of the customer. 
   
 
Returns
 
portal_session  portal_session
 

      always returned 
 Resource object representing portal_session
 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/portal_sessions/123x
    

      Retrieve a portal session
      
  
 
This API retrieves a portal session using portal_session_id as a path parameter.
  
Notes
 
 

      Sample Request
    
 
 
curl  https://{site}.chargebee.com/api/v2/portal_sessions/portal___test__KyVnGlSBWm8Rw2NP \
     -u {site_api_key}:
 

      copy
      
Click to Copy
 
 
curl  https://{site}.chargebee.com/api/v2/portal_sessions/portal___test__KyVnGlSBWm8Rw2NP \
     -u {site_api_key}:
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "portal_session": {
        "access_url": "https://yourapp.chargebeeportal.com/portal/access/__test__v3rABlcM6Cvfhcu6LGIMnNmp9sTPHcuGKcu",
        "created_at": 1517505972,
        "customer_id": "__test__KyVnHhSBWm8QH2sR",
        "expires_at": 1517506272,
        "id": "portal___test__KyVnGlSBWm8Rw2NP",
        "linked_customers": [
            {
                "customer_id": "__test__KyVnHhSBWm8QH2sR",
                "email": "duncan@user.com",
                "has_active_subscription": false,
                "has_billing_address": false,
                "has_payment_method": false,
                "object": "linked_customer"
            },
            {..}
        ],
        "login_at": 1517505972,
        "login_ipaddress": "127.0.0.1",
        "object": "portal_session",
        "redirect_url": "https://cbdemo.com:8080",
        "status": "activated",
        "token": "__test__v3rABlcM6Cvfhcu6LGIMnNmp9sTPHcuGKcu"
    }
}
 

      URL Format
      GET
 

      https://{site}.chargebee.com/api/v2/portal_sessions/{portal-session-id}
    
 
Method
 
  
   
 
    
 
Returns
 
portal_session  portal_session
 

      always returned 
 Resource object representing portal_session
 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/portal_sessions/123x
    

      Logout a portal session
      
 
Idempotency Supported
 
 
 Logs out the portal session. Typically this should be called when customers logout of your application. 
 

 If this API is called for a Portal Session that currently is in : 
 

     
 
  • "created" status, the session status will be marked as "logged_out" and the access URL will become invalid. 
    •  
 
  • "logged_in" status, the session status will be marked as "logged_out" and customer will not be able to use that session. 
    •  
 
  • "logged_out" status, this will return normally without changing any attribute of this resource.
    •  

  
Notes
 
 

      Sample Request
    
 
 
curl  https://{site}.chargebee.com/api/v2/portal_sessions/portal___test__KyVnHhSBWm9152sY/logout \
     -X POST  \
     -u {site_api_key}:
 

      copy
      
Click to Copy
 
 
curl  https://{site}.chargebee.com/api/v2/portal_sessions/portal___test__KyVnHhSBWm9152sY/logout \
     -X POST  \
     -u {site_api_key}:
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "portal_session": {
        "access_url": "https://yourapp.chargebeeportal.com/portal/access/__test__MUfEicuIkiAnAsyvcDLmTysj6myi86uNw",
        "created_at": 1517505974,
        "customer_id": "__test__KyVnHhSBWm90C2sW",
        "expires_at": 1517509574,
        "id": "portal___test__KyVnHhSBWm9152sY",
        "linked_customers": [
            {
                "customer_id": "__test__KyVnHhSBWm90C2sW",
                "has_active_subscription": false,
                "has_billing_address": false,
                "has_payment_method": false,
                "object": "linked_customer"
            },
            {..}
        ],
        "object": "portal_session",
        "redirect_url": "https://yourdomain.com/users/3490354",
        "status": "logged_out",
        "token": "__test__MUfEicuIkiAnAsyvcDLmTysj6myi86uNw"
    }
}
 

      URL Format
      POST
 

      https://{site}.chargebee.com/api/v2/portal_sessions/{portal-session-id}/logout
    
 
Method
 
  
   
 
    
 
Returns
 
portal_session  portal_session
 

      always returned 
 Resource object representing portal_session
 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/portal_sessions/123x
    

      Activate a portal session
      
 
Idempotency Supported
 
 
 When an user is sent back to your return URL with session details, you should validate that information by calling this API. The details passed to the return_url should be sent as below: 


     
 
  • auth_session_id - this should be sent as part of the endpoint.
    •  
 
  • auth_session_token - this should be sent as value for the input parameter token.
    •  

 

 

 Note: This API is not applicable for in-app portal. 
  
Notes
 
 

      Sample Request
    
 
 
curl  https://{site}.chargebee.com/api/v2/portal_sessions/portal___test__KyVnGlSBWm8Rw2NP/activate \
     -u {site_api_key}:\
     -d token="__test__v3rABlcM6Cvfhcu6LGIMnNmp9sTPHcuGKcu"
 

      copy
      
Click to Copy
 
 
curl  https://{site}.chargebee.com/api/v2/portal_sessions/portal___test__KyVnGlSBWm8Rw2NP/activate \
     -u {site_api_key}:\
     -d token="__test__v3rABlcM6Cvfhcu6LGIMnNmp9sTPHcuGKcu"
 
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "portal_session": {
        "access_url": "https://yourapp.chargebeeportal.com/portal/access/__test__v3rABlcM6Cvfhcu6LGIMnNmp9sTPHcuGKcu",
        "created_at": 1517505972,
        "customer_id": "__test__KyVnHhSBWm8QH2sR",
        "expires_at": 1517506272,
        "id": "portal___test__KyVnGlSBWm8Rw2NP",
        "linked_customers": [
            {
                "customer_id": "__test__KyVnHhSBWm8QH2sR",
                "email": "duncan@user.com",
                "has_active_subscription": false,
                "has_billing_address": false,
                "has_payment_method": false,
                "object": "linked_customer"
            },
            {..}
        ],
        "login_at": 1517505972,
        "login_ipaddress": "127.0.0.1",
        "object": "portal_session",
        "redirect_url": "https://cbdemo.com:8080",
        "status": "activated",
        "token": "__test__v3rABlcM6Cvfhcu6LGIMnNmp9sTPHcuGKcu"
    }
}
 

      URL Format
      POST
 

      https://{site}.chargebee.com/api/v2/portal_sessions/{portal-session-id}/activate
    
 
Method
 
 
Input Parameters
 
  
 
token[]
 

      required, string, max chars=70 
 Unique pre-authenticated portal session token to access customer portal directly. 
 
 
    
 
Returns
 
portal_session  portal_session
 

      always returned 
 Resource object representing portal_session
 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/portal_sessions/123x