Appendix

Updated 11 July 2026

Watch Tutorial Medusa

Reference tables, validation rules, sample configurations, and glossary.

Validation rules

Field Rule

product_id

Required, non-empty string

variant_id

Optional, nullable (null = all variants)

min_qty

Integer ≥ 1

max_qty

Integer ≥ min_qty, or null (open-ended)

price

Positive number

pricing_type

fixed, percentage, or fixed_discount

percentage price

Cannot exceed 100

currency_code

Exactly 3 characters, lowercased

reference_unit_price

Positive or null

customer_group_id

String or null

region_id

String or null

Pricing type formulas

Type Input price Formula

fixed

Unit price

unit = price

percentage

% off

unit = base × (1 − price/100)

fixed_discount

Amount off

unit = max(base − price, 0)

Base = base_unit_price → catalog price → reference_unit_price

Database: quantity_prices

Column Type Notes

id

PK

qprice_…

product_id

text

Required

variant_id

text, nullable

Null = all variants

min_qty

number

≥ 1

max_qty

number, nullable

Null = open-ended

pricing_type

text

Default fixed

price

bigNumber

Tier value

currency_code

text

Lowercase ISO

customer_group_id

text, nullable

B2B (API)

region_id

text, nullable

Regional (API)

reference_unit_price

bigNumber, nullable

Discount fallback

created_at

timestamp

Auto

updated_at

timestamp

Auto

Store API parameters

Param Required Description

product_id

Yes

Product to query

variant_id

No

Variant filter + variant rules

currency_code

No

Filter / calculation currency

quantity

No

Returns calculated_price when set

base_unit_price

No

Override catalog for discounts

customer_group_id

No

B2B segment

region_id

No

Regional context

Admin API – create body fields

Field Required Description

product_id

Yes

Medusa product ID

variant_id

No

Null = all variants

min_qty

Yes

Minimum quantity

max_qty

No

Null = open-ended

pricing_type

No

Default fixed

price

Yes

Tier value

currency_code

Yes

ISO 4217

customer_group_id

No

B2B segment

region_id

No

Regional override

reference_unit_price

No

Manual list price

Sample configuration (3 tiers, fixed)

[
  { "min_qty": 1, "max_qty": 10, "pricing_type": "fixed", "price": 100, "currency_code": "usd" },
  { "min_qty": 11, "max_qty": 50, "pricing_type": "fixed", "price": 90, "currency_code": "usd" },
  { "min_qty": 51, "max_qty": null, "pricing_type": "fixed", "price": 80, "currency_code": "usd" }
]

Glossary

Term Definition

Quantity pricing

Unit price changes based on purchase quantity

Tier

One quantity range + pricing rule

Open-ended tier

No max qty (e.g. 51+)

Breakpoint

Quantity where next tier begins

List price

Catalog price before volume adjustment

Reference unit price

Manual list price when catalog is missing

Fixed price

Tier sets exact unit price

Percentage discount

% off list price

Fixed discount

Fixed amount off per unit

Rule priority

Highest specificity / min_qty wins on overlap

Product-level rule

Applies to all variants (variant_id null)

Variant-specific rule

Applies to one variant only

calculated_price

Store API response with resolved unit price

pricingEngine

Internal Medusa module name

Supported versions

Component Version

Plugin

1.0.1

Medusa

v2.13+

Node.js

20+

Links