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.