Currencies

API Version

Product Catalog

Library

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.

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.

Customer-related endpoints

Invoice-related endpoints

Create an invoice

Product catalog-related endpoints

Sample currency [ JSON ]

{
    "currency": {
        "id": "cur_XpbNwDtU56AzUh3j",
        "currency_code": "USD",
        "is_base_currency": true,
        "forex_type": "auto"
    }
}

Model Class

ChargeBee::Currency

id

optional, string, max chars=40
Unique identifier of a currency.

enabled

boolean, default=true
This field mentions whether the foreign currency is active or archived. If the value is false the foreign currency is archived else it is active

forex_type

optional, enumerated string
This represents the exchange rate type set for the currency.

Possible values are

manualIf forex_type is manual, you will be able to set the conversion rate for the currency. You need to update the exchange rate each time your exchange rate provider changes itautoIf forex_type is auto, conversion rate will be auto updated by Chargebee every day with third party providers (using external currency conversion providers)

currency_code

optional, string, max chars=3
A three letter currency code. For example, GBR, INR, and more.

is_base_currency

optional, boolean, default=false
Check whether this is a base currency or not. The value of the attribute is true when the currency matches the site's base currency.

manual_exchange_rate

optional, string, max chars=20
This attribute shows the exchange rate in decimal. When forex_type is manual you have to set the exchange rate for additional currencies in manual_exchange_rate field.

This API is used to retrieve the list of all currencies currently configured within the site.

Sample Codes

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::Currency.list({
  :limit => "5"
  })
currency = result.currency

copy

Click to Copy

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::Currency.list({
  :limit => "5"
  })
currency = result.currency

Sample Result [ JSON ]

{
    "list": [
        {
            "currency": {
                "id": "cur_XpbNwDtU56AzUh3j",
                "currency_code": "USD",
                "is_base_currency": true,
                "forex_type": "auto"
            }
        },
        {..}
    ]
}

Method

ChargeBee::Currency.list({<param name> => <value>,<param name> => <value> ...})

currency

always returned
Resource object representing currency

This API is used to retrieve an individual currency object configured within this site.

Sample Codes

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::Currency.retrieve("cur_XpbNwDtU56AzUh3j")
currency = result.currency

copy

Click to Copy

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::Currency.retrieve("cur_XpbNwDtU56AzUh3j")
currency = result.currency

Sample Result [ JSON ]

{
    "currency": {
        "id": "cur_XpbNwDtU56AzUh3j",
        "currency_code": "EUR",
        "is_base_currency": false,
        "forex_type": "manual",
        "manual_exchange_rate": "1.234784"
    }
}

Method

ChargeBee::Currency.retrieve(<site_currency_id>,{<param name> => <value>,<param name> => <value> ...})

currency

always returned
Resource object representing currency

This API is used to add a new currency to your Chargebee site. Prior to using this API, ensure that the multi-currency feature is enabled.
If the forex_type is set to manual, you can specify the manual_exchange_rate. Additionally, the currency code provided must adhere to the three-letter ISO standard currency codes.

Sample Codes

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::Currency.create({
  :currency_code => "EUR",
  :forex_type => "MANUAL",
  :manual_exchange_rate => "1.234784"
  })
currency = result.currency

copy

Click to Copy

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::Currency.create({
  :currency_code => "EUR",
  :forex_type => "MANUAL",
  :manual_exchange_rate => "1.234784"
  })
currency = result.currency

Sample Result [ JSON ]

{
    "currency": {
        "id": "cur_XpbNwDtU56AzUh3j",
        "currency_code": "EUR",
        "is_base_currency": false,
        "forex_type": "manual",
        "manual_exchange_rate": "1.234784"
    }
}

Method

ChargeBee::Currency.create({<param name> => <value>,<param name> => <value> ...})

currency_code[]

required, string, max chars=3
A three letter currency code. For example, GBR, INR, and more.

forex_type[]

required, enumerated string
This represents the exchange rate type set for the currency.

Possible values are

manual_exchange_rate[]

optional, string, max chars=20
This parameter allows you to pass the exchange rate in decimal format. When forex_type is manual you have to set the exchange rate for additional currencies in manual_exchange_rate parameter. A maximum of nine decimal values are allowed to pass in this field.

currency

always returned
Resource object representing currency

This API is used to update the configured currencies within your Chargebee site. Additionally, If the forex_type is set to manual, you can specify the manual_exchange_rate.

Sample Codes

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::Currency.update("cur_XpbNwDtU56AzUh3j",{
  :forex_type => "MANUAL",
  :manual_exchange_rate => "1.234784"
  })
currency = result.currency

copy

Click to Copy

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::Currency.update("cur_XpbNwDtU56AzUh3j",{
  :forex_type => "MANUAL",
  :manual_exchange_rate => "1.234784"
  })
currency = result.currency

Sample Result [ JSON ]

{
    "currency": {
        "id": "cur_XpbNwDtU56AzUh3j",
        "currency_code": "EUR",
        "is_base_currency": false,
        "forex_type": "manual",
        "manual_exchange_rate": "1.234784"
    }
}

Method

ChargeBee::Currency.update(<site_currency_id>,{<param name> => <value>,<param name> => <value> ...})

forex_type[]

required, enumerated string
This represents the exchange rate type set for the currency.

Possible values are

manual_exchange_rate[]

optional, string, max chars=20
TThis parameter allows you to pass the exchange rate in decimal format. When forex_type is manual you have to set the exchange rate for additional currencies in manual_exchange_rate parameter. A maximum of nine decimal values are allowed to pass in this field.

currency

always returned
Resource object representing currency

This API is used to schedule exchange rate modification for a manual forex_type currency.

Sample Codes

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::Currency.add_schedule("cur_XpbNwDtU56AzUh3j",{
  :manual_exchange_rate => "1.234784",
  :schedule_at => 1608209339
  })
currency = result.currency

copy

Click to Copy

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::Currency.add_schedule("cur_XpbNwDtU56AzUh3j",{
  :manual_exchange_rate => "1.234784",
  :schedule_at => 1608209339
  })
currency = result.currency

Sample Result [ JSON ]

{
    "scheduled_at": "1608209339",
    "currency": {
        "id": "cur_XpbNwDtU56AzUh3j",
        "currency_code": "EUR",
        "is_base_currency": false,
        "forex_type": "manual",
        "manual_exchange_rate": "1.234784"
    }
}

Method

ChargeBee::Currency.add_schedule(<site_currency_id>,{<param name> => <value>,<param name> => <value> ...})

manual_exchange_rate[]

required, string, max chars=20
This parameter allows you to pass the exchange rate in decimal format. When forex_type is manual you have to set the exchange rate for additional currencies in manual_exchange_rate parameter. A maximum of nine decimal values are allowed to pass in this field.

schedule_at[]

required, timestamp(UTC) in seconds
Timestamp at which the exchange rate scheduled has to be updated in your site. This timestamp must be a future date.

scheduled_at

required, timestamp(UTC) in seconds

currency

always returned
Resource object representing currency

This API allows you to remove a scheduled exchange rate from a currency.

Sample Codes

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::Currency.remove_schedule("cur_XpbNwDtU56AzUh3j")
currency = result.currency

copy

Click to Copy

 
require 'chargebee'
ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")
result = ChargeBee::Currency.remove_schedule("cur_XpbNwDtU56AzUh3j")
currency = result.currency

Sample Result [ JSON ]

{
    "scheduled_at": "1608209339",
    "currency": {
        "id": "cur_XpbNwDtU56AzUh3j",
        "currency_code": "EUR",
        "is_base_currency": false,
        "forex_type": "manual",
        "manual_exchange_rate": "1.234784"
    }
}

Method

ChargeBee::Currency.remove_schedule(<site_currency_id>,{<param name> => <value>,<param name> => <value> ...})

scheduled_at

required, timestamp(UTC) in seconds

currency

always returned
Resource object representing currency

Currency values

Whole number currency values

Fractional currency values

Rounding of invoice line item amounts

Multi-currency support

List of affected endpoints

Sample currency [ JSON ]

API Index URL GET

Model Class

Currency attributes

Consent Fields for Currency

Custom Fields for Currency

List currencies ¶

Notes

Sample Result [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Retrieve a currency ¶

Notes

Sample Result [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Add a new currency ¶

Notes

Sample Result [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Update a currency ¶

Notes

Sample Result [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Add schedule ¶

Notes

Sample Result [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

Remove schedule ¶

Notes

Sample Result [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL