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

Currencies

Chargebee supports billing in over 100 currencies. On this page, you can find information about how currency units are expressed in the API, as well as some pointers to keep in mind when using multiple currencies.

Currency values

By default, the Chargebee API supports only whole numbers for currency values. To allow for fractional (decimal) values, you must enable the multi-decimal pricing feature. Additionally, the units in which currencies are expressed in the API depend on whether the currency is zero-decimal and whether multi-decimal pricing is enabled.

Whole number currency values

By default, Chargebee supports currency values in whole numbers; fractions are not supported. In the API, currency values can be identified by checking their data types. For all whole number currency values in this API, the data type is indicated as "in cents" in this documentation.

The specific unit used for the currency in the API depends on whether it is a zero-decimal currency:

  • Zero-decimal currencies: For currencies that do not have decimal subunits, such as the Japanese Yen (JPY), the amount must be provided in the major unit of the currency. The major unit of a currency is the unit represented by its ISO 4217 code. For example, to specify an amount of JPY 15, set the amount as 15.
  • Other currencies: For currencies that are not zero-decimal, Chargebee supports values up to two decimal places in the major unit of the currency. This value with two decimal places must be converted to an integer by multiplying it by 100. For example, $1.53 should be provided as 1.53 × 100, which is 150.

Fractional currency values

When multi-decimal pricing is enabled in Chargebee, you can work with fractional currency values using dedicated API parameters and attributes of the String type. Usually, these attributes and parameters have the suffix _in_decimal in their names. The value is expressed in the major unit of the currency, which is the unit represented by its ISO 4217 code. For example, $1.6782 should be provided as 1.6782. The maximum number of decimal places supported by the API can be configured in the admin console.

Note: For zero-decimal currencies, such as the Japanese Yen (JPY), decimal places are not allowed.

Rounding of invoice line item amounts

While Chargebee supports multiple decimal places for currency values, at the invoice line item-level, the amount attribute is always rounded off to two decimal places in the major unit of the currency. The major unit of a currency is the unit represented by its ISO 4217 code. The rounding logic used is ROUND_HALF_EVEN. For example, if the quantity is 0.0765 and unit_amount is $10.674, the line item amount is (0.0765×$10.674) = $0.816561 and is rounded off to $0.82.

Multi-currency support

By default, Chargebee is able to process transactions in only one currency. However, you can enable the multi-currency feature to support more currencies. The first currency enabled in Chargebee also becomes the "base currency" by default. If you have multiple currencies enabled and want to change the base currency for your site, reach out to Support for assistance.

Warning

For some API endpoints, the currency_code parameter becomes required when the multi-currency feature is enabled. Before enabling the feature for your site, ensure that you update your code to provide the currency_code parameter when calling the endpoints listed in the next section.

List of affected endpoints

The following endpoints require the currency_code parameter to be passed when the multi-currency feature has been enabled.