docs: add section on multi-currency and region support

2025-09-11 14:41:43 +03:00
parent d73591aafd
commit d8c65a7310
4 changed files with 117 additions and 3 deletions
@@ -34,4 +34,60 @@ When the conditions are met, the prices in the price list can override the defau

 A price list has optional `start_date` and `end_date` properties that indicate the date range in which a price list can be applied.

-Its associated prices are represented by the [Price data model](#price-data-model).
+Its associated prices are represented by the [Price data model](#price-data-model).
+
+---
+
+## Multi-Currency Support for Prices
+
+The `Price` data model has a `currency_code` property that represents the currency of the price. For example, `usd` for US Dollars and `eur` for Euros.
+
+This adds support for multi-currency pricing, allowing you to associate a resource with a price set that contains prices in multiple currencies.
+
+For example, Medusa links a product variant from the [Product Module](../../product/page.mdx) to a price set that contains prices in multiple currencies. A variant's price set would be similar to the following:
+
+```json title="Example Price Set with Multiple Currencies"
+{
+  "id": "pset_123",
+  "prices": [
+    {
+      "id": "price_123",
+      "amount": 20,
+      "currency_code": "usd"
+    },
+    {
+      "id": "price_124",
+      "amount": 18,
+      "currency_code": "eur"
+    }
+  ]
+}
+```
+
+When the customer views and purchases a product, Medusa selects the price based on the customer's currency.
+
+---
+
+## Multi-Region Support for Prices
+
+The `Price` data model has a relation to the [PriceRule](/references/pricing/models/PriceRule) data model that allows you to define prices that are applied based on specific conditions, such as the customer's region.
+
+For example, Medusa allows you to specify prices for a product variant that are applied only when the customer is in a specific region. The price would be similar to the following:
+
+```json title="Example Price with Region Rule"
+{
+  "id": "price_123",
+  "amount": 25,
+  "currency_code": "usd",
+  "price_rules": [
+    {
+      "id": "pricerule_123",
+      "attribute": "region_id",
+      "value": "reg_123",
+      "operator": "eq"
+    }
+  ]
+}
+```
+
+When the customer views and purchases a product, Medusa selects the price based on the customer's region.
@@ -29,6 +29,7 @@ Learn more about why modules are isolated in [this documentation](!docs!/learn/f
 ## Pricing Features

 - [Price Management](./concepts/page.mdx): Store and manage prices of a resource, such as a product or a variant.
+- [Multi-Currency and Region Support](./concepts/page.mdx#multi-currency-support-for-prices): Define prices for a single resource in multiple currencies and regions.
 - [Advanced Rule Engine](./price-rules/page.mdx): Create prices with tiers and custom rules to condition prices based on different contexts.
 - [Price Lists](./concepts/page.mdx#price-list): Group prices and apply them only in specific conditions with price lists.
 - [Price Calculation Strategy](./price-calculation/page.mdx): Retrieve the best price in a given context and for the specified rule values.