Let’s talk about how we can build your commerce project — tailored to your business, powered by Mercur
Mercur 2.2.0 shipped on July 9, 2026, and it changes how offers, products, and attributes work at the data layer. Storefronts now query offers directly through the Store API, product attributes run on Medusa's native product options instead of a custom layer, and every new project ships with AI agent documentation out of the box.
The release closed more than 80 pull requests. Two changes are breaking. Below is what shipped, why it matters, and what to check before you upgrade.
Offers move to the Store API
Sellers on Mercur sell through offers, not raw product variants. Before 2.2.0, offer data for the storefront lived behind admin-only endpoints, so most teams patched together their own read layer to show seller offers to buyers.
2.2.0 adds GET /store/offers, a store-facing endpoint for discovering offers directly. Admin offer views now group by seller and include variant counts per seller, so an operator managing hundreds of sellers can see offer coverage at a glance instead of paging through variants one by one.
If your storefront reads product variants directly today, this is the endpoint to move to before the next release removes the old path.
Master products replace duplicate variants
This is the structural change behind the offers work, and it is a breaking change for existing storefronts.
Before 2.2.0, each seller's listing created its own product and variant records, even when ten sellers listed the same physical item. That duplicated catalog data and made cross-seller comparison (the classic "buy box" problem) harder to build well.
2.2.0 introduces shared master products. One product record represents the item; each seller attaches an offer to it with their own price, stock, and fulfillment terms. Store API responses now return master products, and buyers add items to cart by offer ID, not variant ID.
Migration checklist:
- Update storefront cart and PDP logic to read offers via
GET /store/offers, not product variants - Replace any "add to cart by variant ID" call with "add to cart by offer ID"
- Re-run catalog import scripts against the new master product structure if you sync from a PIM or ERP
Attributes now run on Medusa's native product options
Mercur's attribute system used to be a custom layer sitting next to Medusa's product model. In 2.2.0, attributes are rebuilt on top of Medusa's native product options.
The practical effect: product creation and attribute assignment now follow one code path instead of two, which removes a class of edge-case bugs where a custom attribute and a Medusa option disagreed about a product's own data.
This is the second breaking change. Projects with custom attribute logic built against the old layer need to migrate to native product options before upgrading. Check any code that reads or writes attributes directly through the previous custom API.
AI agent support ships in every project
Every new Mercur project now includes documentation scoped for AI coding agents, not just human developers.
- Version-matched docs ship inside the project itself, at
node_modules/@mercurjs/docs/, so an agent working in the repo reads documentation that matches the installed version instead of guessing from the latest online docs - New projects scaffold with
AGENTS.mdandCLAUDE.mdout of the box - An MCP server at docs.mercurjs.com/mcp exposes live documentation search to any MCP-compatible agent
Teams running Claude Code, Cursor, or another agent against a Mercur codebase get grounded, version-correct answers instead of the agent inferring behavior from training data that may already be out of date.
Panel Extension API opens up Admin and Vendor dashboards
2.2.0 ships a Panel Extension API for both the Admin and Vendor dashboards. Developers can now extend widgets, add navigation entries, and register custom fields without forking dashboard code.
Seller-facing forms can now surface custom fields too, and extension fields display consistently across both dashboards. If a client needs a custom onboarding question, a compliance field, or a seller-specific data point in the vendor UI, this is now a supported extension point instead of a dashboard fork.
create-mercur-app upgrades to Medusa 2.17.2
The standalone starter template, generated with bunx create-mercur-app, upgrades to Medusa 2.17.2. New projects come with a fully internationalized dashboard and a seeded demo seller, so a fresh install has working sample data instead of an empty catalog.
How to upgrade
Plan the upgrade in stages - the two breaking changes touch different parts of the codebase and can be tested independently.
- Read the full release notes and changelog before touching production.
- Plan the master products and attributes migrations separately - they touch different parts of the codebase and can be tested independently.
- Update storefront code to call
GET /store/offersand add-to-cart by offer ID. - If you rely on custom attribute logic, migrate it to Medusa's native product options first, in a branch, before merging the rest of the upgrade.
- Re-seed or re-test against
create-mercur-applocally if you want to see the new dashboard internationalization and demo seller before upgrading a live project.
Frequently asked questions
Does upgrading to 2.2.0 break my existing storefront?
Yes, if your storefront reads product variants directly or uses custom attribute logic. Both master products and the attributes rebuild are breaking changes. Review the migration checklist above before upgrading a production project.
What is a master product in Mercur 2.2.0?
A master product is a single shared product record that multiple sellers attach offers to, instead of each seller creating a duplicate product and variant. Buyers now add items to cart by offer ID.
Do I need to change anything if I don't use custom attributes?
If your project only uses Mercur's built-in attribute assignment, the rebuild on Medusa's native product options should not require code changes on your side. Test product creation and attribute display after upgrading to confirm.
What does the new AI agent support actually include?
Every new project ships with version-matched documentation at node_modules/@mercurjs/docs/, plus AGENTS.md and CLAUDE.md scaffolding. An MCP server at docs.mercurjs.com/mcp gives any MCP-compatible agent live documentation search.
Where do I find the complete list of changes?
The full release, including all 80+ merged pull requests and the complete breaking changes list, is on the Mercur GitHub releases page.
