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.
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.
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:
15
.
153
.
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.
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.
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.
currency_code
parameter to be passed when the multi-currency feature has been enabled.