Catalog Modeling in Medusa.js: Variants, Regions, and Prices That Scale

In Medusa, a catalog is organized in three layers: Product, ProductVariant, and PriceList. A Product is the root concept — a t-shirt, a course, a service. ProductVariants are the specific purchasable versions — t-shirt size M color black, t-shirt size L color white. PriceLists allow assigning different prices by region, currency, or customer segment.

Variants are the inventory unit: each variant has its own SKU, its own stock, and its own base price. The frontend displays the product; the cart adds variants. This separation allows a product with 20 size-and-color combinations to be a single object in the catalog without duplicating product information.

A product options define the dimensions of variation: Size, Color, Material. Values are the concrete choices: S, M, L for Size; Black, White for Color. Medusa generates the full option set; the catalog stores them as individual variants, not as combinations of nested objects.

Each variant needs a unique SKU. The SKU is the operational identifier: it appears on shipping labels, in inventory, and in reports. A well-formed SKU includes the product code plus the option values — for example, TEE-M-BLK for a medium black t-shirt. That convention makes reconciliation between Medusa and external systems straightforward.

Medusa manages prices through two mechanisms: the base price of each variant (associated with a currency) and PriceLists (which allow alternative prices under specific conditions). A PriceList can represent a temporary promotion, a wholesale customer price, or a region-differentiated price.

The price Medusa returns to the frontend is already calculated considering the cart region and active PriceLists. There is no need to calculate prices on the frontend or make extra API calls. If a variant price in MXN differs from another region, model it with a PriceList for that region — do not duplicate the variant.

Medusa has two ways to group products: ProductCategory and ProductCollection. Categories are hierarchical (Clothing > T-Shirts > Basics) and used for structured navigation. Collections are flat and editorial (Summer 2026 Collection, Featured) and used for campaign pages or special filters.

For search, Medusa integrates natively with MeiliSearch and Algolia through plugins. The plugin indexes products automatically when they are created or updated. For large catalogs — more than 10,000 variants — an external search engine is essential; relying on the basic Medusa search endpoint has performance limits that appear earlier than expected.