docs: fixes and improvements to price calculation guide (medusajs#13419)

Author: shahednasser

www/apps/book/public/llms-full.txt

@@ -32562,7 +32562,7 @@ Each of these prices is represented by the [Price data model](#price-data-model)
 
 A [PriceList](https://docs.medusajs.com/references/pricing/models/PriceList/index.html.md) is a group of prices that are only enabled when their conditions and rules are satisfied. For example, you can apply special prices to customers in the VIP group.
 
-When the conditions are met, the prices in the price list override the default prices in a price set.
+When the conditions are met, the prices in the price list can override the default prices in a price set. Learn more in the [Price Calculation](https://docs.medusajs.com/Users/shahednasser/medusa/www/apps/resources/app/commerce-modules/pricing/price-calculation/index.html.md) guide.
 
 A price list has optional `start_date` and `end_date` properties that indicate the date range in which a price list can be applied.
 
@@ -32909,17 +32909,19 @@ Learn more about workflows in [this documentation](https://docs.medusajs.com/doc
 
 # Prices Calculation
 
-In this document, you'll learn how prices are calculated when you use the [calculatePrices method](https://docs.medusajs.com/references/pricing/calculatePrices/index.html.md) of the Pricing Module's main service.
+In this guide, you'll learn how prices are calculated when you use the [calculatePrices method](https://docs.medusajs.com/references/pricing/calculatePrices/index.html.md) of the Pricing Module's main service.
 
 ## calculatePrices Method
 
-The [calculatePrices method](https://docs.medusajs.com/references/pricing/calculatePrices/index.html.md) accepts as parameters the ID of one or more price sets and a context.
+The [calculatePrices method](https://docs.medusajs.com/references/pricing/calculatePrices/index.html.md) accepts the ID of one or more price sets and a context as parameters.
 
-It returns a price object with the best matching price for each price set.
+It returns a price object with the best-matching price for each price set.
+
+The `calculatePrices` method is useful for retrieving the prices of a product variant or a shipping option that matches a specific context, such as a currency code, in your backend customizations.
 
 ### Calculation Context
 
-The calculation context is an optional object passed as a second parameter to the `calculatePrices` method. It accepts rules to restrict the selected prices in the price set.
+The calculation context is an optional object passed as the second parameter to the `calculatePrices` method. It accepts rules as key-value pairs to restrict the selected prices in the price set.
 
 For example:
 
@@ -32928,7 +32930,7 @@ const price = await pricingModuleService.calculatePrices(
   { id: [priceSetId] },
   {
     context: {
-      currency_code: currencyCode,
+      currency_code: "eur",
       region_id: "reg_123",
     },
   }
@@ -32943,19 +32945,19 @@ For each price set, the `calculatePrices` method selects two prices:
 
 - A calculated price: Either a price that belongs to a price list and best matches the specified context, or the same as the original price.
 - An original price, which is either:
-  - The same price as the calculated price if the price list it belongs to is of type `override`;
-  - Or a price that doesn't belong to a price list and best matches the specified context.
+  - The same price as the calculated price if it belongs to a price list of type `override`;
+  - Otherwise, a price that doesn't belong to a price list and [best matches](#original-price-selection-logic) the specified context.
 
-Both prices are returned in an object that has the following properties:
+Both prices are returned in an object with the following properties:
 
 - id: (\`string\`) The ID of the price set from which the price was selected.
 - is\_calculated\_price\_price\_list: (\`boolean\`) Whether the calculated price belongs to a price list.
 - calculated\_amount: (\`number\`) The amount of the calculated price, or \`null\` if there isn't a calculated price. This is the amount shown to the customer.
 - is\_original\_price\_price\_list: (\`boolean\`) Whether the original price belongs to a price list.
-- original\_amount: (\`number\`) The amount of the original price, or \`null\` if there isn't an original price. This amount is useful to compare with the \`calculated\_amount\`, such as to check for discounted value.
+- original\_amount: (\`number\`) The amount of the original price, or \`null\` if there isn't an original price. This amount is useful for comparing with the \`calculated\_amount\`, such as to check for a discounted value.
 - currency\_code: (\`string\`) The currency code of the calculated price, or \`null\` if there isn't a calculated price.
-- is\_calculated\_price\_tax\_inclusive: (\`boolean\`) Whether the calculated price is tax inclusive. Learn more about tax-inclusivity in \[this document]\(../tax-inclusive-pricing/page.mdx)
-- is\_original\_price\_tax\_inclusive: (\`boolean\`) Whether the original price is tax inclusive. Learn more about tax-inclusivity in \[this document]\(../tax-inclusive-pricing/page.mdx)
+- is\_calculated\_price\_tax\_inclusive: (\`boolean\`) Whether the calculated price is tax inclusive. Learn more about tax inclusivity in \[this document]\(../tax-inclusive-pricing/page.mdx)
+- is\_original\_price\_tax\_inclusive: (\`boolean\`) Whether the original price is tax inclusive. Learn more about tax inclusivity in \[this document]\(../tax-inclusive-pricing/page.mdx)
 - calculated\_price: (\`object\`) The calculated price's price details.
 
   - id: (\`string\`) The ID of the price.
@@ -32964,9 +32966,9 @@ Both prices are returned in an object that has the following properties:
 
   - price\_list\_type: (\`string\`) The price list's type. For example, \`sale\`.
 
-  - min\_quantity: (\`number\`) The price's min quantity condition.
+  - min\_quantity: (\`number\`) The price's minimum quantity condition.
 
-  - max\_quantity: (\`number\`) The price's max quantity condition.
+  - max\_quantity: (\`number\`) The price's maximum quantity condition.
 - original\_price: (\`object\`) The original price's price details.
 
   - id: (\`string\`) The ID of the price.
@@ -32975,51 +32977,65 @@ Both prices are returned in an object that has the following properties:
 
   - price\_list\_type: (\`string\`) The price list's type. For example, \`sale\`.
 
-  - min\_quantity: (\`number\`) The price's min quantity condition.
+  - min\_quantity: (\`number\`) The price's minimum quantity condition.
+
+  - max\_quantity: (\`number\`) The price's maximum quantity condition.
+
+### Original Price Selection Logic
 
-  - max\_quantity: (\`number\`) The price's max quantity condition.
+When the calculated price isn't from a price list of type `override`, the original price is selected based on the following logic:
+
+![Diagram illustrating the original price selection logic](https://res.cloudinary.com/dza7lstvk/image/upload/v1757058523/Medusa%20Resources/original-price-calculation_sxjw3l.jpg)
+
+1. If the context doesn't have any rules, select the default price (the price without any rules).
+2. If the context has rules and there's a price that matches all the rules, select that price.
+3. If the context has rules and there's no price that matches all the rules:
+   - Find all the prices whose rules match at least one rule in the context.
+   - Sort the matched prices by the number of matched rules in descending order.
+   - Select the first price in the sorted list (the one that matches the most rules).
 
 ***
 
 ## Examples
 
-Consider the following price set:
+Consider the following price set, which has a default price, prices with rules, and tiered pricing:
 
 ```ts
 const priceSet = await pricingModuleService.createPriceSets({
   prices: [
     // default price
     {
       amount: 5,
-      currency_code: "EUR",
+      currency_code: "eur",
       rules: {},
     },
     // prices with rules
     {
       amount: 4,
-      currency_code: "EUR",
+      currency_code: "eur",
       rules: {
         region_id: "reg_123",
       },
     },
     {
       amount: 4.5,
-      currency_code: "EUR",
+      currency_code: "eur",
       rules: {
         city: "krakow",
       },
     },
     {
-      amount: 5,
-      currency_code: "EUR",
+      amount: 3.5,
+      currency_code: "eur",
       rules: {
         city: "warsaw",
         region_id: "reg_123",
       },
     },
+    // tiered price
     {
       amount: 2,
-      currency_code: "EUR",
+      currency_code: "eur",
       min_quantity: 100,
     },
   ],
@@ -33035,15 +33051,34 @@ const price = await pricingModuleService.calculatePrices(
   { id: [priceSet.id] },
   {
     context: {
-      currency_code: "EUR"
+      currency_code: "eur"
+    }
+  }
+)
+```
+
+### Result
+
+### Calculate Prices with Exact Match
+
+### Code
+
+```ts
+const price = await pricingModuleService.calculatePrices(
+  { id: [priceSet.id] },
+  {
+    context: {
+      currency_code: "eur",
+      region_id: "reg_123",
+      city: "warsaw"
     }
   }
 )
 ```
 
 ### Result
 
-### Calculate Prices with Rules
+### Calculate Prices with Partial Match
 
 ### Code
 
@@ -33052,7 +33087,7 @@ const price = await pricingModuleService.calculatePrices(
   { id: [priceSet.id] },
   {
     context: {
-      currency_code: "EUR",
+      currency_code: "eur",
       region_id: "reg_123",
       city: "krakow"
     }
@@ -33075,7 +33110,7 @@ const price = await pricingModuleService.calculatePrices(
         items: [
           {
             id: "item_1",
-            quantity: 2,
+            quantity: 150,
             // assuming the price set belongs to this variant
             variant_id: "variant_1",
             // ...
@@ -33101,29 +33136,29 @@ const priceList = pricingModuleService.createPriceLists([{
   starts_at: Date.parse("01/10/2023").toString(),
   ends_at: Date.parse("31/10/2023").toString(),
   rules: {
-    region_id: ['PL']
+    region_id: ['region_123', 'region_456'],
   },
   type: "sale",
   prices: [
     {
-      amount: 4,
-      currency_code: "EUR",
+      amount: 2,
+      currency_code: "eur",
       price_set_id: priceSet.id,
     },
     {
-      amount: 4.5,
-      currency_code: "EUR",
+      amount: 1.5,
+      currency_code: "usd",
       price_set_id: priceSet.id,
-    },
+    }
   ],
 }]);
 
 const price = await pricingModuleService.calculatePrices(
   { id: [priceSet.id] },
   {
     context: {
-      currency_code: "EUR",
-      region_id: "PL",
+      currency_code: "eur",
+      region_id: "reg_123",
       city: "krakow"
     }
   }

www/apps/resources/app/commerce-modules/pricing/concepts/page.mdx

@@ -30,7 +30,7 @@ Each of these prices is represented by the [Price data model](#price-data-model)
 
 A [PriceList](/references/pricing/models/PriceList) is a group of prices that are only enabled when their conditions and rules are satisfied. For example, you can apply special prices to customers in the VIP group.
 
-When the conditions are met, the prices in the price list override the default prices in a price set.
+When the conditions are met, the prices in the price list can override the default prices in a price set. Learn more in the [Price Calculation](../price-calculation/page.mdx) guide.
 
 A price list has optional `start_date` and `end_date` properties that indicate the date range in which a price list can be applied.