Vue Storefront is now Alokai! Learn More
Adding Additional Currencies

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:

// apps/storefront-unified-nextjs/app/[locale]/(default)/components/user-settings-form.tsx

'use client';

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

export default async function ChangeCurrencyForm() {
  const [, setCurrency] = useSfCurrencyState();
  const queryClient = useQueryClient();
  
  const setCurrentCurrency = (value: string) => {
    setCookie('vsf-currency', value, {
      sameSite: 'strict',
      secure: true,
    });

    // when avaiable in your app: 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 (
    <form
      action={async (formData) => {
        setCurrentCurrency(`${formData.get('currency')}`);
      }}
    >
      <button type="submit">Change Currency</button>
    </form>
  );
}

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.