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.
Display CurrencyCurrency 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 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 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 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
    required

Parameters

  • store_hash in path - string

example

Response

Body

application/json

example

Update a Currency

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

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

application/json

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
    required

Parameters

  • store_hash in path - string

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
      required

    Parameters

    • store_hash in path - string

    example

    Response

    Body

    array | application/json

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

      Authentication

      • X-Auth-Token in header
        required

      Parameters

      • store_hash in path - string

      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

      application/json

      example

      Delete All Currencies

      DELETE /currencies

      Request

      Deletes all non-default store currencies.

      Authentication

      • X-Auth-Token in header
        required

      Parameters

      • store_hash in path - string

      example

      Response

      Body

      object | application/json

        example

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