Medusa v2 Pricing and Promotions
Before writing code
Fetch live docs:
- Web-search
site:docs.medusajs.com pricing module for pricing data model and service methods
- Web-search
site:docs.medusajs.com price list rules for conditional pricing configuration
- Web-search
site:docs.medusajs.com promotion module for promotion types and rules
- Fetch
https://docs.medusajs.com/resources/references/pricing and review the IPricingModuleService interface
- Web-search
medusajs v2 tax module region 2026 for latest tax calculation and region setup
Pricing Module Architecture
Entity Relationships
PriceSet
├── Prices[]
│ ├── amount (integer, minor units)
│ ├── currency_code
│ ├── min_quantity, max_quantity
│ └── Rules[] (region_id, customer_group_id)
└── MoneyAmounts[]
Module Links
Product Module (variant) ──link──> Pricing Module (price set)
Region Module ──link──> Pricing Module (price context)
Customer Group ──link──> Pricing Module (group pricing)
Fetch live docs for exact link definitions and how price sets connect to product variants.
Price Calculation
Resolution Flow
Customer Request
└─> Context: { region_id, currency_code, customer_group_id }
└─> Pricing Module: find best matching price
├── Check price lists (sale/override) with rules
├── Check variant prices with matching rules
└─> Return lowest applicable price
Pricing Context
| Context Field | Source | Effect |
|---|
region_id | Cart region | Filters by region-specific prices |
currency_code | Region default | Determines currency |
customer_group_id | Customer profile | Enables group-specific pricing |
quantity | Line item qty | Enables quantity-based tiers |
Price Lists
Types
| Type | Description | Use Case |
|---|
sale | Discounted price (lower than default) | Seasonal sales, flash deals |
override | Replaces default price entirely | B2B/wholesale pricing |
Configuration
| Field | Type | Description |
|---|
title | string | Display name |
status | active/draft | Visibility |
type | sale/override | Price list behavior |
starts_at / ends_at | datetime | Scheduled activation window |
rules | object | Customer group, region conditions |
Key Service Methods
| Operation | Method |
|---|
| Create price set | pricingModuleService.createPriceSets() |
| Add prices | pricingModuleService.addPrices() |
| Create price list | pricingModuleService.createPriceLists() |
| Calculate price | pricingModuleService.calculatePrices() |
Fetch live docs for the full list of rule attributes and how to combine multiple rules.
Regions and Currencies
Region Model
| Field | Type | Description |
|---|
name | string | Display name (e.g., "North America") |
currency_code | string | Default currency (e.g., "usd") |
countries | relation | Countries in this region |
automatic_taxes | boolean | Auto-calculate taxes |
Region-Currency Mapping
| Region | Currency | Countries |
|---|
| North America | usd | US, CA |
| Europe | eur | DE, FR, IT, ES... |
| United Kingdom | gbp | GB |
- Each region has exactly one default currency
- Prices stored in minor units (cents): $10.00 =
1000
Tax Calculation
| Concept | Description |
|---|
| Tax Region | Geographic area with tax rules |
| Tax Rate | Percentage rate for a tax region |
| Tax Line | Calculated tax for a line item |
| Tax Provider | External service (TaxJar, Avalara) or built-in |
Tax Configuration
| Setting | Options | Description |
|---|
automatic_taxes | true/false | Auto-calculate vs manual |
| Tax-inclusive pricing | region setting | Prices include or exclude tax |
| Tax provider | built-in or custom | Calculation engine |
Fetch live docs for tax provider interface and tax-inclusive pricing configuration.
Promotion Module
Promotion Types
| Type | Description | Example |
|---|
standard | Rule-based discounts | 10% off orders over $100 |
buyget | Buy-X-Get-Y promotions | Buy 2 get 1 free |
Promotion Structure
Promotion
├── code (optional coupon), type, is_automatic
├── ApplicationMethod
│ ├── type (percentage, fixed)
│ ├── allocation (each, across)
│ └── target_type (items, shipping, order)
└── Rules[] (attribute, operator, values)
Application Method Types
| Type | Allocation | Description |
|---|
percentage | each | % off each qualifying item |
percentage | across | % off total of qualifying items |
fixed | each | Fixed amount off each item |
fixed | across | Fixed amount off total |
Promotion Rules
| Rule Attribute | Operator | Description |
|---|
customer_group_id | in | Customer group membership |
currency_code | eq | Specific currency |
product_id | in | Specific products |
product_collection_id | in | Specific collections |
Fetch live docs for the complete list of rule attributes and how promotions stack.
Key Service Methods
| Operation | Method |
|---|
| Create promotion | promotionModuleService.createPromotions() |
| Compute actions | promotionModuleService.computeActions() |
| List promotions | promotionModuleService.listPromotions() |
Best Practices
Pricing Strategy
- Store all prices in minor units (cents/pence) — never use decimals
- Create region-specific prices for multi-currency stores
- Use
sale price lists for temporary discounts and override for permanent B2B pricing
Promotions
- Use
is_automatic: true for site-wide promotions (no coupon code needed)
- Combine rules for targeted promotions (e.g., VIP customers + specific collections)
- Test promotion stacking behavior — multiple promotions may apply to the same cart
Tax and Performance
- Enable
automatic_taxes and configure tax regions for each country
- Decide on tax-inclusive vs tax-exclusive pricing per region at setup time
Fetch the Medusa v2 pricing, promotion, and tax module documentation for exact service method signatures, rule configuration, and price resolution logic before implementing.
