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
  • Accept in header with default of application/json - string
    required
  • id in path - string
    required

    The ID of the subject currency.

example

Response

Body

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

  • 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

  • id
    integer
    read-only

    ID of the currency. Read only.

    Example: 2

  • last_updated
    string

    Date the currency was last updated, created or modified.

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

    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

    • 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

    • id
      integer
      read-only

      ID of the currency. Read only.

      Example: 2

    • last_updated
      string

      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
        required

      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
          required

        Parameters

        • store_hash in path - string
        • 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

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

          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

          • 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

          • id
            integer
            read-only

            ID of the currency. Read only.

            Example: 2

          • last_updated
            string

            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
              required

            Parameters

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

            example

            Response

            Body

            object | application/json

              example

              Did you find what you were looking for?