medusa-pricing

Medusa v2 Pricing and Promotions

Before writing code

Fetch live docs:

1. Web-search site:docs.medusajs.com pricing module for pricing data model and service methods
2. Web-search site:docs.medusajs.com price list rules for conditional pricing configuration
3. Web-search site:docs.medusajs.com promotion module for promotion types and rules
4. Fetch https://docs.medusajs.com/resources/references/pricing and review the IPricingModuleService interface
5. 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.