Medusa Explained · Pricing · 4/4
Medusa’s Pricing module: understanding tax-exclusive and tax-inclusive prices
The Pricing module in Medusa stores product amounts and selects the one that applies to a sale. It also indicates whether that amount already includes tax, allowing the cart to calculate totals correctly afterwards.
In this article
An amount does not say whether tax is included
A running shoe variant has a price set, a PriceSet, containing a Price in euros:
{
"currency_code": "eur",
"amount": 120
}
Simplified excerpt: only the two fields relevant here are shown.
This 120 is a number of euros, but it is still incomplete for selling. It may be a price excluding tax (HT in French): tax will be added when totals are calculated. It may also be a price including tax (TTC in French): the tax portion is already included in those 120 EUR. A store selling to consumers in France generally displays tax-inclusive prices; a store selling mainly to businesses often works with tax-exclusive prices.
Nothing in the Price records this distinction. It depends on the sales context: the currency, or the region where the sale takes place. Medusa therefore stores it separately, in a single additional entity.
The price preference: PricePreference
A PricePreference declares how to interpret amounts in a given context. To specify that all euro prices are entered including tax:
{
"attribute": "currency_code",
"value": "eur",
"is_tax_inclusive": true
}
Simplified excerpt: the stored object also has an ID (prefix prpref_) and technical timestamps.
The three fields read like a sentence:
attributeidentifies the context criterion. Only two criteria are considered:currency_codeandregion_id.valuespecifies the currency or region concerned, hereeur. For a region, use its ID, for examplereg_123.is_tax_inclusiveistrueif amounts in this context include tax. Its default value isfalse.
There can only be one preference for each criterion–value pair: one for eur, one for any given region. And when no preference applies, Medusa treats amounts as excluding tax.
One essential point to remember: the preference contains no tax rate. It says how to interpret an amount, not how much tax applies to it.
Creating and changing the preference
The Pricing module service exposes the expected operations for this entity:
createPricePreferencesstores one or more preferences;updatePricePreferenceschanges, for example,is_tax_inclusiveon an existing preference;listPricePreferencesretrieves preferences, such as the one for the currencyeur.
An application rarely uses the service directly. The createPricePreferencesWorkflowworkflow, used by the Admin creation route, receives the same data shape:
await createPricePreferencesWorkflow(container).run({
input: [{ attribute: "currency_code", value: "eur", is_tax_inclusive: true }],
})
Creating this preference does not change any price. The Price of 120 EUR remains 120: Medusa does not convert, divide or rewrite existing amounts. Only their interpretation changes. Switching a store from tax-exclusive to tax-inclusive pricing therefore requires reviewing the entered amounts yourself if you want to preserve the same tax-inclusive totals.
The same settings in the Admin
The Medusa Admin presents this setting in two places. In Settings → Store, the store’s currency table includes a column labelled Tax inclusive pricing. In the demo store shown, the euro is set to False : its prices are interpreted as excluding tax.
Tax inclusive pricing, euro set to FalseA region’s detail page, under Settings → Regions, shows the same information for the region. Here, the demo region uses euros, covers France and does not use tax-inclusive pricing.
Tax inclusive pricing set to FalseThese screenshots show where the setting is located; their value, False, differs from the tax-inclusive example above, and they do not illustrate a switch between the two. These screens are used to view and edit currency and region preferences. The Admin offers no other criterion: tax-exclusive and tax-inclusive pricing is configured by currency or region.
What Pricing returns
At the time of sale, the backend asks the module for the applicable price using calculatePrices, passing it a context. This context must contain the currency; the region is added to account for a regional preference:
const [price] = await pricingModuleService.calculatePrices(
{ id: ["pset_01"] },
{ context: { currency_code: "eur" } }
)
With the preference eur set to true, the response looks like this:
{
"currency_code": "eur",
"calculated_amount": 120,
"is_calculated_price_tax_inclusive": true,
"original_amount": 120,
"is_original_price_tax_inclusive": true
}
Simplified response excerpt: other fields omitted.
calculated_amount is the selected amount. is_calculated_price_tax_inclusive says how to interpret it: here, 120 EUR including tax. original_amount is the reference amount, often identical when no special pricing applies; it has its own flag, is_original_price_tax_inclusive.
That is all Pricing contributes to tax handling: an amount and how to interpret it. It does not know the VAT rate, create tax lines or calculate the cart total.
Who calculates the tax?
Three actors share the next steps.
The Tax knows the rates. Using the customer’s address or country and the sales region, it supplies the applicable rates and tax lines through a tax provider (Medusa’s default provider, or an external service connected in its place).
Cart workflows coordinate everything. When a variant enters the cart, they retrieve the amount calculated by Pricing with its tax-exclusive/tax-inclusive flag, then ask the Tax module for each item’s tax lines.
The totals calculation finally combines both pieces of information. Depending on the flag, it extracts tax from a tax-inclusive amount or adds it to a tax-exclusive amount.
Take an isolated example: a single unit of an item, with no other charges or discounts, at an assumed rate of 20 %:
- tax-inclusive amount of 120 EUR: excluding tax = 120 / (1 + 0,20) = 100 EUR, tax = 120 − 100 = 20 EUR. The line totals 120 EUR including tax.
- tax-exclusive amount of 100 EUR: including tax = 100 × (1 + 0,20) = 120 EUR, including 20 EUR in tax.
With the same amount: 120 interpreted as excluding tax, this line would therefore reach 144 EUR including tax. This is exactly the discrepancy the preference prevents: tax is not always “added”; sometimes it is extracted.
Going further: currency and region together
A store can have one preference for the currency and another for a region. If the context contains both currency_code and region_id, Medusa does not automatically favour the region. It takes precedence only when two conditions are met:
- the selected price is itself restricted to that region (it has a
region_idrule matching the context); - that region has a preference.
Otherwise, the preference for the price’s currency applies; and with no preference at all, the amount is interpreted as excluding tax.
For example, the euro is tax-exclusive, but the France region is tax-inclusive. A variant has a general price of 100 EUR and a price of 120 EUR restricted to the France region. For a customer in France, if the 120 EUR price is selected, it is interpreted as including tax. For a variant with only its general euro price, the amount is interpreted as excluding tax, even for this customer in France.
What we know now
A amount: 120 is neither “120 including tax” nor “120 excluding tax” on its own. The Price holds a number and a currency; the PricePreference applicable to the context, by currency or region, says whether that number includes tax. Changing this preference changes how prices are interpreted, not the stored amounts: Medusa does not convert them.
Sources
- Medusa documentation: Tax-Inclusive Pricing, createPricePreferencesWorkflow, Manage Store, Manage Regions.
- Module source code
Pricing: modelPricePreferenceand Pricing module service (calculatePrices,isTaxInclusive).