Repository navigation
v2.4.0
Mercur v2.4.0
Mercur now connects to more of the outside world. Payouts move to a thin core
module plus a new Stripe connector plugin, and a new Magento 2 connector lets
an external storefront sell marketplace offers. Operators can assign sellers
to regions, the panels get a layout composer and much deeper extension points,
and checkout and vendor lists get a serious performance pass. We also bumped
Medusa to 2.22.0, which requires Node 22.22+, and fixed a batch of cart, offer
and panel bugs. This release has breaking changes, so please read the section
below first.
⚠️ Before you upgrade
- Node 22.22+ and Medusa 2.22.0 (#1685). Medusa 2.22.0 drops Node 20. To pick
up the October 2026 Node.js security releases, we recommend Node 24.22.1+, or
22.23.4+ if you stay on Node 22. - Run migrations. They restructure the payout tables, add the
region_sellerlink,order_group.metadata, a new telemetry table and list
indexes, and makeseller.default_leadtime_to_shipnullable. @mercurjs/payout-stripe-connectis removed (#1693). Install
@mercurjs/stripe-connector-pluginand point the payout module at
@mercurjs/stripe-connector-plugin/providers/payout-stripe-connect. If you
also adopt the plugin's payment provider, addpp_stripe-connector_<id>to
your regions.- The payout module API changed (#1693).
createPayoutWorkflowis replaced bycreateOrderPayoutsWorkflow.- On
IPayoutProvider,createPayoutAccountbecomescreateAccount, and
retrieveAccountandreversePayoutare now required. PayoutStatus.CANCELEDbecomesABORTED; existing rows are migrated.
- Existing sellers have no regions until you assign them (#1665, #1696).
GET /vendor/regionsnow returns assigned regions only,
GET /vendor/regions/:idreturns 404 for the others, and a vendor offer or
shipping price on an unassigned region returns 400. Set a default region
under Settings → Store for new sellers, then link existing ones from the
seller page or withPOST /admin/sellers/:id/regionsand
{ "add": ["reg_…"] }. - New sellers no longer default to a lead time of 2 (#1687, #1730). They
start atnulland use the marketplace default from Settings → Marketplace.
Existing sellers keep their current value, including2; clear a store's lead
time to move it to the marketplace default. If you ran the migration on a
v2.3.9canary, it cleared values of2, so those sellers need them set again. - Offers honour the product–seller allowlist (#1697).
createOffersWorkflownow refuses a product restricted to other sellers or
rejected by the operator. Products with no link stay open to every seller. - Store order groups no longer return
orders.items.variant.product(#1727).
Asking for it explicitly returns 400. Useorders.items.product_handleand
orders.items.product_title. GET /vendor/paymentsscopes through the order's payment collection
(#1678), so shared, uncaptured cart-stage payments are not listed.- Storefront on Next 16 (#1713). Catalog prices are fetched anonymously, so
customer-group price lists no longer show on catalog pages (the cart still
applies them). Canonical and structured-data URLs now come from
NEXT_PUBLIC_BASE_URL. - Mercur now sends anonymous telemetry from your server (#1718, #1725). It's
on by default and prints nothing at boot, and it helps us see how many
installations exist, which versions they run and whether they keep running.- Server: a startup event and a daily heartbeat with a random installation
id, versions, runtime, OS and infrastructure details, feature flags, and
one-time milestones such as the first approved seller or first paid payout.
Marketplace counts are sent as range buckets, never exact numbers. Only
first-party plugins are named; custom ones are just counted. Each event also
says whether the install was seeded with demo data. - CLI: every command now reports its name, flag names, exit code and
duration, with flag values redacted unless they're a boolean or a fixed
choice. It stops sendingblocks.jsoncontents,aliasPrefix, CPU model and
email, and the email prompt is gone. - Opt out with
MERCUR_DISABLE_TELEMETRY,DO_NOT_TRACKor
withMercur({ projectConfig: { mercur: { telemetry: false } } }). It's also
off in CI, underNODE_ENV=testand in worker processes. Set
MERCUR_TELEMETRY_DEBUG=trueto print payloads instead of sending them.
Every event and property is listed on the telemetry docs page.
- Server: a startup event and a daily heartbeat with a random installation
✨ Highlights
💳 Stripe connector plugin
Core payouts are now shaped like Medusa's payment module: one provider per
marketplace, one payout per seller order, and one payout_reversal per later
refund. An order that isn't ready goes on_hold and is re-decided on the next
run. Core still schedules nothing. @mercurjs/stripe-connector-plugin brings
the operations: seven scheduled jobs, settlements that net payouts, reversals
and adjustments per seller and currency, operator adjustments, capture
validation and failed-operation alerts. Operators get Integrations → Stripe and
Settings → Stripe, plus widgets on the seller and order pages. Vendors get their
own Stripe page. (#1693)
🛒 Magento 2 connector
@mercurjs/magento2-connector-plugin lets a Magento 2 storefront sell
marketplace offers while Mercur keeps sellers, split orders, commissions and
payouts. It ships HMAC-signed webhooks with retries and redelivery, and an
external payment provider that authorizes at checkout and captures when Magento
invoices the order. Storefront refunds are mirrored onto the Mercur order, and
there's an admin screen at /settings/magento. The Magento side is the separate
mercurjs/magento2-connector Composer package. (#1683, c5305c2)
🌍 Sellers in regions
Operators decide which regions a seller operates in, from the region page, the
seller page or Create Seller. Vendors see and price only in their assigned
regions, and the offer grids get one column per region. Admin keeps full
visibility of prices across all regions. New sellers get the store's default
region. (#1665)
🧱 Layout composer and deeper panel extensions
Admin product detail and vendor offer detail now render through a
LayoutComposer that uses Medusa's entry ids. Plugins, the Medusa project and
the host app are ordered layers where later wins, and any layer can contribute
routes, widgets, layouts/, _layouts.ts and _navigation.ts (#1674).
Custom-fields configs can also hide, replace or add columns and fields on
embedded tables, spreadsheet grids and built-in form fields, using the existing
list and forms keys (#1701).
🧭 Customizable vendor onboarding
Each onboarding step is now a tab of the seller onboarding form zone, so you
can add, remove, reorder or mark steps optional from a custom-fields config. The
store handle is now required, with a live check against the new
GET /vendor/sellers/handle-availability. Going back after a failed Finish no
longer wipes what the user typed. (#1658)
🏷️ Offer conditions in the panels
Operators manage conditions under Settings → Offer Conditions, and vendors pick
one when creating or editing an offer. (#1657, #1661)
⏱️ Lead time defaults
Lead time gets its UI and a marketplace-wide default, set in Settings →
Marketplace, on the store, and on the offer. GET /store/offers returns
effective_leadtime_to_ship, resolved from offer to store to marketplace.
(#1687)
⚡ Performance
- Fix checkout lock units: timeouts passed in milliseconds meant a lock wait of
about 8 hours and a TTL of about 33. Concurrent completion under
processPaymentWorkflowis now locked too (#1677). - Load the commission rate table once per checkout, and add list indexes on
order groups, offers, payouts, reviews and commission rules (#1677). - Push vendor list seller scoping into SQL
EXISTSsubqueries instead ofid IN
lists that grow with lifetime volume (#1678).
🛍️ Storefront
- Move to Next 16 with Cache Components: every route has a prerendered shell,
the default first page of a listing sits in the HTML, and catalog reads are
cached (#1713). - Add a cart drawer that opens instantly, optimistic cart edits, and a quantity
picker on the product page. Pages no longer wait on the cart (#1711).
🧩 More extension points
offerPricesUpsertedhook, plus previous values, snapshots andupdated_by
on the other offer hooks (#1654).getStatisticson the seller and offer modules, with
GET /admin/sellers/statisticsandGET /admin/offers/statistics(#1659).deleted_atfilter andwith_deletedon admin offers and sellers, so a delta
sync can see removals (#1683).order_group.metadata, copied fromcart.metadata(#1683).POST /store/carts/:id/completenow returns the seller orders (#1697).is_replayon thepaymentRefundedhook (#1685).
Platform
- Bump Medusa to 2.22.0 (#1685).
🐛 Fixes
- Allocate cart credit lines across split orders, so the credit-covered part no
longer shows as owed. Fully credit-covered orders still stay on hold for
payout (#1728). - Compensate commission lines, payment captures and links when checkout is
canceled after completion, so no marketplace records stay behind (#1729). - Confirm offer stock against the cart's total demand per inventory item, so
buyers learn at add-to-cart rather than at checkout (#1668). - Subtract reserved stock from availability on
GET /store/offers(#1669). - Stop Edit prices on a vendor offer from wiping every price when saved before
regions loaded (#1673). - Fix in-place updates of quantity-tiered offer prices never completing (#1654).
- Return
items.offeranditems.offer.selleron store cart routes, so carts
group by the right seller (#1712). - Stop
GET /store/order-groupsreturning 400 withoutfields, which crashed
the storefront's order page (#1727). - Ignore an empty
currency_codeonPOST /store/carts, fix the 500 on
GET /admin/products?sku=, and emitproduct.publishedwhen an admin
publishes a product (#1697). - Add status, bank payout and period end filters to vendor Stripe settlements
(#1731). - Refetch admin and vendor product lists on search, filter and sort (#1708).
- Keep the date filter popover open while typing a custom date (#1671).
- Load plugin extensions in the panels' ESM build, which silently started
without them (#1693). - Set the store default region in the seed, so seeded installs can create priced
sellers (#1696). - Clear peer-dependency warnings on fresh installs by aligning tiptap and pinning
@opentelemetry/api(#1722).
📚 Docs
- Rewrite the architecture page and the platform module docs, with new figures
(#1679, #1680). - Split use cases into standalone marketplace and marketplace inside a store
(#1705). - Split the Magento 2 integration into focused pages and add a demo video (#1706,
#1709). - Point legacy redirects at existing pages (#1656).
🙌 New contributors
Full Changelog: v2.3.7...v2.4.0