Chargebee Getting Started: Account, Keys, and First API Call 2026

Getting started overview

Integrating with Chargebee for subscription and recurring billing management involves a structured process that begins with account creation and extends to making authenticated API calls. Developers typically follow a sequence of steps to configure their Chargebee environment, secure API credentials, and then programmatically interact with the platform. Chargebee's API is RESTful, supporting standard HTTP methods and JSON payloads for requests and responses. It is designed to manage core subscription lifecycle events, from customer creation and plan management to invoice generation and payment processing.

Before making any API calls, developers need to establish a Chargebee account, which provides access to the web interface and the necessary administrative tools for managing API keys and webhooks. The platform provides SDKs for several popular programming languages, including Python, Node.js, and Java, to simplify integration by abstracting common API interactions. These SDKs handle authentication, request formatting, and response parsing, allowing developers to focus on business logic rather than low-level HTTP details. Understanding the distinction between test and live environments is crucial, as API keys and data are separate for each to prevent accidental modifications to production systems during development.

The initial setup typically involves configuring your test site, which is a sandbox environment where you can experiment with Chargebee's features without impacting real customer data or financial transactions. Once familiar with the API and integration patterns, developers transition to a live site for production deployment. Chargebee's documentation emphasizes security best practices, such as protecting API keys and securely handling sensitive customer data, aligning with compliance standards like PCI DSS Level 1 and GDPR.

Create an account and get keys

To begin using Chargebee, the first step is to create an account. Chargebee offers a Launch plan that is free for businesses generating up to $50,000 in revenue, which is suitable for initial setup and testing. During the signup process, you will provide basic business information and set up your initial site. Your account will automatically be provisioned with a "test site" environment. This test site is critical for development, allowing you to simulate transactions, create customers, and manage subscriptions without affecting live data or incurring real costs. All API interactions during the initial setup should target this test site.

Once your account is active, you need to generate API keys to authenticate your requests. Chargebee uses a pair of keys for API access:

• Publishable Key: Used for client-side operations, such as integrating with Chargebee's hosted payment pages or client-side SDKs. This key is generally considered safe to expose in client-side code.
• Secret Key: Used for server-side operations that require full access to your Chargebee account data, such as creating subscriptions, managing invoices, or issuing refunds. This key must be kept confidential and never exposed in client-side code or public repositories.

To generate these keys:

1. Log in to your Chargebee test site.
2. Navigate to Settings > Configure Chargebee > API Keys.
3. Click the "Add API Key" button.
4. Choose the type of key (Production or Test) and specify an expiry if desired. For getting started, ensure you select "Test" keys.
5. Copy both the Publishable and Secret API keys. It is recommended to store your Secret API key in a secure environment variable or a secrets management service, rather than hardcoding it directly into your application code.

Chargebee's API keys are specific to each site (test or live) and environment. For instance, a Secret Key generated for your test site will not work on your live site, and vice-versa. This separation helps maintain data integrity and security during the development lifecycle, aligning with common practices in API security, as outlined by organizations like the Internet Engineering Task Force (IETF) for OAuth 2.0, which emphasizes client credential security.

Your first request

After setting up your Chargebee account and obtaining your API keys, the next step is to make your first authenticated API request. This demonstrates that your environment is correctly configured and that your API keys are valid. For this example, we will use the Chargebee Customers API to retrieve a list of customers. Even in a new test site, there might be a few sample customers automatically generated, or you can create one through the Chargebee UI first.

We'll use a Python example, as it's one of the primary languages supported by Chargebee SDKs, and demonstrates core API interaction principles applicable across other languages.

Prerequisites for Python:

1. Install the Chargebee Python SDK:

   pip install chargebee

2. Set up environment variables: Store your site name and Secret API key securely.

   export CHARGEBEE_SITE="your_test_site_name"
   export CHARGEBEE_API_KEY="your_test_secret_key"

   Replace your_test_site_name with the subdomain of your Chargebee test site (e.g., if your URL is https://your_test_site_name.chargebee.com) and your_test_secret_key with the Secret API Key you generated.

Python example: Fetching customers

import chargebee
import os

# Configure Chargebee with your site name and API key
chargebee.configure(
    site=os.environ.get('CHARGEBEE_SITE'),
    api_key=os.environ.get('CHARGEBEE_API_KEY')
)

try:
    # Fetch all customers
    # The list() method returns a ResultList object
    result_list = chargebee.Customer.list({"limit": 5}) # Limit to 5 for brevity

    print("Successfully fetched customers:")
    for customer_entry in result_list:
        customer = customer_entry.customer
        print(f"  Customer ID: {customer.id}, Email: {customer.email}")

except chargebee.exceptions.APIError as e:
    print(f"Chargebee API Error: {e.message}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

Explanation:

• chargebee.configure(): Initializes the SDK with your Chargebee site name and API key. This is a global configuration for the SDK.
• chargebee.Customer.list(): This method makes a GET request to the /customers endpoint. We've added a limit parameter to retrieve only up to 5 customers.
• result_list: The response from Chargebee for list operations is a ResultList object, which can be iterated over. Each item in the list is an object containing the primary resource (e.g., customer_entry.customer) and potentially related data.
• Error Handling: The try-except block catches potential chargebee.exceptions.APIError for issues like invalid API keys or network problems, and general exceptions for other unexpected issues.

Upon successful execution, this script will print the IDs and email addresses of up to five customers in your Chargebee test site. This confirms that your API credentials are correct and your application can communicate with Chargebee's services.

Common next steps

After successfully making your first API call, you can proceed with more complex integrations and functionalities within Chargebee. The following are typical next steps for developers:

1. Explore Core Resources: Familiarize yourself with other key API resources beyond customers, such as Plans, Subscriptions, and Invoices. Understanding how these resources interact is fundamental to building a complete subscription management system.
2. Implement Webhooks: Chargebee leverages webhooks to notify your application of events occurring in your Chargebee account (e.g., subscription activated, payment failed, invoice generated). Implementing a webhook listener in your application is crucial for real-time updates and automating workflows.
3. Integrate Hosted Pages: For payment collection and customer self-service, Chargebee offers hosted pages. These are pre-built, PCI-compliant pages for checkout, customer portal, and invoice payments that you can embed or link to from your application. This offloads significant compliance burden.
4. Handle Payments: Connect Chargebee with your preferred payment gateways (e.g., Stripe, PayPal, Braintree). Configure payment methods and understand how to process one-time and recurring payments through the API. Refer to the Chargebee Payment Gateways documentation for integration details.
5. Manage Product Catalog: Define your products, plans, and add-ons within Chargebee. This involves setting up pricing models, trial periods, and billing frequencies that align with your business offerings.
6. Transition to Live Site: Once your integration is thoroughly tested in the sandbox, replicate your configurations (plans, products, webhooks) to your live Chargebee site. Generate new production API keys and update your application's environment variables to point to the live environment.
7. Monitor and Audit: Set up monitoring for API calls, webhook deliveries, and system health. Regularly review Chargebee's audit logs and reports to ensure smooth operation and compliance.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some typical problems and their solutions:

• Authentication Error (401 Unauthorized):

  • Issue: Invalid API key or site name.
  • Solution: Double-check that your Secret API Key and site name are correct and match the environment (test vs. live). Ensure you are using a test key for your test site. Verify there are no leading/trailing spaces in the key or site name. Refer to the Chargebee API Authentication guide.

• Network Connection Issues:

  • Issue: Your application cannot reach Chargebee's servers.
  • Solution: Check your network connectivity. Ensure no firewalls or proxy settings are blocking outgoing requests to *.chargebee.com.

• SDK Configuration Error:

  • Issue: SDK not initialized correctly or missing dependencies.
  • Solution: Verify that the Chargebee SDK is properly installed (e.g., pip install chargebee for Python). Ensure the chargebee.configure() call is executed before any other SDK methods. Consult the specific SDK documentation for your language.

• Resource Not Found (404 Error):

  • Issue: Attempting to retrieve a resource (e.g., a specific customer or plan) that does not exist in your Chargebee account.
  • Solution: If you are trying to fetch a specific item, verify its ID. For list operations, ensure you're querying the correct endpoint. If fetching customers, manually create a few in your Chargebee test UI first.

• Invalid Parameters (400 Bad Request):

  • Issue: The request body or query parameters are malformed or contain invalid values.
  • Solution: Review the Chargebee API Reference for the specific endpoint you are calling. Pay close attention to required fields, data types, and allowed values for parameters.

• Environment Variable Issues:

  • Issue: Your application isn't picking up the environment variables (CHARGEBEE_SITE, CHARGEBEE_API_KEY).
  • Solution: Ensure environment variables are correctly set and accessible in the context where your script runs. For testing, you might temporarily hardcode values (only for testing, never in production) to confirm this is the issue, then revert to environment variables.

• Rate Limiting (429 Too Many Requests):

  • Issue: You've sent too many requests in a short period.
  • Solution: While unlikely for a first call, be aware of Chargebee's API rate limits. Implement exponential backoff for retries if you plan to make many requests programmatically.

If you continue to experience issues, consulting the Chargebee developer documentation or reaching out to Chargebee support with your request details, error messages, and API key environment (test/live) can help resolve complex problems.