www/apps/resources/app/commerce-modules/pricing/price-calculation/page.mdx
import { Tabs, TabsList, TabsTrigger, TabsContent, TabsContentWrapper, TypeList } from "docs-ui"
export const metadata = {
title: Prices Calculation,
}
In this guide, you'll learn how prices are calculated when you use the calculatePrices method of the Pricing Module's main service.
The calculatePrices method 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.
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.
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:
const price = await pricingModuleService.calculatePrices(
{ id: [priceSetId] },
{
context: {
currency_code: "eur",
region_id: "reg_123",
},
}
)
In this example, you retrieve the prices in a price set for the specified currency code and region ID.
For each price set, the calculatePrices method selects two prices:
override;Both prices are returned in an object with the following properties:
<TypeList
types={[
{
name: "id",
type: "string",
description: "The ID of the price set from which the price was selected."
},
{
name: "is_calculated_price_price_list",
type: "boolean",
description: "Whether the calculated price belongs to a price list."
},
{
name: "calculated_amount",
type: "number",
description: "The amount of the calculated price, or null if there isn't a calculated price. This is the amount shown to the customer."
},
{
name: "is_original_price_price_list",
type: "boolean",
description: "Whether the original price belongs to a price list."
},
{
name: "original_amount",
type: "number",
description: "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."
},
{
name: "currency_code",
type: "string",
description: "The currency code of the calculated price, or null if there isn't a calculated price."
},
{
name: "is_calculated_price_tax_inclusive",
type: "boolean",
description: "Whether the calculated price is tax inclusive. Learn more about tax inclusivity in this document"
},
{
name: "is_original_price_tax_inclusive",
type: "boolean",
description: "Whether the original price is tax inclusive. Learn more about tax inclusivity in this document"
},
{
name: "calculated_price",
type: "object",
description: "The calculated price's price details.",
children: [
{
name: "id",
type: "string",
description: "The ID of the price."
},
{
name: "price_list_id",
type: "string",
description: "The ID of the associated price list."
},
{
name: "price_list_type",
type: "string",
description: "The price list's type. For example, sale."
},
{
name: "min_quantity",
type: "number",
description: "The price's minimum quantity condition."
},
{
name: "max_quantity",
type: "number",
description: "The price's maximum quantity condition."
}
]
},
{
name: "original_price",
type: "object",
description: "The original price's price details.",
children: [
{
name: "id",
type: "string",
description: "The ID of the price."
},
{
name: "price_list_id",
type: "string",
description: "The ID of the associated price list."
},
{
name: "price_list_type",
type: "string",
description: "The price list's type. For example, sale."
},
{
name: "min_quantity",
type: "number",
description: "The price's minimum quantity condition."
},
{
name: "max_quantity",
type: "number",
description: "The price's maximum quantity condition."
}
]
}
]}
sectionTitle="Returned Calculated Price"
/>
When the calculated price isn't from a price list of type override, the original price is selected based on the following logic:
Consider the following price set, which has a default price, prices with rules, and tiered pricing:
const priceSet = await pricingModuleService.createPriceSets({
prices: [
// default price
{
amount: 5,
currency_code: "eur",
rules: {},
},
// prices with rules
{
amount: 4,
currency_code: "eur",
rules: {
region_id: "reg_123",
},
},
{
amount: 4.5,
currency_code: "eur",
rules: {
city: "krakow",
},
},
{
amount: 3.5,
currency_code: "eur",
rules: {
city: "warsaw",
region_id: "reg_123",
},
},
// tiered price
{
amount: 2,
currency_code: "eur",
min_quantity: 100,
},
],
})
```ts
const price = await pricingModuleService.calculatePrices(
{ id: [priceSet.id] },
{
context: {
currency_code: "eur"
}
}
)
```
</TabsContent>
<TabsContent value="result">
The returned price is:
```ts
const price = {
id: "<PRICE_SET_ID>",
is_calculated_price_price_list: false,
calculated_amount: 5,
is_original_price_price_list: false,
original_amount: 5,
currency_code: "eur",
is_calculated_price_tax_inclusive: false,
is_original_price_tax_inclusive: false,
calculated_price: {
price_id: "<DEFAULT_PRICE_ID>",
price_list_id: null,
price_list_type: null,
min_quantity: null,
max_quantity: null,
},
original_price: {
price_id: "<DEFAULT_PRICE_ID>",
price_list_id: null,
price_list_type: null,
min_quantity: null,
max_quantity: null,
},
}
```
- Original price selection: Since there are no provided rules in the context, the original price is the default price of the price set.
- Calculated price selection: Since there are no associated price lists, the calculated price is set to the original price.
</TabsContent>
```ts
const price = await pricingModuleService.calculatePrices(
{ id: [priceSet.id] },
{
context: {
currency_code: "eur",
region_id: "reg_123",
city: "warsaw"
}
}
)
```
</TabsContent>
<TabsContent value="result">
The returned price is:
```ts
const price = {
id: "<PRICE_SET_ID>",
is_calculated_price_price_list: false,
calculated_amount: 3.5,
is_original_price_price_list: false,
original_amount: 3.5,
currency_code: "eur",
is_calculated_price_tax_inclusive: false,
is_original_price_tax_inclusive: false,
calculated_price: {
price_id: "<FOURTH_PRICE_ID>",
price_list_id: null,
price_list_type: null,
min_quantity: null,
max_quantity: null,
},
original_price: {
price_id: "<FOURTH_PRICE_ID>",
price_list_id: null,
price_list_type: null,
min_quantity: null,
max_quantity: null,
},
}
```
- Original price selection: The fourth price in the price set is selected as the best price because it matches both the `region_id` and `city` rules.
- Calculated price selection: Since there are no associated price lists, the calculated price is set to the original price.
</TabsContent>
```ts
const price = await pricingModuleService.calculatePrices(
{ id: [priceSet.id] },
{
context: {
currency_code: "eur",
region_id: "reg_123",
city: "krakow"
}
}
)
```
</TabsContent>
<TabsContent value="result">
The returned price is:
```ts
const price = {
id: "<PRICE_SET_ID>",
is_calculated_price_price_list: false,
calculated_amount: 4,
is_original_price_price_list: false,
original_amount: 4,
currency_code: "eur",
is_calculated_price_tax_inclusive: false,
is_original_price_tax_inclusive: false,
calculated_price: {
price_id: "<SECOND_PRICE_ID>",
price_list_id: null,
price_list_type: null,
min_quantity: null,
max_quantity: null,
},
original_price: {
price_id: "<SECOND_PRICE_ID>",
price_list_id: null,
price_list_type: null,
min_quantity: null,
max_quantity: null,
},
}
```
- Original price selection: The second price in the price set is selected as the best price because it matches the `region_id` rule.
- Although the third price also matches a rule (`city`), the second price is selected because it appears first in the price set.
- Calculated price selection: Since there are no associated price lists, the calculated price is set to the original price.
</TabsContent>
```ts
const price = await pricingModuleService.calculatePrices(
{ id: [priceSet.id] },
{
context: {
cart: {
items: [
{
id: "item_1",
quantity: 150,
// assuming the price set belongs to this variant
variant_id: "variant_1",
// ...
}
],
// ...
}
}
}
)
```
</TabsContent>
<TabsContent value="result">
The returned price is:
```ts
const price = {
id: "<PRICE_SET_ID>",
is_calculated_price_price_list: false,
calculated_amount: 2,
is_original_price_price_list: false,
original_amount: 2,
currency_code: "eur",
is_calculated_price_tax_inclusive: false,
is_original_price_tax_inclusive: false,
calculated_price: {
price_id: "<FIFTH_PRICE_ID>",
price_list_id: null,
price_list_type: null,
min_quantity: 100,
max_quantity: null,
},
original_price: {
price_id: "<FIFTH_PRICE_ID>",
price_list_id: null,
price_list_type: null,
min_quantity: 100,
max_quantity: null,
},
}
```
- Original price selection: Since the cart's item quantity is `100` or more, the tiered price is selected as the best price.
- Calculated price selection: Since there are no associated price lists, the calculated price is set to the original price.
</TabsContent>
```ts
const priceList = pricingModuleService.createPriceLists([{
title: "Summer Price List",
description: "Price list for summer sale",
starts_at: Date.parse("01/10/2023").toString(),
ends_at: Date.parse("31/10/2023").toString(),
rules: {
region_id: ['region_123', 'region_456'],
},
type: "sale",
prices: [
{
amount: 2,
currency_code: "eur",
price_set_id: priceSet.id,
},
{
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: "reg_123",
city: "krakow"
}
}
)
```
</TabsContent>
<TabsContent value="result">
The returned price is:
```ts
const price = {
id: "<PRICE_SET_ID>",
is_calculated_price_price_list: true,
calculated_amount: 2,
is_original_price_price_list: false,
original_amount: 4,
currency_code: "eur",
is_calculated_price_tax_inclusive: false,
is_original_price_tax_inclusive: false,
calculated_price: {
price_id: "<FOURTH_PRICE_ID>",
price_list_id: null,
price_list_type: null,
min_quantity: null,
max_quantity: null,
},
original_price: {
price_id: "<PL_PRICE_ID_1>",
price_list_id: "<PRICE_LIST_ID>",
price_list_type: "sale",
min_quantity: null,
max_quantity: null,
},
}
```
- Original price selection: The second price in the price set is selected as the best price because it matches the `region_id` rule.
- Although the third price also matches a rule (`city`), the second price is selected because it appears first in the price set.
- Calculated price selection: The price from the price list is selected as the calculated price because it matches the `region_id` rule of the price list.
</TabsContent>