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.
1---2name: medusa-pricing3description: Configure Medusa v2 pricing — pricing module, price lists with rules, currencies, tax calculation, regions, and promotion campaigns. Use when setting up pricing and discounts.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/medusa-pricing7---89# Medusa v2 Pricing and Promotions1011## Before writing code1213**Fetch live docs**:141. Web-search `site:docs.medusajs.com pricing module` for pricing data model and service methods152. Web-search `site:docs.medusajs.com price list rules` for conditional pricing configuration163. Web-search `site:docs.medusajs.com promotion module` for promotion types and rules174. Fetch `https://docs.medusajs.com/resources/references/pricing` and review the `IPricingModuleService` interface185. Web-search `medusajs v2 tax module region 2026` for latest tax calculation and region setup1920## Pricing Module Architecture2122### Entity Relationships2324```25PriceSet26├── Prices[]27│ ├── amount (integer, minor units)28│ ├── currency_code29│ ├── min_quantity, max_quantity30│ └── Rules[] (region_id, customer_group_id)31└── MoneyAmounts[]32```3334### Module Links3536```37Product Module (variant) ──link──> Pricing Module (price set)38Region Module ──link──> Pricing Module (price context)39Customer Group ──link──> Pricing Module (group pricing)40```4142> **Fetch live docs** for exact link definitions and how price sets connect to product variants.4344## Price Calculation4546### Resolution Flow4748```49Customer Request50 └─> Context: { region_id, currency_code, customer_group_id }51 └─> Pricing Module: find best matching price52 ├── Check price lists (sale/override) with rules53 ├── Check variant prices with matching rules54 └─> Return lowest applicable price55```5657### Pricing Context5859| Context Field | Source | Effect |60|---------------|--------|--------|61| `region_id` | Cart region | Filters by region-specific prices |62| `currency_code` | Region default | Determines currency |63| `customer_group_id` | Customer profile | Enables group-specific pricing |64| `quantity` | Line item qty | Enables quantity-based tiers |6566## Price Lists6768### Types6970| Type | Description | Use Case |71|------|-------------|----------|72| `sale` | Discounted price (lower than default) | Seasonal sales, flash deals |73| `override` | Replaces default price entirely | B2B/wholesale pricing |7475### Configuration7677| Field | Type | Description |78|-------|------|-------------|79| `title` | string | Display name |80| `status` | `active`/`draft` | Visibility |81| `type` | `sale`/`override` | Price list behavior |82| `starts_at` / `ends_at` | datetime | Scheduled activation window |83| `rules` | object | Customer group, region conditions |8485### Key Service Methods8687| Operation | Method |88|-----------|--------|89| Create price set | `pricingModuleService.createPriceSets()` |90| Add prices | `pricingModuleService.addPrices()` |91| Create price list | `pricingModuleService.createPriceLists()` |92| Calculate price | `pricingModuleService.calculatePrices()` |9394> **Fetch live docs** for the full list of rule attributes and how to combine multiple rules.9596## Regions and Currencies9798### Region Model99100| Field | Type | Description |101|-------|------|-------------|102| `name` | string | Display name (e.g., "North America") |103| `currency_code` | string | Default currency (e.g., "usd") |104| `countries` | relation | Countries in this region |105| `automatic_taxes` | boolean | Auto-calculate taxes |106107### Region-Currency Mapping108109| Region | Currency | Countries |110|--------|----------|-----------|111| North America | `usd` | US, CA |112| Europe | `eur` | DE, FR, IT, ES... |113| United Kingdom | `gbp` | GB |114115- Each region has exactly **one** default currency116- Prices stored in **minor units** (cents): $10.00 = `1000`117118## Tax Calculation119120| Concept | Description |121|---------|-------------|122| Tax Region | Geographic area with tax rules |123| Tax Rate | Percentage rate for a tax region |124| Tax Line | Calculated tax for a line item |125| Tax Provider | External service (TaxJar, Avalara) or built-in |126127### Tax Configuration128129| Setting | Options | Description |130|---------|---------|-------------|131| `automatic_taxes` | `true`/`false` | Auto-calculate vs manual |132| Tax-inclusive pricing | region setting | Prices include or exclude tax |133| Tax provider | built-in or custom | Calculation engine |134135> **Fetch live docs** for tax provider interface and tax-inclusive pricing configuration.136137## Promotion Module138139### Promotion Types140141| Type | Description | Example |142|------|-------------|---------|143| `standard` | Rule-based discounts | 10% off orders over $100 |144| `buyget` | Buy-X-Get-Y promotions | Buy 2 get 1 free |145146### Promotion Structure147148```149Promotion150├── code (optional coupon), type, is_automatic151├── ApplicationMethod152│ ├── type (percentage, fixed)153│ ├── allocation (each, across)154│ └── target_type (items, shipping, order)155└── Rules[] (attribute, operator, values)156```157158### Application Method Types159160| Type | Allocation | Description |161|------|------------|-------------|162| `percentage` | `each` | % off each qualifying item |163| `percentage` | `across` | % off total of qualifying items |164| `fixed` | `each` | Fixed amount off each item |165| `fixed` | `across` | Fixed amount off total |166167### Promotion Rules168169| Rule Attribute | Operator | Description |170|----------------|----------|-------------|171| `customer_group_id` | `in` | Customer group membership |172| `currency_code` | `eq` | Specific currency |173| `product_id` | `in` | Specific products |174| `product_collection_id` | `in` | Specific collections |175176> **Fetch live docs** for the complete list of rule attributes and how promotions stack.177178### Key Service Methods179180| Operation | Method |181|-----------|--------|182| Create promotion | `promotionModuleService.createPromotions()` |183| Compute actions | `promotionModuleService.computeActions()` |184| List promotions | `promotionModuleService.listPromotions()` |185186## Best Practices187188### Pricing Strategy189- Store all prices in **minor units** (cents/pence) — never use decimals190- Create region-specific prices for multi-currency stores191- Use `sale` price lists for temporary discounts and `override` for permanent B2B pricing192193### Promotions194- Use `is_automatic: true` for site-wide promotions (no coupon code needed)195- Combine rules for targeted promotions (e.g., VIP customers + specific collections)196- Test promotion stacking behavior — multiple promotions may apply to the same cart197198### Tax and Performance199- Enable `automatic_taxes` and configure tax regions for each country200- Decide on tax-inclusive vs tax-exclusive pricing per region at setup time201202Fetch the Medusa v2 pricing, promotion, and tax module documentation for exact service method signatures, rule configuration, and price resolution logic before implementing.