Announcing Preview of Global Product Options in Medusa

We're releasing global product options as a preview feature in Medusa. Until now, product options like Size or Color were scoped to individual products. This release lets admin users define product options once and reuse them across any number of products.

We're shipping this as a preview to collect feedback before it becomes stable. If you run into issues or have suggestions, please open a GitHub issue.

What global product options change

Previously, each product carried its own isolated set of options. If you had 200 products that all used the same Size option, each one held its own copy. There was no way to standardize values or manage them from a single place.

With global product options, you can:

• Create a product option once from the admin dashboard
• Assign that option to multiple products
• Manage option values centrally, without editing each product individually
• Mix global options with product-specific ones as needed
• Filter products by their options in the storefront

How to install the preview

The feature is available on the Copy to clipboardpreview dist-tag. Follow these steps to enable it:

1. Update all Copy to clipboard@medusajs/* packages to the preview version

In your Copy to clipboardpackage.json, set every Copy to clipboard@medusajs/* dependency to Copy to clipboardpreview:

12345678910111213
{
  "dependencies": {
    "@medusajs/admin-sdk": "options-preview",
    "@medusajs/admin-shared": "options-preview",
    "@medusajs/caching": "options-preview",
    "@medusajs/cli": "options-preview",
    "@medusajs/dashboard": "options-preview",
    "@medusajs/draft-order": "options-preview",
    "@medusajs/framework": "options-preview",
    "@medusajs/medusa": "options-preview",
  }
}

We also recommend removing your Copy to clipboardnode_modules and lock files to ensure the correct versions are installed across all Medusa packages.

Then run your package manager's install command to pull the updated packages.

2. Run database migrations

Your original data will not be impacted by running these migrations. However, you may not be able to revert this change if you choose to use the latest version before this feature is out. Proceed with caution.

12
yarn medusa db:migrate

Or the equivalent for your package manager (Copy to clipboardnpx medusa db:migrate, Copy to clipboardpnpm medusa db:migrate).

This will update your database tables and previously created options to align with the new schema introduced by this release.

3. Update your storefront and backend usages (optional)

If your storefront or custom backend code references product options, you can use the following prompt with an AI coding assistant like Claude Code to update usages to support global product options:

1234567891011121314151617181920
## Context

You are upgrading a Medusa project (backend + storefront) to a Medusa version that introduces **global product options**.

**What changed in Medusa core (PR #13817):**

- Previously, `product_option` records were *exclusive* to a single product. Each product defined its own `Size`, `Color`, etc., and options could not be shared.
- Now, the relationship is many-to-many through two new pivot tables:
  - `product_product_option` — links options to products.
  - `product_product_option_value` — optionally restricts a product to a subset of an option's values.
- `ProductOptionDTO` gained an `is_exclusive: boolean` field. Options created via the legacy embedded-in-product path are `is_exclusive: true`; options created standalone are `is_exclusive: false` and reusable.
- `CreateProductDTO.options` now accepts either:
  1. an inline `CreateProductOptionDTO` (legacy — creates a new exclusive option), or
  2. `{ id: string; value_ids?: string[] }` to link an existing global option (optionally restricting which values are linked).
- The store API accepts `option_value_id` as a list filter on `/store/products` to filter by selected option values.
- New core-flows in `@medusajs/medusa/core-flows`:
  - `createProductOptionsWorkflow` — creates global options.
  - `createAndLinkProductOptionsToProductWorkflow` — add/remove/update options on an existing product.
  - `setProductProductOptionsWorkflow` — low-level set/replace.

Stability and feedback

This is a preview release. The APIs and data model may change before the feature reaches stable. We don't recommend running it in production yet.

If something doesn't work as expected or the behavior isn't what you'd want, let us know by opening a GitHub issue. Direct feedback at this stage shapes what ships as stable.

Get started

Update your packages to Copy to clipboardoptions-preview, run migrations, and give it a try. We're looking forward to hearing what you think.