Skip to main content

Multi-Currency Price Lists

Use multi-currency price lists to handle selling in different currencies on the same shop.

Instead of using a conversion rate to calculate the final price in different currencies, specify an absolute base price for each product or a currency conversion rate for each currency you wish to sell in. The customer selects their currency on the storefront (or the currency is auto-detected based on the customer's location), and the storefront displays product prices in the chosen currency where available.

Prerequisites​

Before you get started, complete the following steps:

  1. Install Bold's Price Rules Engine.
  2. To utilize the Price Rules Multi-Currency feature, two configuration flags need to be applied to your store by the Bold Price Rules team. Please contact Bold Support to create this request..
  3. Before using multi-currency price lists, read and understand the following guides:
    1. Managing Price Rules](/guides/price-rules/working-with-rulesets/managing-price-rules)
    2. Conditions
    3. Actions

Enable Multi-Currency​

You must enable the storefront's multi-currency functionality using the multi-currency flag before you apply any multi-currency price ruleset. Complete the following steps to enable multi-currency price rules and set a default currency for the storefront:

  1. Enable the multi-currency flag and set the multi_currency_default_currency by adding the following code to the bold-pr.liquid template:
<script>
window.BOLD = window.BOLD || {};
window.BOLD.pre = {
  config: {
    multi_currency: true,
    multi_currency_default_currency: "CAD",
  },
};
</script>
note

The multi_currency value above enables/disables the storefront's Price Rules currency functionality. If multi_currency is set to false, the store's default currency (set using multi_currency_default_currency) is used. Check your storefront in your browser's console to confirm that you have set the correct values for these flags. If they are undefined, you either added the script to the wrong file or you did not save the file.

  1. Confirm that you have Bold's Price Rules storefront build running by typing window.BOLD.pre in the browser's console. If you receive a WindowApi {...} object in return, you should be ready to get started.

Create multi-currency rulesets​

Rulesets identify products and variants that rules (also contained in the ruleset) apply to. Rules are defined by conditions (criteria that must be met before the rule is applied) and actions (actions that apply whenever the specified conditions are met for the products and variants in the applicable ruleset). For more information, refer to Rulesets and Rules.

Currency is an additional condition that you can attribute to a price rule.

Creating multi-currency price lists requires three additional components in a rule:

Currency in this ruleset functions as a condition. Price Rules only applies the action if the currency on the storefront matches the currency stated in the condition. Price Rules applies one of two actions if the currency condition is met:

  • PRICE_ADJUST_ABSOLUTE_BASE_PRICE
  • PRICE_ADJUST_RATE

To use these conditions and actions, set the rule type as BASE_PRICE.

Sample multi-currency rulesets​

PRICE_ADJUST_ABSOLUTE_BASE_PRICE​

The PRICE_ADJUST_ABSOLUTE_BASE_PRICE action supports the "price list" scenario. For example, if you want to set different prices for different regions individually, instead of setting up a conversion rate, use PRICE_ADJUST_ABSOLUTE_BASE_PRICE.

The following ruleset makes product 12345 cost £100 when the storefront is set to "GPB", or $150 when the storefront is set to "CAD". The rest of the rulesets apply on top of this base price.

{
  "ruleset": {
    "product_selection": {
      "type": "PRODUCT_SEARCH",
      "product_ids": ["12345"]
    },
    "rules": [
      {
        "conditions": [
          {
            "type": "CURRENCY",
            "value": "GBP"
          }
        ],
        "actions": [
          {
            "type": "PRICE_ADJUST_ABSOLUTE_BASE_PRICE",
            "value": 10000
          }
        ],
        "type": "BASE_PRICE"
      },
      {
        "conditions": [
          {
            "type": "CURRENCY",
            "value": "CAD"
          }
        ],
        "actions": [
          {
            "type": "PRICE_ADJUST_ABSOLUTE_BASE_PRICE",
            "value": 17000
          }
        ],
        "type": "BASE_PRICE"
      }
    ],
    "active": true,
    "priority": 100,
    "internal_name": "sample absolute base price ruleset"
  }
}

PRICE_ADJUST_RATE​

The PRICE_ADJUST_RATE action supports a "conversion rate" scenario. For example, if you want a different conversion rate to apply to a different region, use the PRICE_ADJUST_RATE action. The store's default currency is the base rate, which is then adjusted by the value in the PRICE_ADJUST_RATE action.

If a product is $100 in CAD (the store's default currency), the following ruleset sets the price of the product 12345 to £58 (100 x 0.58) when the storefront is set to "GPB", or $80 (100 x 0.8) when the storefront is set to "USD". The rest of rulesets apply on top of this base price.

{
  "ruleset": {
    "product_selection": {
      "type": "PRODUCT_SEARCH",
      "product_ids": ["12345"]
    },
    "rules": [
      {
        "conditions": [
          {
            "type": "CURRENCY",
            "value": "GBP"
          }
        ],
        "actions": [
          {
            "type": "PRICE_ADJUST_RATE",
            "value": 0.58
          }
        ],
        "type": "BASE_PRICE"
      },
      {
        "conditions": [
          {
            "type": "CURRENCY",
            "value": "USD"
          }
        ],
        "actions": [
          {
            "type": "PRICE_ADJUST_RATE",
            "value": 0.8
          }
        ],
        "type": "BASE_PRICE"
      }
    ],
    "active": true,
    "priority": 100,
    "internal_name": "sample adjust rate ruleset"
  }
}

Configure the storefront currency​

The commands for setting and clearing the storefront currency can be called in any store that uses Bold's Price Rules Engine and has the required pr.js script included. Call these commands either via the browser's console for testing purposes, or programmatically.

Set the storefront currency​

Use the following command to call the currency endpoint and save the new currency to the browser's localStorage for that store. If you do not manually set the currency on the storefront, then the default currency from the storefront or the multi_currency_default_currency script value is used.

window.BOLD.pre.setCurrency("CAD");
note

Find the list of available currency codes here: List of Currency Codes by Country (ISO 4217)

Clear the storefront currency​

Use the following command to clear the storefront currency. This is not a permanent clearing; it simply removes the currency data from the browser's localStorage, and Price Rules in turn makes a new request to retrieve new currency data the next time the page loads. This is a good way to clear and reset storefront currency data in case of any issues.

window.BOLD.pre.removeCurrencyData();

Competing rules and priority​

In the following example, there are two rules. Both rules are trying to set the base price of product 12345.

Price Rules figures out the best price; in this case, the best price is £58, which means the PRICE_ADJUST_RATE rule is applied.

If you don't want to offer the lowest price, specify a priority within a Rule. For more information on priority, refer to the priority section of the Price Rules Attributes guide.

{
  "ruleset": {
    "product_selection": {
      "type": "PRODUCT_SEARCH",
      "product_ids": ["12345"]
    },
    "rules": [
      {
        "conditions": [
          {
            "type": "CURRENCY",
            "value": "GBP"
          }
        ],
        "actions": [
          {
            "type": "PRICE_ADJUST_RATE",
            "value": 0.58
          }
        ],
        "type": "BASE_PRICE"
      },
      {
        "conditions": [
          {
            "type": "CURRENCY",
            "value": "GBP"
          }
        ],
        "actions": [
          {
            "type": "PRICE_ADJUST_ABSOLUTE_BASE_PRICE",
            "value": 60
          }
        ],
        "type": "BASE_PRICE"
      }
    ],
    "active": true,
    "priority": 100,
    "internal_name": "sample currency ruleset"
  }
}