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

Multi-currency overview

v2.4.0 of @vsf-enterprise/bigcommerce-api enables 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

To call the getCurrencies endpoint, you can use the getCurrencies method from the @vue-storefront/bigcommerce-sdk SDK.

import { sdk } from "~/sdk.config.ts";

const { data: currencies } = await sdk.bigcommerce.getCurrencies();

To call the getChannel endpoint, you can use the getChannel method from the @vue-storefront/bigcommerce-sdk SDK.

import { sdk } from "~/sdk.config.ts";

const { data: channel } = await sdk.bigcommerce.getChannel({
  include: "currencies",
});
const currencies = channel.currencies;

Fetching products based on the currency

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

  • getProductById - fetch list of products 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 this method accepts currencyCode. If the currencyCode is undefined, it will return the information in default currency.

SDK usage

All those endpoints can be accessed from the @vue-storefront/bigcommerce-sdk SDK.

Example usage of those SDK methods:

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

// or

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

// or

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

// or

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

Updating cart currency

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

await 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.