Medusa Explained · Pricing · 2/4
Medusa’s Pricing module: adapting a price to its context
The Pricing module stores variant prices and selects the one that applies to a given situation. This article shows how a simple rule lets the same variant display a different price in a particular region.
In this article
The starting point
A variant is linked to a PriceSet, which groups its Price objects: each holds an amount, a currency and, if needed, quantity bounds. When we call calculatePrices with a currency, the module selects the matching price.
Take a trainer sold for 90 EUR. The brand decides to offer it for 92 EUR in its Benelux region, where it sells through a different channel. Everywhere else, the price remains 90 EUR. The currency is the same; only the region changes. We therefore need to tell the module: “this amount only applies to this region”.
A rule attached to a price
The 92 EUR price is a second Price in the same PriceSet as the 90 EUR price. What distinguishes it is that it has a price rule : a PriceRule object that sets a condition on the calculation context.
Here is that rule as stored, reduced to its relevant fields:
{
"id": "prule_01",
"price_id": "price_92",
"attribute": "region_id",
"operator": "eq",
"value": "reg_benelux"
}
Other technical fields omitted.
It reads directly: the price price_92 only applies if the context contains region_id equal to reg_benelux. attribute names the data being tested, value the expected value, operator the comparison; eq, equality, is the default value. The price itself maintains a rules_countcounter, set to 1 here. The 90 EUR price has no rules: its rules_count is 0.
A price can have several rules, such as a region and a postcode. In that case, all must be satisfied. This article sticks to just one.
Writing the rule alongside the price
Here, the rule is declared alongside the price, using the addPrices method of the Pricingservice, which adds prices to an existing set:
await pricingModuleService.addPrices({
priceSetId: "pset_basket_42",
prices: [
{
amount: 92,
currency_code: "eur",
rules: { region_id: "reg_benelux" },
},
],
})
The rules field is an input parameter, rather than the stored object. It is a simple { attribut: valeur }dictionary, convenient to write. The module turns each entry into a PriceRule with the eqoperator, and updates rules_count. What we send and what is stored therefore have two different forms; the earlier JSON shows the second.
In practice, a Medusa application most often uses product workflows rather than the Pricing service directly. The regional price then follows the same path as the variant’s other prices.
Calculating with and without a region
The rule is in place. What is now returned by calculatePrices ?
Without a region in the context:
const [price] = await pricingModuleService.calculatePrices(
{ id: ["pset_basket_42"] },
{ context: { currency_code: "eur" } }
)
// price.calculated_amount : 90
With the Benelux region:
const [price] = await pricingModuleService.calculatePrices(
{ id: ["pset_basket_42"] },
{ context: { currency_code: "eur", region_id: "reg_benelux" } }
)
// price.calculated_amount : 92
And with region_id: "reg_france", the result returns to 90. The method returns an array, with one object per set; the comments only show the calculated amount. This object contains other fields, such as the reference amount and selected price.
The context is a free-form JSON object. currency_code is required; quantity is used for quantity bounds; all other keys are compared against the rules.
How the module chooses
Selection happens in two stages: first discard prices that do not apply, then rank those that remain.
Eligibility. A price is a candidate if its currency and quantity bounds match, and if all its rules are satisfied by the context. A partial match is not enough. Three behaviours follow:
- a price without rules remains a candidate in every context, provided the currency and quantity match;
- if the context does not contain
region_id, the 92 EUR price is excluded: its rule cannot be checked; - if the context contains data that no rule uses, such as a country code, it has no effect.
Ranking. Among the candidates, excluding price lists, the module ranks prices with the most rules first, then, in a tie, the lowest amount.
With reg_benelux, both prices are candidates: 90 EUR without a rule, 92 EUR with one rule. The 92 EUR price ranks ahead because it is more specific, even though it is more expensive. The module therefore does not look for the minimum price: it looks for the most specific price for this context, using the amount only to break a tie in specificity.
Quantity bounds do not change their nature when rules are added. They remain fields on the Price (min_quantity, max_quantity), filtered before ranking, and do not become objects of type PriceRule.
Who provides the context
The module guesses nothing. It does not know where the customer is or which cart they are viewing: it compares rules against the context it receives.
The application prepares this context. On the storefront side, the Store API product routes can, for example, accept a region_idparameter, or retrieve the region from the cart, and pass this information to the calculation along with the currency. The signed-in customer’s data is added in the same way on the server. The module thus remains independent of how the region was determined.
In the Admin, a variant’s Prices section shows its current amounts. The native interface is not a generic rule editor, however: a rule on a project-specific attribute is written through code or a workflow.
What we can do now
A price rule attaches a condition to an amount. To sell a variant for 92 EUR in Benelux and 90 EUR elsewhere, simply add to the same PriceSet a price carrying a region_idrule. At calculation time, a price is eligible only if all its rules are satisfied; among eligible prices, the most specific wins, and the amount only breaks ties. The context comes from the backend, and the module simply compares it.
This rule lives on a single price for a single variant. If a condition needs to make negotiated amounts available across dozens of variants at once, for example for a reseller group, it can be grouped: this is the role of price lists, the subject of the next article.
Sources
- Medusa documentation: price rules, including the other available operators; price calculation.