Community

Multi-currency Ecommerce: How to Take Multiple Currencies in Your Storefront

Jan 23, 2023 by

Sani Amina

Explore the benefits of multi-currency ecommerce and how Medusa, an open source Shopify alternative, solves the multi-currency hurdle Shopify merchants face.

Introduction

Multi-currency ecommerce is an avenue for business owners or merchants to sell their products without barriers, allowing buyers to make purchases in their own currency.

This feature has many benefits; it makes buying and selling seamless as customers can know the exact cost of products without having to deal with multiple calculations or pay conversion fees.

Medusa, alongside its numerous benefits, supports the implementation of multi-currency for stores. Merchants can add an unlimited number of currencies and regions to their store, and specify prices specific for each currency and region.

In this article, you’ll learn more about the benefits of multi-currency support. You’ll also learn about what Medusa is and how to use its multi-currency feature.

What is Medusa?

Medusa is an open source composable commerce platform that enables individuals and businesses to build unique digital experiences in their online stores. It offers limitless customization capabilities for developers to cater the ecommerce store to the business use case.

Suggested Read: Explained in 5 Levels of Difficulty: Ecommerce by Medusa

Medusa comes with pre-built ecommerce rich features such as multiple payment methods for credit cards, shopping carts, and multiple currencies for the global market.

Medusa's ecommerce engine also provides multi-currency and regions support. Medusa offers a feature that is missing in many ecommerce platforms. Instead of forcing a conversion rate on all products, it provides the flexibility of setting prices for each product per currency or region. That makes Medusa stand out from other ecommerce platforms.

Why is Multi-currency Support Important in Ecommerce?

In an ecommerce platform, the need for multi-currency support is very important and cannot be overlooked.

Some of its benefits include:

It allows businesses to sell their products internationally in the local currency of the customer of the online store.
It gives businesses more flexibility on how they display the price of the product. Conversion rates can lead to prices that are formatted with many decimal points. Setting a specific price can keep the presentational quality of the price and the product.
Multi-currency support allows online ecommerce businesses to have control over prices across different countries.
It prevent customers from being charged additional fees due to currency conversion rates when they pay with foreign currencies since they get to choose their native currency while shopping.

Set up Medusa for Multi-Currency Support

In this section, you’ll learn how to install the Medusa server and Medusa admin to benefit from Medusa’s multi-currency support.

Prerequisites

Before you start this tutorial, ensure you have the following:

Node v14 or a later version.
Medusa CLI installed. Run this command below to install Medusa CLI:

npm install @medusajs/medusa-cli -g

Creating a New Medusa Project

Run the command below to create your new medusa store project:

medusa new my-medusa-store --seed

The above command will create a Medusa store for you in the new directory

Copy to clipboard
my-medusa-store

Next, change the directory to your newly created project and start your Medusa server:

cd my-medusa-store
medusa develop

Medusa store runs on port

Copy to clipboard
9000

by default. You can test your store with this URL on your browse:

Copy to clipboard
localhost:9000/store/products

Creating Medusa Store Admin

Medusa Admin is connected with the Medusa server and many ecommerce features such as product management, order management, customer management, discounts and gift management, pricing, settings, and more.

To create Medusa Admin, start by cloning the Medusa Admin GitHub repository. Use the command below:

git clone https://github.com/medusajs/admin medusa-admin

After the above command has been completed, change your directory with this command:

cd medusa-admin

Now, install dependencies and start your admin:

npm install
npm run start

By default, the admin runs on port

Copy to clipboard
7000

. So, in your browser, go to

Copy to clipboard
localhost:7000

to view your admin. It should look similar to the image below.

Medusa Admin has default admin login details which are “

Copy to clipboard
admin@medusa-test.com

" as the email address password “

Copy to clipboard
supersecret

” as the password. The default admin login information exists because you added

Copy to clipboard
--seed

to the

Copy to clipboard
medusa new

command when you created Medusa Server.

Using Multi-currency in Medusa

You can add multiple currencies in your ecommerce store from the Medusa admin. You can create multiple regions in the same store and select the currency of the region. Then, you’ll be able to set the price of the product differently for each currency.

Adding More Currencies

To add more currencies to your ecommerce storefront from Medusa Admin, follow the steps below:

Open the Medusa Admin settings page, and click on currencies.

Click on Edit Currencies to open the the current store currencies dialog.

Click on Add Currencies to add more currencies to your Medusa store.

Click the checkbox next to the currencies you want to add.

After selecting the currencies you need from the above snapshot, click on the “Save and close” button.

Creating Multiple Regions

Regions are used to manage the countries your ecommerce store operates in. A currency must be associated with a region to be visible and used by customers.

In this section, you’ll learn how to create regions for each of the currencies you created in the previous section.

To create a region, follow the steps below:

Go to Settings ⇒ Regions.
Click on the plus button at the top of the Regions section.
In the new form that opens:
1. For each region, you can select settings specific to that region as indicated in the steps above. You can choose one or more countries to be part of a region. You can also select what currency is provided for that region.
2. For example, you can create a region for countries like the USA, Canada, and Australia, and use US Dollar as the currency for that region. You can also create a different region for each of those countries and choose their currencies.
3. Note that for a currency to appear in the Currency field, it must be added as explained in the previous section.
After entering all the preferred details of the region, click the “Save and close” button.

If you would like to learn more about regions and available features, you can check Medusa Regions documentation.

Set Multi-currency Prices for a Product

In this section, you’ll learn how to set a price per currency or region for products.

Follow these steps to set your multi-currency prices while adding your products:

1. Select Variants on the product general information page.

2. Click on the Add an Option button.

3. After adding a product option, you can create variant by clicking on Add a variant.

4. After clicking on Add a variant, you will be prompted to enter general information for the variant. Click on the plus button on the right side of Pricing to set the multi-currency price of the product variant.

5. You can now set prices for the product per currency and region.

Use Multiple Currency in an Ecommerce Storefront

Medusa has some already-built starter storefronts using Next.js and Gatsby.js. For this tutorial, you will be using the Medusa Next.js Starter storefront.

You can run this command to create your storefront:

npx create-next-app -e https://github.com/medusajs/nextjs-starter-medusa my-medusa-storefrontxz

Copy to clipboard
my-medusa-storefront

in the above command represents your storefront name. You can change it to your preferred name.

Next, change to the newly created directory

Copy to clipboard
my-medusa-storefront

and rename the template environment variable file to use environment variables in development:

cd my-medusa-storefront
mv .env.template .env.local

Testing Multi-Currency Support

If you completed the above steps, it is time to test if your multi-currency is working perfectly on your storefront. During the testing process, observe how the product prices change based on the selected region.

Testing your Ecommerce Storefront

Make sure the Medusa server is running, then start the local storefront server:

npm run dev

Medusa Next.js starter storefront runs on port 8000 by default. You can test your storefront at

Copy to clipboard
localhost:8000

Test Multi-Currency Support on the Storefront

To test multi-currency support in your store, move down to the footer part of your storefront and click on “Shipping to” to select the list of available countries and currencies that you added to your admin panel.

You can then see the products’ prices change based on the selected currency. Try changing to another region and see how the currency and price change.

Test Storefront Product API Response

Aside from using the Next.js or Gatsby storefront, you can build your own storefront using Medusa’s APIs. This section explains how to retrieve product prices based on the selected region using Medusa’s APIs.

You can either use the Fetch API to send requests to the Medusa server, or use Medusa’s JS Client.

This tutorial section uses the Medusa JS Client. To install it, run the following command in the directory of your ecommerce storefront:

npm install @medusajs/medusa-js

Then, you can retrieve the available regions in your Medusa server by sending a request to the List Regions endpoint:

import Medusa from "@medusajs/medusa-js"

const medusa = new Medusa()

medusa.regions.list()
.then(({ regions }) => {
  console.log(regions.length)
  // show customers available regions
})

You can then display these regions to the customer and allow them to select the region. You can store the selected region in the local storage.

Then, when retrieving the products, pass to the List Products endpoint the

Copy to clipboard
region_id

query parameter with its value being the selected region ID:

localhost:9000/store/products?region_id=<region_id>

This request returns the products in the store. For each product, you’ll find a

Copy to clipboard
prices

attribute which is an array of prices similar to this:

{
   "prices":[
      {
         "id":"ma_01GD0VCDZM2HTAZST8JNTXXPT1",
         "created_at":"2022-09-15T15:13:24.401Z",
         "updated_at":"2022-09-15T15:13:24.401Z",
         "deleted_at":null,
         "currency_code":"eur",
         "amount":0,
         "min_quantity":null,
         "max_quantity":null,
         "price_list_id":null,
         "variant_id":"variant_01GD0VCDY50AA6BX9V3MMNKWN6",
         "region_id":"reg_01GCXWJARKRC5678HB9QTWH1XK",
         "price_list":null
      },
      {
         "id":"ma_01GD0VCDZXSA3C3Z0MY0BCE227",
         "created_at":"2022-09-15T15:13:24.401Z",
         "updated_at":"2022-09-15T15:13:24.401Z",
         "deleted_at":null,
         "currency_code":"eur",
         "amount":2000,
         "min_quantity":null,
         "max_quantity":null,
         "price_list_id":null,
         "variant_id":"variant_01GD0VCDY50AA6BX9V3MMNKWN6",
         "region_id":null,
         "price_list":null
      }
   ]
}

Since you provided the ID of the region, the array will include only prices for that region and for the currency of that region.

The array should include at least one price, which is the price set for the currency of the region. The attribute

Copy to clipboard
region_id

for this price will be

Copy to clipboard
null

If you’ve set in the admin a price specific for this region, it’ll be added as another entry in the array. This entry has the attribute

Copy to clipboard
region_id

set to the ID of the region.

Conclusion

Multi-currency support is an important asset for all ecommerce stores. Businesses should keep that in mind while choosing an ecommerce platform for their online store, since not all platforms provide this flexible support.

You can learn more about Currencies, Regions and Region User-Guide from Medusa documentation.

If you have any issues or questions or are interested in learning more about Medusa, please join our Discord channel.

Medusa’s multi-currency feature provides the optimal flexibility for businesses as they can set prices for a specific currency and region. Developers can also implement the storefront to show the available regions and prices based on selected region using Medusa’s APIs.

Share this post