Skip to main content
A variant axis is a multi_select attribute that a product varies along, such as Size or Color. Mercur doesn’t invent its own variant system: each axis is backed by a native Medusa ProductOption, so variants, carts, and orders keep working the way Medusa expects while operators manage sizes and colors as catalog attributes. The Size axis attribute maps each value to a Medusa option value, S to optval_01JD8Q1 and so on, and the Linen shirt selects only S and M, so its variants behind it are S and M. The Size axis attribute maps each value to a Medusa option value, S to optval_01JD8Q1 and so on, and the Linen shirt selects only S and M, so its variants behind it are S and M.

​
The option mirror

When you create a multi_select attribute with is_variant_axis: true, createProductAttributesWorkflow first creates a Medusa ProductOption (id prefix opt) titled with the attribute’s name. It then stores the option’s id on the attribute and each option value’s id on the matching attribute value. The workflows keep the two sides in step. Renaming the attribute renames the option, and adding, renaming, or deleting values rewrites the option’s value list. Deleting the attribute deletes the option.
This run creates the Size attribute, a global Size option with values S, M, and L, and three attribute values pointing at those option values.

​
Global options and exclusive options

Since Medusa 2.16, a product option can be shared by several products, and products attach to it. Mercur uses both kinds of option Medusa offers: Medusa keeps titles of non-exclusive options unique, so two global axis attributes can’t share a name. Inline axes use exclusive options, so two products can each have their own “Cut” axis.

​
A product picks a subset of values

A global axis holds every value the marketplace supports, but one product rarely uses all of them. When you attach the axis with value_ids, the workflow links the option to the product with only the matching option values, and it also links those attribute values to the product through the pivot link.
The product now has the Size option restricted to two values. You change the subset later with an update entry. The workflow moves the option values and the pivot links together.

​
Variants bind to the option by title

Attaching an axis doesn’t create variants. You create variants yourself, and each one names its option values by option title, for example options: { Size: "M" }. Mercur’s createProductsWorkflow takes attributes and variants together, attaches the axes first, and then creates the variants against them.
A product with no axis still needs an option for Medusa to accept variants. createProductsWorkflow gives every new product a placeholder __default__ option and removes it once a real axis is attached.