Go Headless

Build Apps

Client

API Preview

Develop Websites

REST

Velo

GraphQL (Alpha)

Identifying details needed to determine which currency rate to convert. The combination of the `from` and `to` properties together comprise the unique ID.

identifiers

ConvertCurrencyIdentifiers

amounts

Returns an array of amounts converted from the original (`from`) currency to the target (`to`) currency and the timestamp for the conversion rate used.


Use the `convertCurrency()` function to convert an array of one or more amounts between two currencies. The `convertCurrency()` function returns an array of converted amounts and the timestamp for the conversion rate used.

> **Note**:  The currency codes used must exist in the array of supported currencies returned by the [`listCurrencies()`](#listcurrencies) function.

import { currencies } from 'wix-ecom.v2';

const identifiers = {
  'from': 'USD',
  'to': 'GBP'
};

const amounts =	[ 
  {
    'decimalPlaces': 2,
    'value': '1000'
  },
  {
    'decimalPlaces': 2,
    'value': '20324'
  } 
];

currencies.convertCurrency(identifiers, amounts)
  .then((convertedAmounts) => {
    const firstConvertedAmount = convertedAmounts.amounts[0];
    const timestamp = convertedAmounts.rateTimestamp;
  });

/* Promise resolves to: 
 * {
 *   "amounts": [
 *     {
 *       "decimalPlaces": 2,
 *       "value": "795"
 *     },
 *     {
 *       "decimalPlaces": 2,
 *       "value": "1616287"
 *     } 
 *   ],
 *   "rateTimestamp": "2023-04-30T21:00:00.277Z"
 * }
 */

Convert an array of amounts from one currency to another (dashboard page code)

import { Permissions, webMethod } from 'wix-web-module';
import { currencies } from 'wix-ecom.v2';

export const convertCurrency = webMethod(Permissions.Anyone, async (identifiers, amounts) => {
  try {
    const convertedAmounts = await currencies.convertCurrency(identifiers, amounts);
    const firstConvertedAmount = convertedAmounts.amounts[0];
    const timestamp = convertedAmounts.rateTimestamp;

    return convertedAmounts;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
});

const identifiers = {
  'from': 'USD',
  'to': 'GBP'
};

const amounts =	[ 
  {
    'decimalPlaces': 2,
    'value': '1000'
  },
  {
    'decimalPlaces': 2,
    'value': '20324'
  } 
];

convertCurrency(identifiers, amounts)
  .then((convertedAmounts) => {
    const firstConvertedAmount = convertedAmounts.amounts[0];
    const timestamp = convertedAmounts.rateTimestamp;
  });

/* Promise resolves to: 
 * {
 *   "amounts": [
 *     {
 *       "decimalPlaces": 2,
 *       "value": "795"
 *     },
 *     {
 *       "decimalPlaces": 2,
 *       "value": "1616287"
 *     } 
 *   ],
 *   "rateTimestamp": "2023-04-30T21:00:00.277Z"
 * }
 */


Convert an array of amounts from one currency to another (export from backend code)

convertCurrency

ConvertCurrencyResponse

Identifying details needed to get the conversion rate. The combination of the `from` and `to` properties together comprise the unique ID.

GetConversionRateIdentifiers

Returns the conversion rate between 2 currencies.

import { currencies } from 'wix-ecom.v2';
  
currencies.getConversionRate('USD', 'GBP')
  .then((conversionRate) => {
    const rate = conversionRate.rate;
    const timestamp = conversionRate.rateTimestamp;
  });

/* Promise resolves to:
 *  {
 *    "rate": {
 *       value: "20",
 *       decimalPlaces: 2
 *    },
 *    "rateTimestamp": "2020-03-15T20:00:00.181Z"
 *  }
 */

Return the conversion rate and timestamp (dashboard page code)

import { Permissions, webMethod } from 'wix-web-module';
import { currencies } from 'wix-ecom.v2';

export const getConversionRate = webMethod(Permissions.Anyone, async () => {
  try {
    const conversionRate = await currencies.getConversionRate('USD', 'GBP');
    const rate = conversionRate.rate;
    const timestamp = conversionRate.rateTimestamp;

    return conversionRate;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
});

getConversionRate()
  .then((conversionRate) => {
    const rate = conversionRate.rate;
    const timestamp = conversionRate.rateTimestamp;
  });

/* Promise resolves to:
 *  {
 *    "rate": {
 *       value: "20",
 *       decimalPlaces: 2
 *    },
 *    "rateTimestamp": "2020-03-15T20:00:00.181Z"
 *  }
 */


Return the conversion rate and timestamp (export from backend code)

getConversionRate

ConversionRateResponse

Returns an array of currencies. The array lists all currencies for which Wix supports conversion and their symbols.

import { currencies } from 'wix-ecom.v2';

currencies.listCurrencies()
  .then((listOfAllCurrencies) => {
    const firstCurrencyCode = listOfAllCurrencies[0].code;
    const firstCurrencyCSymbol = listOfAllCurrencies[0].symbol;
  });

/*
 *  Promise resolves to:
 *  {
 *    "currencies": [
 *      {"code": "EUR", "symbol": "€"},
 *      {"code": "USD", "symbol": "$"},
 *      {"code": "JPY", "symbol": "¥"}
 *    ]
 *  }
 */

Get all supported currencies (dashboard page code)

import { Permissions, webMethod } from 'wix-web-module';
import { currencies } from 'wix-ecom.v2';

export const listCurrencies = webMethod(Permissions.Anyone, async () => {
  try {
    const listOfAllCurrencies = await currencies.listCurrencies();
    const firstCurrencyCode = listOfAllCurrencies[0].code;
    const firstCurrencyCSymbol = listOfAllCurrencies[0].symbol;

    return listOfAllCurrencies;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
});

listCurrencies()
  .then((listOfAllCurrencies) => {
    const firstCurrencyCode = listOfAllCurrencies[0].code;
    const firstCurrencyCSymbol = listOfAllCurrencies[0].symbol;
  });

/*
 *  Promise resolves to:
 *  {
 *    "currencies": [
 *      {"code": "EUR", "symbol": "€"},
 *      {"code": "USD", "symbol": "$"},
 *      {"code": "JPY", "symbol": "¥"}
 *    ]
 *  }
 */


Get all supported currencies (export from backend code)

listCurrencies

ListCurrenciesResponse

---
title: Introduction
---

# About the Wix Currencies API


The Currencies API is used to convert from one currency to another and get exchange rates. 

 Currency rates are provided by [XE](https://www.xe.com/company/) and are updated on a daily basis. Rates are provided together with the timestamp when they were set. By using the Currencies API you agree to XE's [Terms of Use](https://www.xe.com/en/legal/dfs.php).

 The Currencies API provides these functions: 


- Use [`listCurrencies()`](wix-ecom-v2/currencies/listcurrencies) to get a list of all the convertible currencies.
- Use [`convertCurrency()`](wix-ecom-v2/currencies/convertcurrency) to convert amounts between two currencies.
- Use [`getConversionRate()`](wix-ecom-v2/currencies/getconversionrate) to get today’s conversion rate for a pair of currencies.  


## Before you begin

+ To use the Currencies API you must upgrade your site to a [Premium Plan](https://support.wix.com/en/article/upgrading-your-site-to-premium-3066683). 

+ The currency converter changes the displayed prices on your site for different currencies but does not change the payment currency. The payment is always made in the [currency set in your site's Dashboard](https://support.wix.com/en/article/setting-your-currency-for-accepting-payments).

+ The currency codes used must exist in the array of supported currencies returned by the [`listCurrencies()`](wix-ecom-v2/currencies/listcurrencies) function.

+ To use the Currencies API, import `{ currencies }` from the `wix-ecom.v2` module:

    ```javascript
    import { currencies } from 'wix-ecom.v2';
    ```


## Use case: Display prices in different currencies

 The API can be used, for example, with the [currency conversion dropdown](https://support.wix.com/en/article/adding-and-setting-up-a-currency-converter-in-wix-stores) element on your Wix Stores page to display prices in a range of different currencies. Selecting a different currency from the dropdown on a Wix Stores page automatically updates all of the prices displayed on your store's page to the selected currency. While the currency converter dropdown works with your Wix Stores pages, the Currencies API can be used on any page.


## Terminology

+ **XE**. A [currency converter provider](https://www.xe.com/company/) that the Currencies API uses. 
+ **Currency code**: A 3-letter [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217) code representing each currency.


## Permissions information


The following functions in Currencies are restricted and only run if you elevate permissions using the `wix-auth` [`elevate()`](https://www.wix.com/velo/reference/wix-auth/elevate) function:

- [`listCurrencies()`](wix-ecom-v2/currencies/listcurrencies)
- [`convertCurrency()`](wix-ecom-v2/currencies/convertcurrency)
- [`getConversionRate()`](wix-ecom-v2/currencies/getconversionrate)
 

<blockquote class='warning'>
<p><strong>Warning:</strong> Elevating a function allows it to be called by any site visitor. Exercise caution to prevent security vulnerabilities.</p>
</blockquote>


velo-deps_wix-ecom.v2_currencies

rate

DecimalValue

Date and time the conversion rate was last updated.

rateTimestamp

Original currency to convert from as a 3-letter [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217) code. The `from` currency code must exist in the array returned by the [`listCurrencies()`](#listcurrencies) function.

from

string

Target currency to convert to as a 3-letter [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217) code.  The `to` currency code must exist in the array returned by the [`listCurrencies()`](#listcurrencies) function.

Currency

A 3-letter [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217) currency code.

code

symbol

Decimal places to apply. For example, the number of decimal places for `10.95`  is `2`.

decimalPlaces

number

The value without decimal points. For example, the number `10.95` becomes `1095`.

value

Original currency to get the rate for as a 3-letter [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217) code. The `from` currency code must exist in the array returned by the [`listCurrencies()`](#listcurrencies) function.

Target currency to get the rate for as a 3-letter [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217) code. The `to` currency code must exist in the array returned by the [`listCurrencies()`](#listcurrencies) function.

convertCurrency( )

Permission Scopes