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

Price Lists

Types

Configuration

Key Service Methods

Fetch live docs for the full list of rule attributes and how to combine multiple rules.

Regions and Currencies

Region Model

Region-Currency Mapping

• Each region has exactly one default currency
• Prices stored in minor units (cents): $10.00 = 1000

Tax Calculation

Tax Configuration

Fetch live docs for tax provider interface and tax-inclusive pricing configuration.

Promotion Module

Promotion Types

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

Promotion Rules

Fetch live docs for the complete list of rule attributes and how promotions stack.

Key Service Methods

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.