Getting started

Chargebee provides HTTP based API which follows the essence of REST*. The HTTP protocol's rules are followed thereby enabling simple HTTP client tools like "curl" to be used.

The following client libraries provide a "easy to use" wrapper around the raw HTTP based API.

If you require support for additional languages, please raise a ticket on our support page.

Sample Snippets

Use the language bar at the top to view code examples in your chosen language.

Want us to generate ready-to-test snippets?

to Chargebee and open the API docs from there and you'll find ready-to-test sample codes based on your Chargebee test site's api key and data.
Don't have an account with Chargebee yet? .

Sample Apps

Explore our suite of sample applications, complete with tutorials to guide your integration with Chargebee.

Documentation

For in-depth explanations and definitions of all Chargebee components, consult our documentation.

Chargebee follows the REST model of exposing resources as urls. For example, subscriptions are exposed as

https://{site}.chargebee.com/api/v1/subscriptions

The Ruby client library provide a corresponding class representation of the resource. For example, subscriptions are represented by

    ChargeBee::Subscription

Request

All operations specific to that resource are exposed as class methods in the corresponding resource class. The methods accepts the input params as hash. You could also pass the environment configuration specific to that request as an additional parameter.

Response

The response is in JSON format. Currently Chargebee does not support any other response format. The ChargeBee::Result class wraps the response sent by the server. It has methods that allow you to fetch the specific resource from the result. The ChargeBee::ListResult class is used to wrap list responses.

Note: Sometimes, while working with Chargebee APIs, you may see undocumented attributes returned in the response. Such attributes should be ignored.

Sample Codes

/*
    creates a subscription with customer information and billing details.
*/

require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::Subscription.create({
  :plan_id => "no_trial",
  :billing_address => {
    :first_name => "John",
    :last_name => "Doe",
    :line1 => "PO Box 9999",
    :city => "Walnut",
    :state => "California",
    :zip => "91789",
    :country => "US"
    },
  :customer => {
    :first_name => "John",
    :last_name => "Doe",
    :email => "john@user.com",
    :auto_collection => "off"
    }
  })
subscription = result.subscription
customer = result.customer
card = result.card
invoice = result.invoice

copy

/*
    creates a subscription with customer information and billing details.
*/

require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::Subscription.create({
  :plan_id => "no_trial",
  :billing_address => {
    :first_name => "John",
    :last_name => "Doe",
    :line1 => "PO Box 9999",
    :city => "Walnut",
    :state => "California",
    :zip => "91789",
    :country => "US"
    },
  :customer => {
    :first_name => "John",
    :last_name => "Doe",
    :email => "john@user.com",
    :auto_collection => "off"
    }
  })
subscription = result.subscription
customer = result.customer
card = result.card
invoice = result.invoice

Sample Result [ JSON ]

{
    "customer": {
        "account_credits": 0,
        "allow_direct_debit": false,
        "auto_collection": "off",
        "billing_address": {
            "city": "Walnut",
            "country": "US",
            "first_name": "John",
            "last_name": "Doe",
            "line1": "PO Box 9999",
            "object": "billing_address",
            "state": "California",
            "state_code": "CA",
            "zip": "91789"
        },
        "card_status": "no_card",
        "created_at": 1517506669,
        "email": "john@user.com",
        "excess_payments": 0,
        "first_name": "John",
        "id": "__test__5SK0bLNFRFuBv6r6j",
        "last_name": "Doe",
        "object": "customer",
        "refundable_credits": 0,
        "taxability": "taxable"
    },
    "invoice": {
        "amount": 895,
        "amount_adjusted": 0,
        "amount_due": 895,
        "amount_paid": 0,
        "billing_address": {
            "city": "Walnut",
            "country": "US",
            "first_name": "John",
            "last_name": "Doe",
            "line1": "PO Box 9999",
            "object": "billing_address",
            "state": "California",
            "state_code": "CA",
            "zip": "91789"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__5SK0bLNFRFuBv6r6j",
        "end_date": 1517506669,
        "first_invoice": true,
        "id": "__demo_inv__7",
        "line_items": [
            {
                "amount": 895,
                "date_from": 1517506669,
                "date_to": 1519925869,
                "description": "No Trial",
                "entity_id": "no_trial",
                "entity_type": "plan",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 1,
                "tax": 0,
                "type": "charge",
                "unit_amount": 895
            },
            {..}
        ],
        "linked_orders": [],
        "linked_transactions": [],
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "start_date": 1517506669,
        "status": "payment_due",
        "sub_total": 895,
        "subscription_id": "__test__5SK0bLNFRFuBv6r6j",
        "tax": 0
    },
    "subscription": {
        "activated_at": 1517506669,
        "created_at": 1517506669,
        "current_term_end": 1519925869,
        "current_term_start": 1517506669,
        "due_invoices_count": 1,
        "due_since": 1517506669,
        "has_scheduled_changes": false,
        "id": "__test__5SK0bLNFRFuBv6r6j",
        "object": "subscription",
        "plan_id": "no_trial",
        "plan_quantity": 1,
        "started_at": 1517506669,
        "status": "active",
        "total_dues": 895
    }
}

Installing Ruby Library

The library can be installed as gem

    sudo gem install chargebee -v '~>1'

Then require the gem as:

require 'chargebee'

Source Code

The source code for the client library is available as a public repository at github. The code is provided with MIT license. So in case you need any modifications please feel free to do so. If you think it would be useful for other users please do let us know.

Library version

Newer versions of client library are released whenever there are new additions to the API. The version numbering format is major-version.minor-version(s). All minor releases are backward compatible. Please check the change notes for more details.
The latest version details for API V1 are:
Version: 1.7.5
Released On: 2019-08-27

OpenAPI Specification

As part of our commitment to enhance the developer experience, we're thrilled to introduce the Chargebee OpenAPI specification. It's the first step in a series of planned improvements.

The Chargebee OpenAPI specification is a version of our API spec that is fully compliant with the OpenAPI Specification v3.0.1. Stay tuned for more updates!

Code samples

The sample code snippets provided for the endpoints in this documentation are ready-to-test. Once you log in and select a test site using the dropdown that appears at the top, the code samples in this documentation automatically include your API key and site data.

API testing

Chargebee provides the Time Machine feature to help you test your integration. Once you've set up your billing configuration on the test site, you can simulate events on a hypothetical time frame to ensure everything works as expected. Ensure that you rigorously test your configuration before going live.

Additional developer resources

Check out our collection of sample applications and related tutorials for integrating with Chargebee.