Medusa Explained · Pricing · 1/4
Medusa’s Pricing module: storing a variant’s prices
Medusa is organised into modules: each handles one area of the store, with its own data and operations. The catalogue describes what is sold; the Pricing module holds the amounts. Following a single pair of trainers, from its first price in euros to a bulk purchasing rate, we will see how these amounts are organised, linked to the item and selected at the time of sale.
In this article
One size, a first price
A store sells the Runner trainer in several sizes. A customer does not buy “the Runner” in general: they put a pair in size 42 in their cart. This specific version of a product, the one actually ordered, is called a variant.
The store sells the Runner in size 42 for 90 € per pair. This price consists of two pieces of information: an amount, 90, and a currency, the euro. Without the currency, the number means nothing.
A second currency, priced separately
The store starts selling in the United States. It sets the price of the same pair at 110 $. This amount is not obtained by converting 90 € at the day’s exchange rate: the merchant chooses it, just as they chose 90 €. Each currency therefore has its own amount.
Size 42 now has two prices:
| Currency | Price per pair |
|---|---|
| Euro | 90 € |
| Dollar | 110 $ |
Grouping the prices of a single variant
At the time of sale, the store must be able to answer a simple question: “what are all the prices for the Runner in size 42?” The two amounts are therefore stored together in a single collection specific to this variant. When the store adds a currency, the new price joins the same collection.
Medusa gives each of these two elements a name:
- a
Priceis a price: an amount and its currency, sometimes with conditions of application that we will explore later; - a
PriceSetis the collection that brings together all the prices of a variant.
The collection contains the prices; each price belongs to a single collection.
Linking the collection to the variant
The variant belongs to the catalogue, the Productmodule. The price collection belongs to the Pricingmodule. These two domains remain separate: the catalogue does not store amounts, and the pricing module does not know what a shoe size or a trainer is.
Yet something must record that a particular collection contains the prices for the Runner in size 42. Medusa therefore keeps this association outside both modules, like a mapping record that simply says: this variant, this price collection. Neither the catalogue nor the pricing module needs to know about the other for the association to exist.
This is the point of the collection: a single association is enough to link the variant to all its prices, present and future. No price needs to be linked separately.
An association of this kind, maintained by Medusa between two modules, is called a module link.
What the Admin shows
In the Admin, the detail page for variant 42, opened from the Basket Runner product, shows its prices in a block on the right labelled Prices. It contains the collection’s two amounts: 90 € in euros and 110 $ in dollars. These are the variant’s standard prices; for now, neither depends on the number of pairs purchased.
This block’s menu opens an editing grid. It has one field per currency: the price per pair in euros and dollars can be read or changed there.
A price that depends on quantity
Running clubs buy in bulk. The store decides that, from 5 pairs onwards, each pair costs 80 € instead of 90 €.
A price can therefore have a quantity condition: a minimum number of pairs and, optionally, a maximum. The store adds the 80 € price, starting at 5 pairs with no upper limit. At the same time, it chooses to restrict the 90 € price to purchases of 1 to 4 pairs: the store sets this limit; the module does not infer it. The bounds are inclusive: 4 pairs still cost 90 € each, while 5 pairs cost 80 € each. The dollar price has no quantity condition: it is 110 $ regardless of the number of pairs.
All three prices belong to the same collection, that of the Runner in size 42:
| Currency | Quantity | Price per pair |
|---|---|---|
| Euro | from 1 to 4 pairs | 90 € |
| Euro | from 5 pairs onwards | 80 € |
| Dollar | any quantity | 110 $ |
Choosing the right price at the time of sale
When a customer buys Runner trainers in size 42, the collection offers several prices. The module selects the one matching the currency and number of pairs. What it returns is a unit price : the price of one pair.
The amount for the pairs is then obtained by multiplying this price by the quantity:
- 3 pairs in euros: the selected price is 90 €, making 270 € for the three pairs;
- 5 pairs in euros: the selected price is 80 €, making 400 €.
In the second case, all pairs cost 80 €, not just the fifth. The amount is not 4 × 90 € + 1 × 80 €, but 5 × 80 €.
What the module does, and how the application uses it
The rest of the application does not write prices directly. The Pricing module provides a set of ready-to-use operations, and everything goes through them. This set of operations offered to other parts of the application is called a service.
For a variant’s prices, this service can:
- create a collection with its initial prices;
- read a collection’s prices;
- add, change or remove a price;
- choose the right unit price for a currency and quantity.
Creating a collection is not enough, however: the pricing module does not know about variants, and the new collection is not yet associated with anything. Storing the prices for the Runner in size 42 therefore requires a sequence of operations. If the variant does not yet have a collection, one must be created with its prices, then associated with the variant. If it already has one, it must be found through the association, then its prices updated.
A coordinated sequence of operations like this, drawing on several modules to complete a whole task, is called a workflow. Medusa provides one for this case: upsertVariantPricesWorkflow. It handles the collection, its prices and the association with the variant.
Quantity tiers and the variant detail page
Once the tiers are stored, the detail page for variant 42 shows three rows in its Prices block: 90 € in euros, 80 € in euros and 110 $ in dollars. Nothing indicates that 90 € applies to 1 to 4 pairs and 80 € from 5 onwards. The editing grid still has just one field per currency: 80 in euros and 110 in dollars. The 90 € price no longer appears there, and no field lets you enter a minimum or maximum number of pairs. The bounds remain available in the page’s technical inspection, but not in the price display.
The module can store these tiers and choose the appropriate price. A developer therefore sets them up on a variant through the module’s operations or the workflow. They can also add a panel to the variant detail page to read and edit these tiers.
Key takeaways
A price is an amount in a currency, sometimes restricted to certain quantities. All prices for a variant are stored in one collection. The catalogue and pricing module remain separate, and Medusa keeps the association between the variant and its collection apart. At the time of sale, the currency and number of pairs determine the price of one pair; the amount for all pairs follows from it. Finally, a coordinated sequence of operations creates or updates the collection and associates it with the right variant.
The next article shows how the same variant can cost a different amount depending on the sales context.