# Credit Units

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


Credit units power credit-based billing for usage-based products, letting you get paid upfront while customers spend credits as they use your product's features. Each credit unit is a customizable consumption unit, such as AI credits or API calls, that you define beyond Chargebee's built-in pricing dimensions.

## When should you use credit units?[](#when-should-you-use-credit-units)

Credit units are a good fit when:

-   Customers have widely varying usage patterns
-   Business costs scale with consumption
-   Upfront cash flow is preferred

## How does it work?[](#how-does-it-work)

1.  Create a credit unit (say, "AI Credits")
2.  Configure credit grants on your plans (e.g., a Pro Plan priced at $20 USD includes 100 AI Credits)
3.  Track customer usage in real time
4.  Bill for actual consumption

**What happens when credits are exhausted?**

Once the provisioned credits are exhausted, further consumption draws from the overdraft balance up to its configured limit. Configure overdraft behavior for a credit unit using [**is\_unlimited**](#is_unlimited) and [**overdraft\_amount**](#overdraft_amount), so customers can continue consuming, purchase more, or pay for overage depending on your setup.

## Sample Credit unit

```json
{
  "credit_unit": {
    "id": "ai_tokens_001",
    "name": "AI tokens",
    "external_name": "AI tokens",
    "status": "active",
    "resource_version": 1784633640000,
    "is_unlimited": false,
    "overdraft_amount": "1000",
    "created_at": 1784633586,
    "created_by": "sample.user@chargebee.com",
    "updated_at": 1784633640,
    "updated_by": "sample.user@chargebee.com"
  }
}
```

## Credit Units attributes

## Input Parameters

- `id` (required, string, max chars=50)
  A unique and immutable identifier for the credit unit.

- `name` (required, string, max chars=50)
  Internal display name for the credit unit. This must be unique across the site.

- `external_name` (required, string, max chars=50)
  Customer-facing display name for the credit unit. This must be unique across the site. If not provided during creation, `name` is used as the default.

- `status` (optional, enumerated string)
  The current lifecycle status of the credit unit.
  Possible enum values:
    - `active`
      Grant configuration for items and grant configuration overrides at subscription layer can be created for active credit units.
    - `archived`
      Grant configuration for items and grant configuration overrides at subscription layer cannot be created for archived credit units. Already configured grants for credit units continue to be effective.

- `resource_version` (optional, long)
  The version number of this resource. For every change made to the resource, `resource_version` is updated with a new timestamp in milliseconds.

- `updated_at` (optional, timestamp(UTC) in seconds)
  The time at which the credit unit was last updated.

- `created_at` (required, timestamp(UTC) in seconds)
  The time at which the credit unit was created.

- `created_by` (optional, string, max chars=100)
  The source (or the user) from where the credit unit has been created.

- `updated_by` (optional, string, max chars=100)
  The source (or the user) from where the credit unit has been last updated.

- `is_unlimited` (required, boolean)
  Indicates whether this credit unit allows unlimited overdraft consumption. When `true`, grace consumption continues without a cap after the allocated grants are exhausted. When `false`, grace consumption is capped by `overdraft_amount`.

- `overdraft_amount` (optional, string, max chars=50)
  The amount up to which grace consumption is allowed after the allocated grants are exhausted. A positive decimal value that applies only when `is_unlimited` is `false`.