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.

If you don't see currencies in your channel menus you need to Configure UI Sections (opens new window)

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 (opens new window) 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": {}
}

TIP

getCurrencies vs getChannel getCurrencies 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.

Nuxt 2 storefront

If you're working with our Nuxt 2 storefront, you can use both of those endpoints via context, just like we're doing it in the composables.

import { useContext } from '@nuxtjs/composition-api';

const { data: currencies } = await context.$bigcommerce.api.getCurrencies();

// or

const { data: channel } = await context.$bigcommerce.api.getChannel({
  include: 'currencies'
});
const currencies = channel.currencies.enabled_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.

Nuxt 2 storefront

If you're working with our nuxt 2 storefront, you can use all of those endpoints via context, just like you do in the composables.

Example usage of those endpoints:

const { data: products } = await context.$bigcommerce.api.getProductById({
  entityId: 97,
  currencyCode: 'EUR',
  includeModifiers: true,
  includeOptions: true,
  includeCustomFields: true
});

// or

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

// or

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

// or

const { data: products } = await context.$bigcommerce.api.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.