Adding Additional Currencies

Learn how to configure additional currencies in your storefront and switch between them.

By default, Alokai Storefront ships with both UI and logic to help implement dynamic currency switching:

LocationSelectorsModal component that allows users to select their language and currency
getCurrencies Unified Method that returns the list of available currencies based on your middleware configuration

Configuring currencies

First, to configure multiple currencies to your app, you can add a currencies (compliant to ISO 4217) in your Unified Extension config and set defaultCurrency value:

// apps/storefront-middleware/integrations/<integration>/extensions/unified.ts

export const unifiedApiExtension = createUnifiedExtension({
  config: { 
    currencies: ["USD", "EUR"], 
    defaultCurrency: "USD", 
  }, 
});

Fetching currencies data

The Unified Methods provide a getCurrencies() method that your frontend can use to fetch the configured currency information in your middleware configuration:

const currencies = await sdk.unified.getCurrencies();

console.log(currencies); // { currencies: ["USD", "EUR"], defaultCurrency: "USD" }

In order to properly fetch and return prices in a specific currency, the middleware looks for a cookie named vsf-currency that contains the desired currency code. This currency code is then used for requests to the commerce platform.

To ensure that the correct currency is retrieved, vsf-currency have to be set in a request headers during the initial application or subsequent data loads. Depending on the framework you are using, you can set the vsf-currency cookie in different ways:

In the App router application, you can set the vsf-currency cookie using setCookie function from cookies-next package. The useUserSettings hook encapsulates this logic:

// apps/storefront-unified-nextjs/hooks/use-user-settings.ts

'use client';

import { useQueryClient } from '@tanstack/react-query';
import { setCookie } from 'cookies-next';

import { CURRENCY_COOKIE } from '@/config/constants';
import { useSfCurrencyState } from '@/sdk/alokai-context';

export function useUserSettings() {
  const [, setCurrency] = useSfCurrencyState();
  const queryClient = useQueryClient();

  const setCurrentCurrency = (value: string) => {
    setCookie(CURRENCY_COOKIE, value, {
      sameSite: 'strict',
      secure: true,
    });

    // set current currency value to application store
    setCurrency(value);

    // remove from internal cache all of the `@tanstack/react-query` queries where
    // data might change based on chosen currency
    // they'll be invalidated and refetched automatically
    queryClient.removeQueries({
      queryKey: ['lazyProduct'],
      type: 'active',
    });
  };

  return { setCurrentCurrency };
}

In Nuxt, you can create a Nuxt plugin that will set the vsf-currency cookie on the server side during the initial page setup:

// apps/storefront-unified-nuxt/plugins/localization.ts

export default defineNuxtPlugin((nuxtApp) => {
  // This plugin will run only on the server side
  if (import.meta.client) {
    return;
  }
  nuxtApp.hook('app:created', async () => {
    const { fetchCurrencies } = useCurrenciesData();
    await fetchCurrencies();
  });
});

In the example above, Nuxt app propagates vsf-currency cookie from the Unified Data Layer response, provided by getCurrencies() API method, to the client. Check out example getCurrencies() Unified Method source code for a reference.

Some platforms don't support currency switching at every stage of the transaction process For instance, in Commercetools, the Cart object is initialized with a designated currency, which cannot be modified once set. Additionally, line items within the cart will not be recalculated to reflect a different currency.

Adding Additional Currencies

Configuring currencies

Fetching currencies data

Setting the vsf-currency cookie

On this page

Setting the `vsf-currency` cookie