From 72675c59eca8b918a4c6f2c0f8467610222f6f98 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 1 Sep 2025 10:10:28 +0300 Subject: [PATCH] docs: document how prices are stored in Medusa (#13362) --- .../learn/introduction/from-v1-to-v2/page.mdx | 8 ++++ www/apps/book/generated/edit-dates.mjs | 2 +- www/apps/book/public/llms-full.txt | 38 ++++++++++++++----- .../pricing/concepts/page.mdx | 14 ++++++- .../pricing/price-calculation/page.mdx | 32 ++++++++-------- www/apps/resources/generated/edit-dates.mjs | 4 +- 6 files changed, 67 insertions(+), 31 deletions(-) diff --git a/www/apps/book/app/learn/introduction/from-v1-to-v2/page.mdx b/www/apps/book/app/learn/introduction/from-v1-to-v2/page.mdx index 70e19eb058..dcd657c552 100644 --- a/www/apps/book/app/learn/introduction/from-v1-to-v2/page.mdx +++ b/www/apps/book/app/learn/introduction/from-v1-to-v2/page.mdx @@ -1893,6 +1893,14 @@ In Medusa v2, the price selection process is now implemented in the [Pricing Mod If your use case is complex and these rules are not enough, you can create a new [module](../../fundamentals/modules/page.mdx) with the necessary logic, then use that module in your custom workflows. +## Prices are Stored in Base Units + +In Medusa v1, prices were stored in the smallest currency unit. For example, a price of $10.00 was stored as `1000` (cents). + +In Medusa v2, prices are stored in the base unit. For example, a price of $10.00 is stored as `10` (dollars). + +Learn more in the [Pricing Concepts](!resources!/commerce-modules/pricing/concepts) guide. + ### Gift Card Features Medusa v1 has gift card features out-of-the-box. diff --git a/www/apps/book/generated/edit-dates.mjs b/www/apps/book/generated/edit-dates.mjs index 0c0178561b..1983055b6c 100644 --- a/www/apps/book/generated/edit-dates.mjs +++ b/www/apps/book/generated/edit-dates.mjs @@ -125,7 +125,7 @@ export const generatedEditDates = { "app/learn/introduction/build-with-llms-ai/page.mdx": "2025-07-22T16:19:11.668Z", "app/learn/installation/docker/page.mdx": "2025-07-23T15:34:18.530Z", "app/learn/fundamentals/generated-types/page.mdx": "2025-07-25T13:17:35.319Z", - "app/learn/introduction/from-v1-to-v2/page.mdx": "2025-07-30T08:13:48.592Z", + "app/learn/introduction/from-v1-to-v2/page.mdx": "2025-09-01T06:34:41.179Z", "app/learn/debugging-and-testing/debug-workflows/page.mdx": "2025-07-30T13:45:14.117Z", "app/learn/fundamentals/data-models/json-properties/page.mdx": "2025-07-31T14:25:01.268Z", "app/learn/debugging-and-testing/logging/custom-logger/page.mdx": "2025-08-28T15:37:07.328Z", diff --git a/www/apps/book/public/llms-full.txt b/www/apps/book/public/llms-full.txt index 179e6b9a40..7d4f374324 100644 --- a/www/apps/book/public/llms-full.txt +++ b/www/apps/book/public/llms-full.txt @@ -22794,6 +22794,14 @@ In Medusa v2, the price selection process is now implemented in the [Pricing Mod If your use case is complex and these rules are not enough, you can create a new [module](https://docs.medusajs.com/learn/fundamentals/modules/index.html.md) with the necessary logic, then use that module in your custom workflows. +## Prices are Stored in Base Units + +In Medusa v1, prices were stored in the smallest currency unit. For example, a price of $10.00 was stored as `1000` (cents). + +In Medusa v2, prices are stored in the base unit. For example, a price of $10.00 is stored as `10` (dollars). + +Learn more in the [Pricing Concepts](https://docs.medusajs.com/resources/commerce-modules/pricing/concepts/index.html.md) guide. + ### Gift Card Features Medusa v1 has gift card features out-of-the-box. @@ -32182,11 +32190,21 @@ View the full flow of the webhook event processing in the [processPaymentWorkflo In this document, you’ll learn about the main concepts in the Pricing Module. +## Price Data Model + +The [Price](https://docs.medusajs.com/references/pricing/models/Price/index.html.md) data model represents a specific price for a resource. For example, the price of a product variant in the USD currency. + +The `Price` data model has an `amount` property that represents the monetary value of the price. It's stored as an integer in base units. For example, `$20.00` is stored as `20`. + +The `Price` data model belongs to other data models like `PriceSet` and `PriceList` to provide a variety of pricing features, as explained below. + +*** + ## Price Set -A [PriceSet](https://docs.medusajs.com/references/pricing/models/PriceSet/index.html.md) represents a collection of prices that are linked to a resource (for example, a product or a shipping option). +A [PriceSet](https://docs.medusajs.com/references/pricing/models/PriceSet/index.html.md) represents a collection of prices that are linked to a resource (for example, a product variant or a shipping option). -Each of these prices are represented by the [Price data module](https://docs.medusajs.com/references/pricing/models/Price/index.html.md). +Each of these prices is represented by the [Price data model](https://docs.medusajs.com/references/pricing/models/Price/index.html.md). ![A diagram showcasing the relation between the price set and price](https://res.cloudinary.com/dza7lstvk/image/upload/v1709648650/Medusa%20Resources/price-set-money-amount_xeees0.jpg) @@ -32622,27 +32640,27 @@ const priceSet = await pricingModuleService.createPriceSets({ prices: [ // default price { - amount: 500, + amount: 5, currency_code: "EUR", rules: {}, }, // prices with rules { - amount: 400, + amount: 4, currency_code: "EUR", rules: { region_id: "reg_123", }, }, { - amount: 450, + amount: 4.5, currency_code: "EUR", rules: { city: "krakow", }, }, { - amount: 500, + amount: 5, currency_code: "EUR", rules: { city: "warsaw", @@ -32650,7 +32668,7 @@ const priceSet = await pricingModuleService.createPriceSets({ }, }, { - amount: 200, + amount: 2, currency_code: "EUR", min_quantity: 100, }, @@ -32707,7 +32725,7 @@ const price = await pricingModuleService.calculatePrices( items: [ { id: "item_1", - quantity: 200, + quantity: 2, // assuming the price set belongs to this variant variant_id: "variant_1", // ... @@ -32738,12 +32756,12 @@ const priceList = pricingModuleService.createPriceLists([{ type: "sale", prices: [ { - amount: 400, + amount: 4, currency_code: "EUR", price_set_id: priceSet.id, }, { - amount: 450, + amount: 4.5, currency_code: "EUR", price_set_id: priceSet.id, }, diff --git a/www/apps/resources/app/commerce-modules/pricing/concepts/page.mdx b/www/apps/resources/app/commerce-modules/pricing/concepts/page.mdx index 6b59a52f6e..6f8e068a0f 100644 --- a/www/apps/resources/app/commerce-modules/pricing/concepts/page.mdx +++ b/www/apps/resources/app/commerce-modules/pricing/concepts/page.mdx @@ -6,11 +6,21 @@ export const metadata = { In this document, you’ll learn about the main concepts in the Pricing Module. +## Price Data Model + +The [Price](/references/pricing/models/Price) data model represents a specific price for a resource. For example, the price of a product variant in the USD currency. + +The `Price` data model has an `amount` property that represents the monetary value of the price. It's stored as an integer in base units. For example, `$20.00` is stored as `20`. + +The `Price` data model belongs to other data models like `PriceSet` and `PriceList` to provide a variety of pricing features, as explained below. + +--- + ## Price Set -A [PriceSet](/references/pricing/models/PriceSet) represents a collection of prices that are linked to a resource (for example, a product or a shipping option). +A [PriceSet](/references/pricing/models/PriceSet) represents a collection of prices that are linked to a resource (for example, a product variant or a shipping option). -Each of these prices are represented by the [Price data module](/references/pricing/models/Price). +Each of these prices is represented by the [Price data model](/references/pricing/models/Price). ![A diagram showcasing the relation between the price set and price](https://res.cloudinary.com/dza7lstvk/image/upload/v1709648650/Medusa%20Resources/price-set-money-amount_xeees0.jpg) diff --git a/www/apps/resources/app/commerce-modules/pricing/price-calculation/page.mdx b/www/apps/resources/app/commerce-modules/pricing/price-calculation/page.mdx index 4a10284c7b..854a16720f 100644 --- a/www/apps/resources/app/commerce-modules/pricing/price-calculation/page.mdx +++ b/www/apps/resources/app/commerce-modules/pricing/price-calculation/page.mdx @@ -166,27 +166,27 @@ const priceSet = await pricingModuleService.createPriceSets({ prices: [ // default price { - amount: 500, + amount: 5, currency_code: "EUR", rules: {}, }, // prices with rules { - amount: 400, + amount: 4, currency_code: "EUR", rules: { region_id: "reg_123", }, }, { - amount: 450, + amount: 4.5, currency_code: "EUR", rules: { city: "krakow", }, }, { - amount: 500, + amount: 5, currency_code: "EUR", rules: { city: "warsaw", @@ -194,7 +194,7 @@ const priceSet = await pricingModuleService.createPriceSets({ }, }, { - amount: 200, + amount: 2, currency_code: "EUR", min_quantity: 100, }, @@ -232,10 +232,10 @@ const priceSet = await pricingModuleService.createPriceSets({ const price = { id: "", is_calculated_price_price_list: false, - calculated_amount: 500, + calculated_amount: 5, is_original_price_price_list: false, - original_amount: 500, + original_amount: 5, currency_code: "EUR", @@ -299,10 +299,10 @@ const priceSet = await pricingModuleService.createPriceSets({ const price = { id: "", is_calculated_price_price_list: false, - calculated_amount: 500, + calculated_amount: 5, is_original_price_price_list: false, - original_amount: 500, + original_amount: 5, currency_code: "EUR", @@ -353,7 +353,7 @@ const priceSet = await pricingModuleService.createPriceSets({ items: [ { id: "item_1", - quantity: 200, + quantity: 2, // assuming the price set belongs to this variant variant_id: "variant_1", // ... @@ -375,10 +375,10 @@ const priceSet = await pricingModuleService.createPriceSets({ const price = { id: "", is_calculated_price_price_list: false, - calculated_amount: 200, + calculated_amount: 2, is_original_price_price_list: false, - original_amount: 200, + original_amount: 2, currency_code: "EUR", @@ -433,12 +433,12 @@ const priceSet = await pricingModuleService.createPriceSets({ type: "sale", prices: [ { - amount: 400, + amount: 4, currency_code: "EUR", price_set_id: priceSet.id, }, { - amount: 450, + amount: 4.5, currency_code: "EUR", price_set_id: priceSet.id, }, @@ -466,10 +466,10 @@ const priceSet = await pricingModuleService.createPriceSets({ const price = { id: "", is_calculated_price_price_list: true, - calculated_amount: 400, + calculated_amount: 4, is_original_price_price_list: false, - original_amount: 500, + original_amount: 5, currency_code: "EUR", diff --git a/www/apps/resources/generated/edit-dates.mjs b/www/apps/resources/generated/edit-dates.mjs index 6740611bfe..52079ef0d4 100644 --- a/www/apps/resources/generated/edit-dates.mjs +++ b/www/apps/resources/generated/edit-dates.mjs @@ -55,8 +55,8 @@ export const generatedEditDates = { "app/commerce-modules/payment/page.mdx": "2025-04-17T08:48:11.702Z", "app/commerce-modules/pricing/_events/_events-table/page.mdx": "2024-07-03T19:27:13+03:00", "app/commerce-modules/pricing/_events/page.mdx": "2024-07-03T19:27:13+03:00", - "app/commerce-modules/pricing/concepts/page.mdx": "2024-10-09T13:37:25.678Z", - "app/commerce-modules/pricing/price-calculation/page.mdx": "2025-05-20T07:51:40.710Z", + "app/commerce-modules/pricing/concepts/page.mdx": "2025-09-01T06:30:15.013Z", + "app/commerce-modules/pricing/price-calculation/page.mdx": "2025-09-01T06:32:07.141Z", "app/commerce-modules/pricing/price-rules/page.mdx": "2025-06-10T15:56:43.648Z", "app/commerce-modules/pricing/tax-inclusive-pricing/page.mdx": "2025-06-27T15:43:35.193Z", "app/commerce-modules/pricing/page.mdx": "2025-05-20T07:51:40.710Z",