Vue Storefront is now Alokai! Learn More
Multi-currency overview

Multi-currency overview

The BigCommerce integration supports the usage of multiple currencies.

Add multiple currencies in BigCommerce Management Panel

To retrieve a response from the BigCommerce API, you must first define the list of currencies in the BigCommerce Management Panel, which can be managed in the channel settings. Manage currencies

If you don't see currencies in your channel menus you need to Configure UI Sections

Fetching available currencies

The BigCommerce integration allows 2 ways of retrieving the list of available currencies.

getCurrencies endpoint

You can use the getCurrencies endpoint, which under the hood makes an HTTP request to Get All Currencies BigCommerce API.

Example response of getCurrencies endpoint:

{
  "data": [
    {
      "entityId": 1,
      "code": "PLN",
      "name": "Zloty",
      "flagImage": "https://cdn11.bigcommerce.com/s-s4zoaccduv/lib/flags/pl.gif",
      "isActive": false,
      "exchangeRate": 4.4714,
      "isTransactional": true,
      "display": {
        "symbol": "zł",
        "symbolPlacement": "LEFT",
        "decimalToken": ".",
        "thousandsToken": ",",
        "decimalPlaces": 2
      }
    },
    {
      "entityId": 2,
      "code": "EUR",
      "name": "Euro",
      "flagImage": "https://cdn11.bigcommerce.com/s-s4zoaccduv/lib/flags/regions/eu.gif",
      "isActive": true,
      "exchangeRate": 0.9416,
      "isTransactional": true,
      "display": {
        "symbol": "€",
        "symbolPlacement": "LEFT",
        "decimalToken": ".",
        "thousandsToken": ",",
        "decimalPlaces": 2
      }
    },
    {
      "entityId": 3,
      "code": "USD",
      "name": "US Dollar",
      "flagImage": "https://cdn11.bigcommerce.com/s-s4zoaccduv/lib/flags/us.gif",
      "isActive": false,
      "exchangeRate": 1,
      "isTransactional": true,
      "display": {
        "symbol": "$",
        "symbolPlacement": "LEFT",
        "decimalToken": ".",
        "thousandsToken": ",",
        "decimalPlaces": 2
      }
    }
  ],
  "meta": {
    "pageInfo": {
      "hasNextPage": false,
      "hasPreviousPage": false,
      "startCursor": "YXJyYXljb25uZWN0aW9uOjA=",
      "endCursor": "YXJyYXljb25uZWN0aW9uOjI="
    }
  }
}

getChannel endpoint

Alternatively, you can use the getChannel endpoint with the { include: 'currencies' } parameter. It adds the available currencies and default currency information to the response:

{
  "data": {
    ...
    "name": "VSF",
    "id": 1,
+   "currencies": {
+     "channel_id": 1,
+     "enabled_currencies": ["PLN", "EUR", "USD"],
+     "default_currency": "EUR"
+   }
  },
  "meta": {}
}

getCurrencies vs getChannelgetCurrencies response include more information about the currencies like the link to it's flag, symbol, and more. getChannel returns information about the channel in general, which might also include currencies. Use cases might be different and everything depends on the needs. If you need channel information and currency details are not important, then I'd recommend using getChannel endpoint. Otherwise, getCurrencies is the one you're looking for.

SDK usage

import { getSdk } from "@/sdk";

const sdk = await getSdk();

// Option 1: Fetch currencies directly
const { data: currencies } = await sdk.commerce.getCurrencies();

// Option 2: Fetch channel with currencies included
const { data: channel } = await sdk.commerce.getChannel({
  include: "currencies",
});
const channelCurrencies = channel.currencies;

Fetching products based on the currency

There are four endpoints that are able to respond with currency information:

  • getProductById - fetch a product based on entityId param,
  • getProductsById - fetch list of products based on entityIds param,
  • getProductsWithFilter - fetch list of products based on filters,
  • getProductsByCategory - fetch list of products based on category id.

Each of these methods accepts currencyCode. If the currencyCode is undefined, it will return the information in default currency.

SDK usage

import { getSdk } from "@/sdk";

const sdk = await getSdk();

const { data: product } = await sdk.commerce.getProductById({
  entityId: 97,
  currencyCode: "EUR",
  includeModifiers: true,
  includeOptions: true,
  includeCustomFields: true,
});

// or

const { data: products } = await sdk.commerce.getProductsById({
  entityIds: [97, 98, 99],
  currencyCode: "EUR",
  after: "",
  first: 10,
  variantsLimit: 250,
  optionsLimit: 40,
});

// or

const { data: products } = await sdk.commerce.getProductsWithFilter({
  filters: {
    categoryEntityId: 28,
    productAttributes: [],
  },
  currencyCode: "EUR",
  after: "",
  first: 10,
});

// or

const { data: products } = await sdk.commerce.getProductsByCategory({
  entityId: 28,
  currencyCode: "EUR",
  after: "",
  first: 10,
});

Updating cart currency

In BigCommerce, cart currency needs to be defined during creation of the cart. In the BigCommerce Integration, it can be done when calling the createCart endpoint with the currency parameter.

await sdk.commerce.createCart({
  ...
+ currency: { code: 'EUR' }
})

However, there is no way to update the currency of the cart in the BigCommerce API. That's a limitation of the BigCommerce API, however it can be achieved by combining the requests.

Developers can implement the update cart currency behaviour when switching the currency by:

  1. Creating a new cart with new currency information,
  2. Adding products from the old cart to the new one,
  3. Updating the user's cart information,
  4. Removing the old cart.