API Quickstart

The instructions on this page help you get started with integrating Chargebee APIs. You will install a client library and make calls to our Product Catalog APIs to define a plan-item price. You will also create a customer record in Chargebee, associating a test card to it. Finally, you will make one API call which will create both a subscription and the associated invoice.

Step 1: Get your API key 

Once you have signed up for a Chargebee account, a test site is created for you. Obtain a full-access API key from your test site for testing and development. You must be an admin or owner of the Chargebee site to see its API keys. Here's an example of what the key can look like: test_YkiZnDgc1MWyjlWRNBJgHsKCRSSB8cuDlS.

Note

API keys must be managed securely. See this section to learn best practices.

Step 2: Download and set up a client library 

Install one of our client libraries to get started from within your development environment.

Select from one of the following options depending on your environment.

Maven

For Maven, add the following dependency to your POM:

<dependency>
<groupId>com.chargebee</groupId>
<artifactId>chargebee-java</artifactId>
<version>LATEST</version>
</dependency>

The above code would fetch the latest version of the library. To download a specific version, replace LATEST in the above code with the version number.

Gradle

For Gradle, add the following to build.gradle:

implementation group: 'com.chargebee', name: 'chargebee-java', version: '{VERSION}'

To get the latest version, remove version: '{VERSION}' in the above code.

Select from one of the following options depending on your environment.

Composer

Install via Composer:

composer require chargebee/chargebee-php:'>=2, <3'

Source Code

  1. Download the source code from https://github.com/chargebee/chargebee-php/tags
  2. Extract the library.
  3. Add the following line to your code:
require_once('/path/to/ChargeBee.php');
  1. Run the following command on your terminal.

    sudo gem install chargebee -v '~>2'
    
  2. Add the following line to your code:

    require 'chargebee'
    

Step 3: Create a customer with a payment method 

Create a customer named Acme Eastern and associate a test card payment method with them. Enable auto-collection so that the card is charged automatically when you eventually create a subscription.

Step 4: Create an item family 

Create an item family. This defines a group of products and services that you sell. In our example, it is Cloud Storage.

Step 5: Create an item 

Now, create an item. An item defines one of the products within the Cloud Storage item family. Set its type to plan. An item of type plan is required to create a subscription. Let's call it Silver Plan.

Step 6: Create an item price 

Item prices define the pricing for an item. They specify how often the customer is charged in a subscription, how much they're charged, and what currency. Let's create an item price for Silver Plan, which charges $500 every month, and call it Silver USD monthly.

Step 7: Create a subscription 

We're now ready to create a subscription for Acme Eastern. Let's subscribe the customer to 4 units of Silver USD monthly.

The endpoint responds with a payload that carries the following objects:

  • The subscription that was created.
  • The customer for whom it was created.
  • The details of the card that was charged.
  • The invoice that was generated for the charge.

A sample response is provided below:

{
    "subscription": {
        "id": "16Bjl4Sa1y72u3Ppw",
        "billing_period": 1,
        "billing_period_unit": "month",
        "customer_id": "acme-east",
        "status": "active",
        "current_term_start": 1623416481,
        "current_term_end": 1626008481,
        "next_billing_at": 1626008481,
        "created_at": 1623416481,
        "started_at": 1623416481,
        "activated_at": 1623416481,
        "updated_at": 1623416481,
        "has_scheduled_changes": false,
        "resource_version": 1623416481565,
        "deleted": false,
        "object": "subscription",
        "currency_code": "USD",
        "subscription_items": [
            {
                "item_price_id": "silver-plan-USD-monthly",
                "item_type": "plan",
                "quantity": 5,
                "unit_price": 50000,
                "amount": 250000,
                "free_quantity": 0,
                "object": "subscription_item"
            }
        ],
        "due_invoices_count": 0,
        "mrr": 0
    },
    "customer": {
        "id": "acme-east",
        "auto_collection": "on",
        "net_term_days": 0,
        "allow_direct_debit": false,
        "created_at": 1623294986,
        "taxability": "taxable",
        "updated_at": 1623294986,
        "pii_cleared": "active",
        "resource_version": 1623294986772,
        "deleted": false,
        "object": "customer",
        "card_status": "valid",
        "promotional_credits": 0,
        "refundable_credits": 0,
        "excess_payments": 0,
        "unbilled_charges": 0,
        "preferred_currency_code": "USD",
        "primary_payment_source_id": "pm_AzyuEASZtkKjx1wxQ",
        "payment_method": {
            "object": "payment_method",
            "type": "card",
            "reference_id": "tok_AzyuEASZtkKjl1wxP",
            "gateway": "chargebee",
            "gateway_account_id": "gw_AzZhVYSZlfWhVmD9",
            "status": "valid"
        }
    },
    "card": {
        "status": "valid",
        "gateway": "chargebee",
        "gateway_account_id": "gw_AzZhVYSZlfWhVmD9",
        "iin": "411111",
        "last4": "1111",
        "card_type": "visa",
        "funding_type": "credit",
        "expiry_month": 12,
        "expiry_year": 2022,
        "created_at": 1623294986,
        "updated_at": 1623294986,
        "resource_version": 1623294986774,
        "object": "card",
        "masked_number": "************1111",
        "customer_id": "acme-east",
        "payment_source_id": "pm_AzyuEASZtkKjx1wxQ"
    },
    "invoice": {
        "id": "12",
        "customer_id": "acme-east",
        "subscription_id": "16Bjl4Sa1y72u3Ppw",
        "recurring": true,
        "status": "paid",
        "price_type": "tax_exclusive",
        "date": 1623416481,
        "due_date": 1623416481,
        "net_term_days": 0,
        "exchange_rate": 1.0,
        "total": 250000,
        "amount_paid": 250000,
        "amount_adjusted": 0,
        "write_off_amount": 0,
        "credits_applied": 0,
        "amount_due": 0,
        "paid_at": 1623416481,
        "updated_at": 1623416481,
        "resource_version": 1623416481559,
        "deleted": false,
        "object": "invoice",
        "first_invoice": true,
        "amount_to_collect": 0,
        "round_off_amount": 0,
        "new_sales_amount": 250000,
        "has_advance_charges": false,
        "currency_code": "USD",
        "base_currency_code": "USD",
        "is_gifted": false,
        "term_finalized": true,
        "tax": 0,
        "line_items": [
            {
                "id": "li_16Bjl4Sa1y73T3Ppy",
                "date_from": 1623416481,
                "date_to": 1626008481,
                "unit_amount": 50000,
                "quantity": 5,
                "amount": 250000,
                "pricing_model": "per_unit",
                "is_taxed": false,
                "tax_amount": 0,
                "object": "line_item",
                "subscription_id": "16Bjl4Sa1y72u3Ppw",
                "customer_id": "acme-east",
                "description": "Silver USD",
                "entity_type": "plan_item_price",
                "entity_id": "silver-plan-USD-monthly",
                "tax_exempt_reason": "tax_not_configured",
                "discount_amount": 0,
                "item_level_discount_amount": 0
            }
        ],
        "sub_total": 250000,
        "linked_payments": [
            {
                "txn_id": "txn_16Bjl4Sa1y74A3Ppz",
                "applied_amount": 250000,
                "applied_at": 1623416481,
                "txn_status": "success",
                "txn_date": 1623416481,
                "txn_amount": 250000
            }
        ],
        "dunning_attempts": [],
        "applied_credits": [],
        "adjustment_credit_notes": [],
        "issued_credit_notes": [],
        "linked_orders": []
    }
}