Convert an existing trial user to a paid subscriber

Watch Video

Let us consider a user who is in trial and after trying the product wants to upgrade to a paid plan. With Chargebee, you can use our hosted checkout pages through API to allow the users to become a paid user.
The advantage of using hosted checkout pages is that you get a PCI DSS compliant checkout flow because your servers do not handle any of the sensitive card information. Click here   to learn more about Chargebee's hosted checkout page option.

Learn more about theme customization here .

Alternative options

Using the complete API integration, you can build your own checkout form. But with this mode of integration, you will need to take care of the PCI compliance requirements.

Honey Comics - Demo Application 

'Honey Comics', our demo application, is a fictitious online comic book store providing a subscription service for comics. We send comic books every week to subscribers. In order to let customers try the service, we provide them with a free trial period for a month. The user would convert to a paid user by using the upgrade option in the website. As of now we charge the user immediately on upgrade even though there could be some trial period left.

BTW, in our sample implementation, to simplify code,

  • We won't be using any database.
  • Also we will not have real login implementation hence we will hard code the user id.


To try out the tutorial yourself, you'll need the following:

  • A Chargebee account. Signup for a free trial if you don't have one.
  • A plan with a trial period in Chargebee. You can setup the plan and subscription for the demo using the "Setup Configuration" option in the index page if you have downloaded code and started the tutorials locally.
  • Your Chargebee API key for your test site.
  • The hosted page return URL  configured in Chargebee.

We should already have a trial subscription in Chargebee for that user. We could do this either via api call or via Chargebee's Admin UI. In addition to that, they should be signed-in into our application so that our system is able to identify the user.

Build the upgrade page 

Build a page where users can upgrade/checkout. In our demo application, we've assumed that there will only be a single plan and the user is currently in trial. When the user clicks on upgrade, the request will be sent to the server.

  • php
  • Ruby
  • Java
  profile.html  -   View full code
Click on </span>"Upgrade" <span class="text-muted">to enter your credit card details and upgrade to a paid subscription.</span><br><br>
<form action="checkout" method="post" id="subscribe-form">
    <!-- We have hard-coded the subscription id.
    It should be the subscription id of the user who has logged-in-->
    <input type="hidden" name="subscription_id" value=""/>
    <input type="submit" class="btn btn-success" value="Upgrade" />

Now lets switch to the server side implementation

Setup the client library 

We first have to download and import  the client library of our choice. Then we need to configure the client library with our test site and our test api key.

For the tutorials we have configured the site and the credentials in a properties file from which the client library is configured at the webapp is initialized.

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

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

For the tutorials we have configured the site credentials in Config.php which is included in other php files.

Request a hosted page URL 

When the server receives the upgrade request, we invoke Chargebee's checkout existing subscription  API. The API will return a hosted page resource response  containing the URL to forward the user to.

Forward user to the checkout page 

We send a 302 redirect response with location set to the URL.

Implement 'Return URL' 

Once the user is on the checkout page and has completed the checkout process, Chargebee will send the user back to your server based on the redirect URL that had been passed previously to the hosted page api call.

Additionally, the following parameters will be added to the redirect URL:

id - unique identifier of the hosted page resource.
state - succeeded, failed or cancelled.

The ‘id' parameter can be used to call the ‘acknowledge hosted page'  API. The response  from this API will have the details provided in the checkout page.


It is recommended that you use ‘acknowledge hosted page' API when you are syncing data using the returned URL. This will ensure that multiple redirects of redirect URL with the same hosted page id will not create duplicate entries at your end. Acknowledge API can be called only once for succeeded hosted page. After calling this the state of the hosted page will be changed from succeeded to acknowledged. And if the same api call is made on the same hosted page id again error will be thrown.

Redirect the user 

After we've fetched the hosted page, we redirect the user to a simple thank you page.You could update the subscription in your database (skipped in demo) and redirect to the appropriate page.


Here is the summary of steps you need to follow:

  1. Build the upgrade page. It could be a simple static html file showing the various plans and letting the user choose his plan.
  2. In the server forward the upgrade request to Chargebee by calling checkout existing API .
  3. The response to the API call will contain the URL for your hosted checkout page. Forward the user to that URL.
  4. Once the checkout is finished, Chargebee will forward the user back to your application using the return URL  configured in Chargebee. In server side handle the redirect request and update your database by fetching the subscription details from Chargebee.
  5. As a last step,forward the user to the appropriate page (such as thank you page).