Chargebee API Essential Guide

What type of API does Chargebee provide?

Chargebee has a REST API.

Key points:

1. Chargebee provides an HTTP-based API that follows the principles of REST.

2. The API uses resource-oriented URLs, form-encoded request formats, and JSON responses.

3. It uses standard HTTP methods like GET for read operations and POST for write operations.

4. The API endpoints are structured around resources, for example:

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

Code example:

Here's a simple example of making a GET request to the Chargebee API using cURL:

curl https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id} \
    -u {site_api_key}:

Best practices:

1. Use HTTPS for all API requests to ensure security.

2. Include your API key in the request for authentication.

3. Handle API responses and errors appropriately in your code.

4. Use the provided client libraries when possible to simplify API interactions.

5. Be aware of rate limits and implement proper error handling for API requests.

Does the Chargebee API have webhooks?

Yes, the official Chargebee API does have webhooks. Here are the key points about Chargebee's webhook functionality:

Webhook Support

1. Chargebee provides webhooks to notify your systems about events as they occur in your Chargebee instance.

2. You can set up multiple webhook endpoints using the Chargebee console to be notified of various events.

Event Types

Chargebee supports a wide range of event types that you can subscribe to via webhooks. Some examples include:

• Subscription-related events (e.g., subscription_created, subscription_cancelled)
• Customer-related events (e.g., customer_created)
• Payment-related events
• Invoice-related events
• Plan, addon, and coupon-related events

The full list of event types is available in the Chargebee API documentation.

Webhook Functionality

1. Webhooks are sent as HTTP POST requests with content type application/json.

2. Each webhook contains detailed information about the event, including:

   • Event type
   • API version
   • Event content (JSON data associated with the event)
   • Origin user (for API-triggered events)
   • Webhook status information

3. Chargebee supports multiple API versions, so you need to specify the API version when creating webhooks.

4. Webhooks are asynchronous and may not be suitable for time-critical applications. For such cases, Chargebee recommends using their List events API to poll for events.

Best Practices

1. Implement proper error handling and retries, as Chargebee will retry failed webhook deliveries up to 7 times at exponential intervals.

2. Be prepared to handle out-of-order delivery of webhooks.

3. Use the resource_version attribute to order events and ensure you're processing the most up-to-date information.

4. Consider securing your webhook URL using basic authentication.

5. Be aware that Chargebee sends webhooks from specific IP addresses, which you may need to whitelist.

In summary, Chargebee's webhook system provides a robust way to integrate real-time event notifications into your application, covering a wide range of event types related to subscriptions, customers, payments, and more.

Rate Limits and other limitations

Here are the key points about the API rate limits for the Chargebee API:

Rate Limiting Criteria

Chargebee restricts API requests based on two criteria [1][2][3]:

1. Requests per minute - Number of requests in the past 60 seconds
2. Concurrent requests - Number of requests at an instance of time

Rate Limits by Plan

The rate limits vary by Chargebee plan [1][2]:

• Starter Plan:

  • Live site: 150 requests per minute
  • Test site: 150 requests per minute
  • Live site concurrent: Up to 150 simultaneous requests (max 50 GET, 100 POST)
  • Test site concurrent: Up to 100 simultaneous requests (max 50 GET, 50 POST)

• Performance Plan:

  • Live site: 300 requests per minute

• Enterprise Plan:

  • Custom limits

Exceeding Rate Limits

When the rate limit is exceeded [1][2][3]:

• An HTTP 429 error response is returned
• No more requests are served until the limit resets (approximately 1 minute)
• For test sites, there is a 5 minute cooling period
• For live sites, there is a 1 minute cooling period

Best Practices for Handling Rate Limits

When encountering rate limits [1]:

• Check for a Retry-After header and wait the specified time before retrying
• Use exponential backoff when retrying requests
• Add randomized jitter to avoid the "thundering herd" problem

Increasing Rate Limits

• Temporary increases can be requested by contacting Chargebee support [1][2]
• For frequent limit breaches, upgrading to a higher plan is recommended [1][2]

Key Considerations

• Rate limits apply separately to test and live sites [1][2]
• Enterprise plans can have custom rate limits [2]
• The total limit for group items in a single purchase is 60 [4]

In summary, Chargebee implements API rate limiting based on requests per minute and concurrent requests, with limits varying by plan. Proper error handling and backoff strategies are recommended when working with the API.

Latest API Version

The most recent version of the Chargebee API is V2.

Key points to consider:

• Chargebee currently has two major API versions: V1 and V2.

• V2 is the latest version of the Chargebee API. As stated in the documentation: "As all of our future development will happen in API V2, the latest version of Chargebee API, you might want to upgrade to V2 to benefit from the new functionality."

• Within V2, there are sub-versions related to changes in the Product Catalog APIs.

• The API version can be identified in several ways:

  • In API endpoint paths: V2 paths begin with /api/v2
  • In webhook payloads: The api_version attribute indicates the version
  • In client libraries: The version is configured in the source code

Best practices:

1. Use the latest V2 version of the API to benefit from new features and improvements.

2. When upgrading from V1 to V2, review the API V2 Upgradation Guide to understand the changes and necessary modifications to your code.

3. Check the API changelog regularly to stay informed about new features and changes.

4. When using client libraries, ensure compatibility between the library version and the API version you're using.

5. When working with webhooks, be aware that the payload schema is determined by the API version.

How to get a Chargebee developer account and API Keys?

Here's how to get a developer account for Chargebee to create an API integration:

1. Sign up for a Chargebee account:

   • Go to the Chargebee website and sign up for an account.
   • Once you sign up, a test site will be automatically created for you to use for development and testing.

2. Access your API keys:

   • Log in to your Chargebee account and go to Settings > Configure Chargebee > API Keys and Webhooks.
   • Click on the API Keys tab to view existing keys or create new ones.

3. Create a new API key:

   • Click on the "Add an API Key" button.
   • Choose the type of key you want to create (e.g., full access, restricted access).
   • Give the key a name.
   • Click "Create Key" to generate the new API key.

4. Securely store your API key:

   • Once created, you'll see your API key. It will look something like: test_YkiZnDgc1MWyjlWRNBJgHsKCRSSB8cuDlS.
   • Make sure to securely store this key as it provides access to your Chargebee account.

5. Start integrating:

   • Use the API key in your code to authenticate requests to the Chargebee API.
   • Refer to Chargebee's API documentation and SDKs for your preferred programming language to start building your integration.

Key points to consider:

• You must be an admin or owner of the Chargebee site to access and create API keys.
• API keys for test and live sites are distinct, so make sure you're using the correct key for your environment.
• Follow best practices for API key management to keep your account secure.

By following these steps, you'll have a developer account set up with Chargebee and be ready to create your API integration using the provided API key.

What can you do with the Chargebee API?

Based on the Chargebee API documentation, here are the key data models you can interact with and what is possible for each:

Customers

• Create, retrieve, update and delete customer records
• Manage customer billing and shipping addresses
• Add custom fields and metadata to customers
• Associate payment sources with customers

Subscriptions

• Create, retrieve, update and cancel subscriptions
• Change subscription plans
• Add/remove addons
• Schedule future changes
• Apply coupons
• Pause/resume subscriptions
• Add custom fields and metadata

Invoices

• Create, retrieve and update invoices
• Apply credits/adjustments to invoices
• Collect payments for invoices
• Void and write off invoices
• Generate invoice PDFs

Plans

• Create, retrieve, update and delete plans
• Configure pricing, billing cycles, trial periods
• Set up addons and charges
• Define metered and quantity-based billing

Coupons

• Create, retrieve, update and delete coupons
• Set discount amounts/percentages
• Configure coupon validity and usage limits
• Apply coupons to subscriptions/invoices

Payments

• Process payments
• Refund payments (full or partial)
• Record offline payments
• Manage payment sources (cards, bank accounts)
• Configure payment gateways

Items

• Create, retrieve, update and delete items (products/services)
• Set pricing and tax configurations
• Group items into item families
• Add custom fields and metadata

Orders

• Create, retrieve and update orders
• Add line items and apply discounts
• Generate invoices from orders

Events & Webhooks

• Retrieve event data
• Configure webhook endpoints
• Receive real-time notifications for events

Custom Fields & Metadata

• Add custom fields to supported resources
• Store additional metadata on resources

This covers the core data models, but Chargebee offers many more capabilities through its API. The documentation provides full details on all available operations for each resource.