Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 33 ยท Commerce Modules and the Data Model

Prices, Currencies and Regions

Understand Medusa 2 pricing: price sets, currency and region prices, rules, price lists, tax-inclusive pricing and calculated prices, with a runnable resolver.

"What does this cost?" sounds simple until one product is sold in euros and dollars, has a wholesale price for business customers, a Black Friday sale and a bulk discount. Medusa's Pricing module answers the question with a flexible but consistent model: a price set per variant, many prices inside it, rules that say when each price applies, and price lists that override prices for a time or an audience.

This lesson explains those pieces, how a calculated price is chosen, how regions and tax-inclusive prices interact, and how amounts are stored. The generic ideas are in Pricing Models and Price Rules, Taxes and Representing Money Correctly. Real Medusa code is read-only here; the stand-ins implement a small resolver so you can see the selection rules in action.

Price sets and prices

Each product variant is linked to a price set. A price set is a container of prices; every price has:

  • an amount and a currency code (for example usd);
  • optionally a minimum and maximum quantity, which gives tiered pricing ("10 or more");
  • optionally rules, such as a region_id or a customer_group_id.

Think of a price set as a table of candidates. The question "what does this variant cost in this context?" is answered by picking the most specific candidate that matches.

flowchart TD
    V["Variant"] -.->|"link"| PS["Price set"]
    PS --> P1["USD 20<br/>no rules"]
    PS --> P2["EUR 18<br/>no rules"]
    PS --> P3["EUR 17<br/>rule: region = Germany"]
    PS --> P4["USD 15<br/>min quantity 10"]
    PL["Price list: Spring Sale"] -->|"overrides"| PS

Candidate prices live in a price set; a price list can override some of them for an audience or a period.

Regions and currencies

A region is a market: it has a currency, a set of countries, tax behavior (such as whether taxes are computed automatically) and the payment providers available there. Two regions can share a currency (several euro countries in one region, or separate regions for different tax setups).

In the Store API, a shopper's context usually comes from the region (region_id) or from a currency code. Medusa uses that context to calculate prices: first it filters to prices in that currency, then it considers rules like region_id, then quantity. A region-specific price beats a generic currency price because it is more specific.

Price lists

A price list groups price overrides with conditions. Common uses:

  • Sale: temporary reduced prices, with a start and end date.
  • Override: a replacement price table for a customer group, for example wholesale buyers.

A price list has a status (draft or active), optional starts_at and ends_at, and rules (such as customer groups). When active and applicable, its prices take precedence over the plain prices in the set. When it expires, the base prices apply again automatically. Which one wins when several apply is defined by the platform; a strong habit is to avoid overlapping lists for the same audience so the result is easy to reason about.

How amounts are stored

In e-commerce generally, the safe way to store money is as integers in the smallest currency unit (cents) so that float errors cannot creep in. Medusa 1 followed that convention. Medusa 2 changed it: price amounts are stored as exact decimal numbers in major units, so a US$19.99 price is 19.99, not 1999, and the database uses a precise numeric type plus a raw representation instead of a floating-point field. Because details like this can differ between versions, check the pricing documentation for the version you run, and never do arithmetic on money with plain floating-point numbers in your own code. The stand-ins below use integer cents because it is the simplest correct approach to show the logic, and they convert at the edges.

Tax-inclusive pricing

Some markets show prices that already include tax (VAT countries), others add tax at checkout (the US). Medusa lets you configure whether prices for a currency or region are tax inclusive through price preferences, and the calculated price reports what the shopper sees along with the tax-exclusive and tax-inclusive amounts when taxes are computed. The cart then adds up line items and tax lines consistently. The tax rates themselves come from the Tax module (Fulfillment, Shipping and Tax Providers).

Two practical rules:

  1. Decide per market whether stored prices include tax, and be consistent.
  2. Never "add tax on top" in your frontend. Take the totals the cart returns.

Reading prices from the Store API (read-only)

The Store API returns calculated prices when you ask for them with a region or currency:

Terminal
curl "http://localhost:9000/store/products?region_id=reg_123&fields=*variants.calculated_price" \
  -H "x-publishable-api-key: pk_..."

Each variant then carries a calculated_price with the chosen amount, its currency, and information about the original price when a price list applied. Without a region or currency, you generally get no calculated price, which is a common cause of "my product shows no price" (The Store API).

Stand-in 1: a price resolver with rules and a price list

The resolver below follows the shape described above. It is a stand-in, so the precedence rules are deliberately simple and written out in the code: filter by currency and quantity, prefer rule matches, then let an active price list override the base price.

JS Resolve a calculated price

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice "No GBP price" returns null. In a real shop that means the variant cannot be bought in that currency, which should surface as "unavailable", never as a price of zero.

Stand-in 2: tax-inclusive prices and display money

This second stand-in shows how to split a tax-inclusive price into net and tax with integer math, and how to format cents for display. It mirrors what a checkout must get right when prices include tax. The rate is a made-up example and rounding rules vary by country, see Taxes.

JS Net, tax and display amounts

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The last line shows why the rounding point (per unit or per line) must be a deliberate, documented choice. Medusa's tax module and your tax provider decide it for real orders; do not recompute it on the storefront.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is a price set?

    A price set holds many prices for one variant. The Pricing module picks the best matching one for a given context.
  2. 2. Which price wins when a region-specific EUR price and a generic EUR price both match?

    Rules make a price more specific. The Pricing module prefers the candidate whose rules match the context best.
  3. 3. What does a price list of type "sale" with an end date do after it expires?

    Price lists are time-bounded overrides. Outside their window they are ignored and the underlying price set is used.
  4. 4. Why should your own code avoid floating-point arithmetic on money?

    A value like 0.1 + 0.2 is not exactly 0.3 in binary floating point. Use integers in minor units or an exact decimal type.
  5. 5. A variant shows no price in the storefront. What is a common cause?

    Calculated prices depend on a region or currency context. A missing context or a missing price for that currency gives no calculated price.

Summary

  • Each variant links to a price set; a price set holds prices defined by amount, currency, quantity range and rules.
  • Regions bundle a currency, countries, tax behavior and payment providers, and give the Store API its pricing context.
  • Price lists (sale or override) apply time-bounded or audience-specific prices over the base prices.
  • Medusa 2 stores amounts as exact decimals in major units; never use plain floats for money in your own code.
  • Decide per market whether prices include tax and let the cart compute totals rather than adding tax in the frontend.

Next: Inventory, Stock Locations and Sales Channels