Currencies

Chargebee's Multi-currency feature allows you to create Plans in multiple currencies, enabling your customers to conveniently pay in their preferred local currency. Please review this documentation to understand the multi-currency feature in Chargebee.

This currency resource contains exchange rate configurations associated with a specific currency. The multi-currency feature must be enabled, and all prerequisites must be addressed to successfully add a new currency via the API.
To invoke a single currency-specific API like update, retrieve, and more, the currency ID has to be passed as a path parameter. You can use list API to fetch the IDs of each currency configured in your site to use with the currency-specific APIs below. 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 x 100, which is 153.

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 x $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.

List of affected endpoints

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

• Customer-related endpoints

• Add promotional credits for a customer
• Deduct promotional credits from a customer
• Set promotional credits for a customer
• Record an excess payment for a customer

• Invoice-related endpoints

• Create an invoice

• Product catalog-related endpoints

• Create an item price
• Create a coupon