Modelado de catálogos en Medusa.js: variantes, regiones y precios que escalan

Cómo estructurar productos, variantes y precios en Medusa para manejar múltiples tamaños, colores, regiones y monedas sin complicar el modelo de datos.

Read in English

La estructura de datos de un catálogo en Medusa

En Medusa, un catálogo se organiza en tres capas: Product, ProductVariant y PriceList. Un Product es el concepto raíz (una playera, un curso, un servicio). Las ProductVariants son las versiones concretas que se pueden comprar (playera talla M color negro, playera talla L color blanco). Los PriceLists permiten asignar precios distintos por región, moneda o segmento de cliente.

Las variantes son la unidad de inventario: cada variante tiene su propio SKU, su propio stock y su propio precio base. El frontend muestra el producto; el carrito agrega variantes. Esta separación permite que un producto con 20 combinaciones de talla y color sea un solo objeto en el catálogo sin duplicar la información del producto.

Productos y variantes: options, values y SKUs

Las opciones de un producto definen las dimensiones de variación: Talla, Color, Material. Los values son las opciones concretas: S, M, L para Talla; Negro, Blanco para Color. Medusa genera el producto de opciones multiplicadas; el catálogo las almacena como variantes individuales, no como combinaciones de objetos.

Cada variante necesita un SKU único. El SKU es el identificador operativo: aparece en las guías de envío, en el inventario y en los reportes. Un SKU bien formado incluye el código de producto más los valores de las opciones, por ejemplo PLY-M-NGR para playera talla M color negro. Esa convención facilita la conciliación entre Medusa y sistemas externos.

Crear un producto con variantes y precios multi-moneda via Medusa Admin API.

const product = await medusaAdmin.products.create({
  title: 'Playera clásica',
  status: 'published',
  options: [
    { title: 'Talla' },
    { title: 'Color' },
  ],
  variants: [
    {
      title: 'S / Negro',
      sku: 'PLY-S-NGR',
      inventory_quantity: 50,
      options: [{ value: 'S' }, { value: 'Negro' }],
      prices: [
        { currency_code: 'mxn', amount: 45000 },
        { currency_code: 'usd', amount: 2500 },
      ],
    },
    {
      title: 'M / Negro',
      sku: 'PLY-M-NGR',
      inventory_quantity: 80,
      options: [{ value: 'M' }, { value: 'Negro' }],
      prices: [
        { currency_code: 'mxn', amount: 45000 },
        { currency_code: 'usd', amount: 2500 },
      ],
    },
  ],
});

Precios por región y listas de precio

Medusa maneja precios a través de dos mecanismos: el precio base de cada variante (que se asocia a una moneda) y los PriceLists (que permiten precios alternativos por condiciones específicas). Un PriceList puede representar una promoción temporal, un precio para clientes mayoristas o un precio diferenciado por región.

El precio que Medusa devuelve al frontend ya está calculado considerando la región del carrito y los PriceLists activos. No hay que calcular el precio en el frontend ni hacer llamadas extra a la API. Si el precio de una variante en MXN es distinto al de otra región, se modela con un PriceList para esa región, no duplicando la variante.

El precio base de la variante es por moneda, no por región.
Usa PriceLists para precios segmentados, no para precios base.
Una región puede tener múltiples monedas; Medusa aplica la del carrito.

Categorías, colecciones y búsqueda que escalan

Medusa tiene dos formas de agrupar productos: ProductCategory y ProductCollection. Las categorías son jerárquicas (Ropa > Camisetas > Básicos) y se usan para navegación estructurada. Las colecciones son planas y editoriales (Colección Verano 2026, Destacados) y se usan para páginas de campaña o filtros especiales.

Para búsqueda, Medusa se integra con MeiliSearch y Algolia de forma nativa a través de plugins. El plugin indexa productos automáticamente al crearlos o actualizarlos. Para catálogos grandes (más de 10,000 variantes), el motor de búsqueda externo es imprescindible; depender del endpoint de búsqueda básico de Medusa tiene límites de performance que aparecen antes de lo esperado.

Más artículos

Volver a artículos

Plataformas de pago en México: Stripe, Conekta, Mercado Pago y OpenPay

Comparativa técnica y comercial de las cuatro plataformas más usadas para aceptar pagos en proyectos digitales mexicanos.

3 de junio de 2026

7 min de lectura

Plataformas de envíos en México: Skydropx, EnviosPerros, Pakke y Enviame

Cómo elegir entre los principales agregadores de paquetería para ecommerce en México según volumen, operación y necesidades técnicas.

3 de junio de 2026

7 min de lectura

CMS headless en 2026: PayloadCMS, Strapi, Sanity y Directus

Qué CMS headless elegir según el tipo de proyecto, el control técnico que necesitas y cómo planeas modelar el contenido.

3 de junio de 2026

8 min de lectura