You are viewing the documentation for Chargebee API V2. If you're using the older version (V1), click here.

Getting started

Chargebee provides an HTTP-based API that follows the principles of REST. The HTTP rules followed allow simple HTTP clients like cURL to be used as well. The URLs are resource-oriented, the request format is form-encoded, and the responses are in JSON.

Depending on the type of operation, the endpoints use one of two HTTP methods:

  • GET: Used for all read-only operations such as retrieving a resource or listing a group of resources.
  • POST: Used for all write operations. Such operations modify the state of a resource.

A history of changes to the API is provided in the API Changelog.

Note

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

Early Access Program

Some features in the API are part of the Early Access Program and are labeled "EAP," "Beta," or "Early Access." Please review the terms and conditions that apply to these features before using them.

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

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


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

    com.chargebee.models.Subscription

Request

The client library exposes all operations specific to that resource as static methods in the corresponding resource class and they return a operation specific Request object. The "Request" objects expose a fluent API using which you could set the input parameters for the operation. After filling in the request parameters, invoke the request method to send the request. There is an additional overloaded request method that takes in environment configuration that is applied only for that request.

Response

The response is in JSON format. Currently Chargebee does not support any other response format. The com.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 com.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
import java.io.IOException;
import com.chargebee.*;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;

public class Sample{
  
  public static void main(String args[]) throws IOException{
    
    

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.createWithItems("__test__8asz8Ru9WhHOJO")
	.subscriptionItemItemPriceId(0,"basic-USD")
	.subscriptionItemBillingCycles(0,2)
	.subscriptionItemQuantity(0,1)
	.subscriptionItemItemPriceId(1,"day-pass-USD")
	.subscriptionItemUnitPrice(1,100)
	.request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();
Invoice invoice = result.invoice();
List unbilledCharges = result.unbilledCharges();
    System.out.println(result);
  }
}
copy full code
copy snippet

Environment.configure("{site}","{site_api_key}");
Result result = Subscription.createWithItems("__test__8asz8Ru9WhHOJO")
	.subscriptionItemItemPriceId(0,"basic-USD")
	.subscriptionItemBillingCycles(0,2)
	.subscriptionItemQuantity(0,1)
	.subscriptionItemItemPriceId(1,"day-pass-USD")
	.subscriptionItemUnitPrice(1,100)
	.request();
Subscription subscription = result.subscription();
Customer customer = result.customer();
Card card = result.card();
Invoice invoice = result.invoice();
List<UnbilledCharge> unbilledCharges = result.unbilledCharges();

Sample Result [ JSON ]

Show more...
{ "customer": { "allow_direct_debit": false, "auto_collection": "off", "card_status": "no_card", "created_at": 1612890916, "deleted": false, "excess_payments": 0, "first_name": "John", "id": "__test__8asukSOXdulGOV", "last_name": "Doe", "net_term_days": 0, "object": "customer", "pii_cleared": "active", "preferred_currency_code": "USD", "promotional_credits": 0, "refundable_credits": 0, "resource_version": 1612890916000, "taxability": "taxable", "unbilled_charges": 0, "updated_at": 1612890916 }, "invoice": { "adjustment_credit_notes": [], "amount_adjusted": 0, "amount_due": 1100, "amount_paid": 0, "amount_to_collect": 1100, "applied_credits": [], "base_currency_code": "USD", "billing_address": { "first_name": "John", "last_name": "Doe", "object": "billing_address", "validation_status": "not_validated" }, "credits_applied": 0, "currency_code": "USD", "customer_id": "__test__8asukSOXdulGOV", "date": 1612890916, "deleted": false, "due_date": 1612890916, "dunning_attempts": [], "exchange_rate": 1, "first_invoice": true, "has_advance_charges": false, "id": "__demo_inv__10", "is_gifted": false, "issued_credit_notes": [], "line_items": [ { "amount": 1000, "customer_id": "__test__8asukSOXdulGOV", "date_from": 1612890916, "date_to": 1615310116, "description": "basic USD", "discount_amount": 0, "entity_id": "basic-USD", "entity_type": "plan_item_price", "id": "li___test__8asukSOXdutkOa", "is_taxed": false, "item_level_discount_amount": 0, "object": "line_item", "pricing_model": "per_unit", "quantity": 1, "subscription_id": "__test__8asukSOXduqmOY", "tax_amount": 0, "tax_exempt_reason": "tax_not_configured", "unit_amount": 1000 }, {..} ], "linked_orders": [], "linked_payments": [], "net_term_days": 0, "new_sales_amount": 1100, "object": "invoice", "price_type": "tax_exclusive", "recurring": true, "resource_version": 1612890917000, "round_off_amount": 0, "status": "payment_due", "sub_total": 1100, "subscription_id": "__test__8asukSOXduqmOY", "tax": 0, "term_finalized": true, "total": 1100, "updated_at": 1612890917, "write_off_amount": 0 }, "subscription": { "activated_at": 1612890916, "billing_period": 1, "billing_period_unit": "month", "created_at": 1612890916, "currency_code": "USD", "current_term_end": 1615310116, "current_term_start": 1612890916, "customer_id": "__test__8asukSOXdulGOV", "deleted": false, "due_invoices_count": 1, "due_since": 1612890916, "has_scheduled_changes": false, "id": "__test__8asukSOXduqmOY", "mrr": 0, "next_billing_at": 1615310116, "object": "subscription", "remaining_billing_cycles": 1, "resource_version": 1612890917000, "started_at": 1612890916, "status": "active", "subscription_items": [ { "amount": 1000, "billing_cycles": 1, "free_quantity": 0, "item_price_id": "basic-USD", "item_type": "plan", "object": "subscription_item", "quantity": 1, "unit_price": 1000 }, {..} ], "total_dues": 1100, "updated_at": 1612890917 } }

Client libraries

Chargebee provides the following open-source client libraries as a wrapper around the HTTP API:

To view this API reference tailored to the programming language of your choice, select the language in the “Library” dropdown above. Reach out to us at Chargebee Support if you’d like to request any other language bindings.

Java client library

Note

Select the programming language of your choice from the “Library” dropdown at the top of the page.

The client libraries for this API are open source and are available on GitHub under the MIT license.
INSTALL THE LIBRARY

You can install the library via Maven or by adding a JAR file to your project.

INSTALL USING MAVEN
You can install the library by adding the following dependency to pom.xml.
Library v3
<dependency>
  <groupId>com.chargebee</groupId>
  <artifactId>chargebee-java</artifactId>
  <version>3.1.1</version>
</dependency>
Library v2
Alert!

Eventually, v2 will become inactive, after which it will no longer receive any new updates. We encourage you to upgrade to v3 at the earliest.

<dependency>
  <groupId>com.chargebee</groupId>
  <artifactId>chargebee-java</artifactId>
  <version>2.22.1</version>
</dependency>
OBTAIN JAR FILES

You can find the JAR files for the library in the dist directory. To obtain the JAR files for a specific library version, check the dist directory within the source tree of the appropriate tag.

IMPORT PACAKAGES
Once the library is installed, import the following packages within your source code.
    import com.chargebee.*;
    import com.chargebee.models.*;
    import com.chargebee.models.enums.*;
    import com.chargebee.exceptions.*;
    
LIBRARY VERSIONS
The Java client library has two active versions, v2 and v3. See the source code readme for more details on versioning.
Version 3:
* Latest release: 3.1.1
* Release date: 2023-01-19
Version 2:
* Latest release: 2.22.1
* Release date: 2023-01-19

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.