Docs
Management API
Currencies

Currencies

Manage alternate currency display options on the storefront.

Definitions

NameDescription
Default CurrencyStoreʼs default currency is the one from which any auto-conversion of pricing (product, tax, shipping, promotions) will happen.
Active CurrencyShopper selected currency on the storefront. This might or might not mean that shopper can actually transact in that currency. Active currency is also often called "presentment currency" in the payments industry.
Transactional CurrencyTransactional currency is what currency and amount BigCommerce 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 active 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 BigCommerceʼs purview.
Settlement CurrencyThis 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 BigCommerceʼs purview. Merchant is able to set their settlement currency through their payment provider.
BigCommerce Conversion RateAny 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 RateOne 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 RateOne 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 RateConversion 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 with the BigCommerce conversion rate and BigCommerce has no visibility into it.
Multi Currency PricingRather than opting for auto-converting product pricing from default currency using BigCommerce 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

Get a Currency

GET /currencies/{id}

Request

Returns a single Currency.

Authentication

  • X-Auth-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
  • id in path - string
    required
    The ID of the subject currency.

example

Response

Body

object | application/json
Currency Object

  • is_default    boolean

    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.

  • country_iso2    string

    2-letter ISO Alpha-2 code for this currency’s country.
    Example: EU

  • default_for_country_codes    array[string]

    Default 3-letter ISO 4217 code for this currency.
    Type: array[string]
    Example: ["EU"]

  • currency_code    string

    3-letter ISO 4217 code for this currency.
    Example: EUR

  • currency_exchange_rate    string

    Amount of this currency that is equivalent to one U.S. dollar.(Float, Float as String, Integer)
    Example: 0.849

  • auto_update    boolean

    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_location    string

    Specifies whether this currency’s symbol appears to the “left” or “right” of the numeric amount.
    Example: left

  • token    string

    Symbol for this currency.
    Example: €

  • decimal_token    string

    Symbol used as the decimal separator in this currency.
    Example: .

  • thousands_token    string

    Symbol used as the thousands separator in this currency.
    Example: ,

  • decimal_places    integer

    Number of decimal places to show for this currency.
    Example: 2

  • name    string

    Name of the currency.
    Example: Euro

  • enabled    boolean

    If the currency is active on the store.

  • is_transactional    boolean

    Indicates if the currency is set as transactional or not. False means display only currency
    Example: true

  • use_default_name    boolean

    Default currency name

  • id    integer
    read-only

    ID of the currency. Read only.
    Example: 2

  • last_updated    string
    read-only

    Date the currency was last updated, created or modified.

example

Update a Currency

PUT /currencies/{id}

Request

Updates a Currency.

Read-Only Fields

  • id
  • last_updated
  • 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

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
  • id in path - string
    required
    The ID of the subject currency.
  • Content-Type in header with default of application/json - string
    required

Body

object | application/json
Currency Object

  • is_default    boolean

    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.

  • country_iso2    string

    2-letter ISO Alpha-2 code for this currency’s country.
    Example: EU

  • currency_exchange_rate    string

    Amount of this currency that is equivalent to one U.S. dollar.(Float, Float as String, Integer)
    Example: 0.849

  • auto_update    boolean

    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_location    string

    Specifies whether this currency’s symbol appears to the “left” or “right” of the numeric amount.
    Example: left

  • token    string

    Symbol for this currency.
    Example: €

  • decimal_token    string

    Symbol used as the decimal separator in this currency.
    Example: .

  • thousands_token    string

    Symbol used as the thousands separator in this currency.
    Example: ,

  • decimal_places    integer

    Number of decimal places to show for this currency.
    Example: 2

  • name    string

    Name of the currency.
    Example: Euro

  • enabled    boolean

    If the currency is active on the store.

  • is_transactional    boolean

    Indicates if the currency is set as transactional or not. False means display only currency

example

Response

Body

object | application/json
Currency Object

  • is_default    boolean

    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.

  • country_iso2    string

    2-letter ISO Alpha-2 code for this currency’s country.
    Example: EU

  • default_for_country_codes    array[string]

    Default 3-letter ISO 4217 code for this currency.
    Type: array[string]
    Example: ["EU"]

  • currency_code    string

    3-letter ISO 4217 code for this currency.
    Example: EUR

  • currency_exchange_rate    string

    Amount of this currency that is equivalent to one U.S. dollar.(Float, Float as String, Integer)
    Example: 0.849

  • auto_update    boolean

    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_location    string

    Specifies whether this currency’s symbol appears to the “left” or “right” of the numeric amount.
    Example: left

  • token    string

    Symbol for this currency.
    Example: €

  • decimal_token    string

    Symbol used as the decimal separator in this currency.
    Example: .

  • thousands_token    string

    Symbol used as the thousands separator in this currency.
    Example: ,

  • decimal_places    integer

    Number of decimal places to show for this currency.
    Example: 2

  • name    string

    Name of the currency.
    Example: Euro

  • enabled    boolean

    If the currency is active on the store.

  • is_transactional    boolean

    Indicates if the currency is set as transactional or not. False means display only currency
    Example: true

  • use_default_name    boolean

    Default currency name

  • id    integer
    read-only

    ID of the currency. Read only.
    Example: 2

  • last_updated    string
    read-only

    Date the currency was last updated, created or modified.

example

Delete a Currency

DELETE /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

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
  • id in path - string
    required
    The ID of the subject currency.

example

Response

Body

object | application/json

    example

    Get All Currencies

    GET /currencies

    Request

    Returns a list of all store Currency.

    Authentication

    • X-Auth-Token in header

    Parameters

    • store_hash in path - string
    • Accept in header with default of application/json - string
      required
    • page in query with default of 1 - integer

      Specifies the page number in a limited (paginated) list of currencies.

    • limit in query with default of 50 - integer

      Controls the number of items per page in a limited (paginated) list of currencies.

    example

    Response

    Body

    array | application/json

    • is_default      boolean

      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.

    • country_iso2      string

      2-letter ISO Alpha-2 code for this currency’s country.
      Example: EU

    • default_for_country_codes      array[string]

      Default 3-letter ISO 4217 code for this currency.
      Type: array[string]
      Example: ["EU"]

    • currency_code      string

      3-letter ISO 4217 code for this currency.
      Example: EUR

    • currency_exchange_rate      string

      Amount of this currency that is equivalent to one U.S. dollar.(Float, Float as String, Integer)
      Example: 0.849

    • auto_update      boolean

      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_location      string

      Specifies whether this currency’s symbol appears to the “left” or “right” of the numeric amount.
      Example: left

    • token      string

      Symbol for this currency.
      Example: €

    • decimal_token      string

      Symbol used as the decimal separator in this currency.
      Example: .

    • thousands_token      string

      Symbol used as the thousands separator in this currency.
      Example: ,

    • decimal_places      integer

      Number of decimal places to show for this currency.
      Example: 2

    • name      string

      Name of the currency.
      Example: Euro

    • enabled      boolean

      If the currency is active on the store.

    • is_transactional      boolean

      Indicates if the currency is set as transactional or not. False means display only currency
      Example: true

    • use_default_name      boolean

      Default currency name

    • id      integer
      read-only

      ID of the currency. Read only.
      Example: 2

    • last_updated      string
      read-only

      Date the currency was last updated, created or modified.

    example

    Create a Currency

    POST /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
    • last_updated

    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 (Help Center).

    Authentication

    • X-Auth-Token in header

    Parameters

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

    Body

    object | application/json
    Currency Object

    • is_default      boolean

      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.

    • country_iso2      string

      2-letter ISO Alpha-2 code for this currency’s country.
      Example: EU

    • currency_code      string
      required

      3-letter ISO 4217 code for this currency.
      Example: EUR

    • currency_exchange_rate      string
      required

      Amount of this currency that is equivalent to one U.S. dollar.(Float, Float as String, Integer)
      Example: 0.849

    • auto_update      boolean

      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_location      string
      required

      Specifies whether this currency’s symbol appears to the “left” or “right” of the numeric amount.
      Example: left

    • token      string
      required

      Symbol for this currency.
      Example: €

    • decimal_token      string
      required

      Symbol used as the decimal separator in this currency.
      Example: .

    • thousands_token      string
      required

      Symbol used as the thousands separator in this currency.
      Example: ,

    • decimal_places      integer
      required

      Number of decimal places to show for this currency.
      Example: 2

    • name      string
      required

      Name of the currency.
      Example: Euro

    • enabled      boolean

      If the currency is active on the store.

    • is_transactional      boolean

      Indicates if the currency is set as transactional or not. False means display only currency

    example

    Response

    Body

    object | application/json
    Currency Object

    • is_default      boolean

      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.

    • country_iso2      string

      2-letter ISO Alpha-2 code for this currency’s country.
      Example: EU

    • default_for_country_codes      array[string]

      Default 3-letter ISO 4217 code for this currency.
      Type: array[string]
      Example: ["EU"]

    • currency_code      string

      3-letter ISO 4217 code for this currency.
      Example: EUR

    • currency_exchange_rate      string

      Amount of this currency that is equivalent to one U.S. dollar.(Float, Float as String, Integer)
      Example: 0.849

    • auto_update      boolean

      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_location      string

      Specifies whether this currency’s symbol appears to the “left” or “right” of the numeric amount.
      Example: left

    • token      string

      Symbol for this currency.
      Example: €

    • decimal_token      string

      Symbol used as the decimal separator in this currency.
      Example: .

    • thousands_token      string

      Symbol used as the thousands separator in this currency.
      Example: ,

    • decimal_places      integer

      Number of decimal places to show for this currency.
      Example: 2

    • name      string

      Name of the currency.
      Example: Euro

    • enabled      boolean

      If the currency is active on the store.

    • is_transactional      boolean

      Indicates if the currency is set as transactional or not. False means display only currency
      Example: true

    • use_default_name      boolean

      Default currency name

    • id      integer
      read-only

      ID of the currency. Read only.
      Example: 2

    • last_updated      string
      read-only

      Date the currency was last updated, created or modified.

    example

    Delete All Currencies

    DELETE /currencies

    Request

    Deletes all non-default store currencies.

    Authentication

    • X-Auth-Token in header

    Parameters

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

    example

    Response

    Body

    object | application/json

      example

      See something you can improve? Edit this file on GitHub

      Did you find what you were looking for?
      Create Checkout TokenGet a Currency