Currency Architecture
In this document, you’ll learn about the Currency entity and its relation to other entities.
Introduction
Currencies are used to define the price of products, services, and other monetary details in a commerce system.
Medusa supports multi-currency within your commerce store. You can specify prices per currency, and even per region. This means that you can serve customers globally without limitations related to pricing.
Currency Entity Overview
The Currency entity has the following attributes:
code: A string indicating the 3 character ISO code for the currency. This attribute also acts as a unique and primary column of the entity.symbol: A string indicating the display symbol of the currency. This would typically be the symbol you would show to the customer or admin users when displaying a price.symbol_native: A string indicating the native symbol of the currency.name: A string indicating the name of the currency.
How Currencies are Created
Currencies are defined in the core of your Medusa backend under utils/currencies.js (or packages/medusa/src/utils/currencies.ts if you’re using the Medusa mono-repository). They’re defined in an object in that file.
When you run the migration or seed command the first time on your Medusa server, a migration uses this object to insert all its properties (the currencies) into the database.
So, if you want to add more currencies, you can create a migration that inserts your currencies into the database.
You can learn more about Migrations in this guide.
Relation to Other Entities
Store
A store has a default currency and can have many currencies. These currencies are then used in other relations, such as when associating a region with a currency.
There are two relations available on the Store entity related to the Currency entity:
- You can expand the
default_currencyrelation on a store and access the default currency withstore.default_currency. You can also use thedefault_currency_codeattribute on the store to access the code of the default currency. - You can expand the
currenciesrelation on a store and access the currencies withstore.currencies.
Region
Each region is associated with a currency. A currency can be used in more than one region, but a region can have only one currency.
The relation is available on a region by expanding the region.currency relation and accessing region.currency. You can also access the currency code through the attribute currency_code on the region.
MoneyAmount
The MoneyAmount entity is used to store the price of different entities within your commerce store.
The relation is available on the MoneyAmount entity by expanding the currency relation and accessing money_amount.currency. You can also access the currency code through the attribute currency_code on the money amount.
Order
The Order entity includes a relation to the currency, as it is the currency that the order was placed in.
The relation is available on the Order entity by expanding the currency relation and accessing order.currency. You can also access the currency code through the attribute currency_code on the order.
Payment
The Payment entity is used to represent a payment of any kind, such as for orders. Each payment is associated with a currency.
The relation is available on the Payment entity by expanding the currency relation and accessing payment.currency_code. You can also access the currency code through the attribute currency_code on the payment.
PaymentCollection
The PaymentCollection entity is used to represent a collection of payments. Each payment collection is associated with a currency.
The relation is available on the PaymentCollection entity by expanding the currency relation and accessing payment_collection.currency_code. You can also access the currency code through the attribute currency_code on the payment collection.