Currencies

Manage alternate currency display options on the storefront.

Definitions

Name	Description
Default Currency	Storeʼs default currency is the one from which any auto-conversion of pricing (product, tax, shipping, promotions) will happen.
Display Currency	Currency that is displayed on the storefront. This might or might not mean that shopper can actually transact in that currency. Display currency is also often called "presentment currency" in the payments industry.
Transactional Currency	Transactional currency is what currency and amount BC passes to the payment provider and the currency/amount that the shopper will be charged to their bank account. If thereʼs a discrepancy between the storefront display currency and the transactional currency, a shopper has to pay a conversion fee and the conversion rate that will be used will be outside of BCʼs purview.
Settlement Currency	This is the currency in which the merchant gets paid out to their bank account. If thereʼs a discrepancy between the currency that shopper transacts in and the currency in which merchant settles, merchant has to pay a conversion fee and the conversion rate used will be outside of BCʼs purview. Merchant is able to set their settlement currency through their payment provider.
BigCommerce Conversion Rate	Any conversion rate set on BigCommerce used to convert product’s default currency pricing into a new non-default currency. Conversion rate could be static or dynamic.
Static Conversion Rate	One of the two auto-converted pricing options. If a merchant manually enters a static conversion rate, then the conversion rate will remain the same until/unless merchant updates their currency settings to use a different conversion rate. The advantage of using this method is to avoid constantly fluctuating price in non-default currencies.
Dynamic Conversion Rate	One of the two auto-converted pricing options. If a merchant selects a dynamic conversion rate, theyʼve tied themselves to a currency conversion service, which will update the conversion rate at a certain frequency. This helps shopper-facing pricing remain most aligned to the storeʼs default currency and keeps non-default currency conversion rate at market rate. Merchant can either use BigCommerce Currency Service provided in the Currency setup page, or they can use API to automatically update the exchange rate from their trusted source.
Bank Conversion Rate	Conversion rate used by merchant’s or shopper’s payment or credit card provider when auto-converting from store’s transactional currency. This rate might not align to the BC conversion rate and BC has no visibility into it.
Multi Currency Pricing	Rather than opting for auto-converting product pricing from default currency using BC conversion rate, merchant has a choice to set price per product per currency. This will be implemented through price lists.

FAQ

Do Multi-Currency settings work with the Checkout SDK?
The Checkout SDK works with multi-currency. There is no additional setup needed for the SDK. After setting up currency in the Control Panel the SDK will work as normal.

Resources

How Currencies Work
Price List API
Using Price Lists (opens in a new tab) (BigCommerce Knowledge Base)
Managing Currencies (opens in a new tab) (BigCommerce Knowledge Base)
Tax (opens in a new tab) (BigCommerce Knowledge Base)

Get a Currency

GET https://api.bigcommerce.com/stores/{store_hash}/v2/currencies/{id}

Request

Returns a single Currency.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
Accept in header with default of application/json - string - required
id in path - string - required
Currency ID

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/currencies/[id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

application/json

is_defaultboolean
Specifies the store’s default currency display format. For write operations, only true value is accepted. When set to true, it cannot be unset, only overridden.
Example: false
country_iso2string
2-letter ISO Alpha-2 code for this currency’s country.
Example: EU
currency_codestring
required
3-letter ISO 4217 code for this currency.
Example: EUR
currency_exchange_ratestring
required
Amount of this currency that is equivalent to one U.S. dollar.(Float, Float as String, Integer)
Example: 0.849
auto_updateboolean
Specifies whether to use the Open Exchange Rates service to update the currency conversion. A value of false specifies a static conversion value. auto_update only applies to non-transactional currencies.
Example: true
token_locationstring
required
Specifies whether this currency’s symbol appears to the “left” or “right” of the numeric amount.
Example: left
tokenstring
required
Symbol for this currency.
Example: €
decimal_tokenstring
required
Symbol used as the decimal separator in this currency.
Example: .
thousands_tokenstring
required
Symbol used as the thousands separator in this currency.
Example: ,
decimal_placesinteger
required
Number of decimal places to show for this currency.
Example: 2
namestring
required
Name of the currency.
Example: Euro
enabledboolean
If the currency is active on the store.
Example: false
is_transactionalboolean
Indicates if the currency is set as transactional or not. False means display only currency
Example: false

idinteger
ID of the currency. Read only.
Example: 2
last_updatedstring
Date the currency was last updated, created or modified.

example

{
  "id": 2,
  "is_default": false,
  "last_updated": "2019-08-24T14:15:22Z",
  "country_iso2": "EU",
  "currency_code": "EUR",
  "currency_exchange_rate": "0.849",
  "auto_update": true,
  "token_location": "left",
  "token": "€",
  "decimal_token": ".",
  "thousands_token": ",",
  "decimal_places": 2,
  "name": "Euro",
  "enabled": false
}

Update a Currency

PUT https://api.bigcommerce.com/stores/{store_hash}/v2/currencies/{id}

Request

Updates a Currency.

Read-Only Fields

id
date_created
date_modified
currency_code

The is_default property can only be set to true. The value of is_default cannot be unset, only overridden.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
id in path - string - required
Currency ID
Content-Type in header with default of application/json - string - required

Body

object | application/json

Currency Object

is_defaultboolean
Specifies the store’s default currency display format. For write operations, only true value is accepted. When set to true, it cannot be unset, only overridden.
Example: false
country_iso2string
2-letter ISO Alpha-2 code for this currency’s country.
Example: EU
currency_codestring
required
3-letter ISO 4217 code for this currency.
Example: EUR
currency_exchange_ratestring
required
Amount of this currency that is equivalent to one U.S. dollar.(Float, Float as String, Integer)
Example: 0.849
auto_updateboolean
Specifies whether to use the Open Exchange Rates service to update the currency conversion. A value of false specifies a static conversion value. auto_update only applies to non-transactional currencies.
Example: true
token_locationstring
required
Specifies whether this currency’s symbol appears to the “left” or “right” of the numeric amount.
Example: left
tokenstring
required
Symbol for this currency.
Example: €
decimal_tokenstring
required
Symbol used as the decimal separator in this currency.
Example: .
thousands_tokenstring
required
Symbol used as the thousands separator in this currency.
Example: ,
decimal_placesinteger
required
Number of decimal places to show for this currency.
Example: 2
namestring
required
Name of the currency.
Example: Euro
enabledboolean
If the currency is active on the store.
Example: false
is_transactionalboolean
Indicates if the currency is set as transactional or not. False means display only currency
Example: false

example

{
  "id": 2,
  "is_default": false,
  "last_updated": "Tue, 12 Jun 2018 14:41:56 +0000\"",
  "country_iso2": "EU",
  "currency_code": "EUR",
  "currency_exchange_rate": "0.849",
  "auto_update": true,
  "token_location": "left",
  "token": "€",
  "decimal_token": ".",
  "thousands_token": ",",
  "decimal_places": 2,
  "name": "Euro",
  "enabled": false
}

Response

Body

application/json

is_defaultboolean
Specifies the store’s default currency display format. For write operations, only true value is accepted. When set to true, it cannot be unset, only overridden.
Example: false
country_iso2string
2-letter ISO Alpha-2 code for this currency’s country.
Example: EU
currency_codestring
required
3-letter ISO 4217 code for this currency.
Example: EUR
currency_exchange_ratestring
required
Amount of this currency that is equivalent to one U.S. dollar.(Float, Float as String, Integer)
Example: 0.849
auto_updateboolean
Specifies whether to use the Open Exchange Rates service to update the currency conversion. A value of false specifies a static conversion value. auto_update only applies to non-transactional currencies.
Example: true
token_locationstring
required
Specifies whether this currency’s symbol appears to the “left” or “right” of the numeric amount.
Example: left
tokenstring
required
Symbol for this currency.
Example: €
decimal_tokenstring
required
Symbol used as the decimal separator in this currency.
Example: .
thousands_tokenstring
required
Symbol used as the thousands separator in this currency.
Example: ,
decimal_placesinteger
required
Number of decimal places to show for this currency.
Example: 2
namestring
required
Name of the currency.
Example: Euro
enabledboolean
If the currency is active on the store.
Example: false
is_transactionalboolean
Indicates if the currency is set as transactional or not. False means display only currency
Example: false

idinteger
ID of the currency. Read only.
Example: 2
last_updatedstring
Date the currency was last updated, created or modified.

example

{
  "id": 2,
  "is_default": false,
  "last_updated": "2019-08-24T14:15:22Z",
  "country_iso2": "EU",
  "currency_code": "EUR",
  "currency_exchange_rate": "0.849",
  "auto_update": true,
  "token_location": "left",
  "token": "€",
  "decimal_token": ".",
  "thousands_token": ",",
  "decimal_places": 2,
  "name": "Euro",
  "enabled": false
}

Delete a Currency

DELETE https://api.bigcommerce.com/stores/{store_hash}/v2/currencies/{id}

Request

Deletes a Currency.

If a currencyʼs is_default property is set to true, this currency cannot be deleted.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
Accept in header with default of application/json - string - required
id in path - string - required
Currency ID

example

curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/currencies/[id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

example

{}

Get All Currencies

GET https://api.bigcommerce.com/stores/{store_hash}/v2/currencies

Request

Returns a list of all store Currency.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
Accept in header with default of application/json - string - required

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/currencies' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

array | application/json

example

[
  {
    "id": 2,
    "is_default": false,
    "last_updated": "2019-08-24T14:15:22Z",
    "country_iso2": "EU",
    "currency_code": "EUR",
    "currency_exchange_rate": "0.849",
    "auto_update": true,
    "token_location": "left",
    "token": "€",
    "decimal_token": ".",
    "thousands_token": ",",
    "decimal_places": 2,
    "name": "Euro",
    "enabled": false
  }
]

Create a Currency

POST https://api.bigcommerce.com/stores/{store_hash}/v2/currencies

Request

Creates Currency.

Required Fields

name
currency_code
currency_exchange_rate
token_location
token
decimal_token
thousands_token
decimal_places

Read-Only Fields

id
date_created
date_modified

The is_default property can only be set to true. The value of is_default cannot be unset, only overridden. To change the storeʼs default currency in the BigCommerce control panel, please see Managing Currencies.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
Content-Type in header with default of application/json - string - required

Body

object | application/json

Currency Object

is_defaultboolean
Specifies the store’s default currency display format. For write operations, only true value is accepted. When set to true, it cannot be unset, only overridden.
Example: false
country_iso2string
2-letter ISO Alpha-2 code for this currency’s country.
Example: EU
currency_codestring
required
3-letter ISO 4217 code for this currency.
Example: EUR
currency_exchange_ratestring
required
Amount of this currency that is equivalent to one U.S. dollar.(Float, Float as String, Integer)
Example: 0.849
auto_updateboolean
Specifies whether to use the Open Exchange Rates service to update the currency conversion. A value of false specifies a static conversion value. auto_update only applies to non-transactional currencies.
Example: true
token_locationstring
required
Specifies whether this currency’s symbol appears to the “left” or “right” of the numeric amount.
Example: left
tokenstring
required
Symbol for this currency.
Example: €
decimal_tokenstring
required
Symbol used as the decimal separator in this currency.
Example: .
thousands_tokenstring
required
Symbol used as the thousands separator in this currency.
Example: ,
decimal_placesinteger
required
Number of decimal places to show for this currency.
Example: 2
namestring
required
Name of the currency.
Example: Euro
enabledboolean
If the currency is active on the store.
Example: false
is_transactionalboolean
Indicates if the currency is set as transactional or not. False means display only currency
Example: false

example

{
  "id": 2,
  "is_default": false,
  "last_updated": "Tue, 12 Jun 2018 14:41:56 +0000\"",
  "country_iso2": "EU",
  "currency_code": "EUR",
  "currency_exchange_rate": "0.849",
  "auto_update": true,
  "token_location": "left",
  "token": "€",
  "decimal_token": ".",
  "thousands_token": ",",
  "decimal_places": 2,
  "name": "Euro",
  "enabled": false
}

Response

Body

application/json

is_defaultboolean
Specifies the store’s default currency display format. For write operations, only true value is accepted. When set to true, it cannot be unset, only overridden.
Example: false
country_iso2string
2-letter ISO Alpha-2 code for this currency’s country.
Example: EU
currency_codestring
required
3-letter ISO 4217 code for this currency.
Example: EUR
currency_exchange_ratestring
required
Amount of this currency that is equivalent to one U.S. dollar.(Float, Float as String, Integer)
Example: 0.849
auto_updateboolean
Specifies whether to use the Open Exchange Rates service to update the currency conversion. A value of false specifies a static conversion value. auto_update only applies to non-transactional currencies.
Example: true
token_locationstring
required
Specifies whether this currency’s symbol appears to the “left” or “right” of the numeric amount.
Example: left
tokenstring
required
Symbol for this currency.
Example: €
decimal_tokenstring
required
Symbol used as the decimal separator in this currency.
Example: .
thousands_tokenstring
required
Symbol used as the thousands separator in this currency.
Example: ,
decimal_placesinteger
required
Number of decimal places to show for this currency.
Example: 2
namestring
required
Name of the currency.
Example: Euro
enabledboolean
If the currency is active on the store.
Example: false
is_transactionalboolean
Indicates if the currency is set as transactional or not. False means display only currency
Example: false

idinteger
ID of the currency. Read only.
Example: 2
last_updatedstring
Date the currency was last updated, created or modified.

example

{
  "id": 2,
  "is_default": false,
  "last_updated": "2019-08-24T14:15:22Z",
  "country_iso2": "EU",
  "currency_code": "EUR",
  "currency_exchange_rate": "0.849",
  "auto_update": true,
  "token_location": "left",
  "token": "€",
  "decimal_token": ".",
  "thousands_token": ",",
  "decimal_places": 2,
  "name": "Euro",
  "enabled": false
}

Delete All Currencies

DELETE https://api.bigcommerce.com/stores/{store_hash}/v2/currencies

Request

Deletes all non-default store currencies.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
Accept in header with default of application/json - string - required

example

curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/currencies' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

example

{}

Currencies

Definitions

FAQ

Resources

Get a Currency

Request

Authentication

Parameters

example

Response

Body

is_defaultboolean

country_iso2string

currency_codestringrequired

currency_exchange_ratestringrequired

auto_updateboolean

token_locationstringrequired

tokenstringrequired

decimal_tokenstringrequired

thousands_tokenstringrequired

decimal_placesintegerrequired

namestringrequired

enabledboolean

is_transactionalboolean

idinteger

last_updatedstring

example

Update a Currency

Request

Authentication

Parameters

Body

is_defaultboolean

country_iso2string

currency_codestringrequired

currency_exchange_ratestringrequired

auto_updateboolean

token_locationstringrequired

tokenstringrequired

decimal_tokenstringrequired

thousands_tokenstringrequired

decimal_placesintegerrequired

namestringrequired

enabledboolean

is_transactionalboolean

example

Response

Body

is_defaultboolean

country_iso2string

currency_codestringrequired

currency_exchange_ratestringrequired

auto_updateboolean

token_locationstringrequired

tokenstringrequired

decimal_tokenstringrequired

thousands_tokenstringrequired

decimal_placesintegerrequired

namestringrequired

enabledboolean

is_transactionalboolean

idinteger

last_updatedstring

example

Delete a Currency

Request

Authentication

Parameters

example

Response

Body

example

Get All Currencies

Request

Authentication

Parameters

example

Response

Body

example

currency_codestring
required

currency_exchange_ratestring
required

token_locationstring
required

tokenstring
required

decimal_tokenstring
required

thousands_tokenstring
required

decimal_placesinteger
required

namestring
required

currency_codestring
required

currency_exchange_ratestring
required

token_locationstring
required

tokenstring
required

decimal_tokenstring
required

thousands_tokenstring
required

decimal_placesinteger
required

namestring
required

currency_codestring
required

currency_exchange_ratestring
required

token_locationstring
required

tokenstring
required

decimal_tokenstring
required

thousands_tokenstring
required

decimal_placesinteger
required

namestring
required

currency_codestring
required

currency_exchange_ratestring
required

token_locationstring
required

tokenstring
required

decimal_tokenstring
required

thousands_tokenstring
required

decimal_placesinteger
required

namestring
required

currency_codestring
required

currency_exchange_ratestring
required

token_locationstring
required

tokenstring
required

decimal_tokenstring
required

thousands_tokenstring
required

decimal_placesinteger
required

namestring
required