Skip to content

v2.4.0

Choose a tag to compare

@github-actions github-actions released this 02 Nov 14:16
· 46 commits to main since this release
84fe2e3

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_seller link, order_group.metadata, a new telemetry table and list
    indexes, and make seller.default_leadtime_to_ship nullable.
  • @mercurjs/payout-stripe-connect is removed (#1693). Install
    @mercurjs/stripe-connector-plugin and point the payout module at
    @mercurjs/stripe-connector-plugin/providers/payout-stripe-connect. If you
    also adopt the plugin's payment provider, add pp_stripe-connector_<id> to
    your regions.
  • The payout module API changed (#1693).
    • createPayoutWorkflow is replaced by createOrderPayoutsWorkflow.
    • On IPayoutProvider, createPayoutAccount becomes createAccount, and
      retrieveAccount and reversePayout are now required.
    • PayoutStatus.CANCELED becomes ABORTED; existing rows are migrated.
  • Existing sellers have no regions until you assign them (#1665, #1696).
    GET /vendor/regions now returns assigned regions only,
    GET /vendor/regions/:id returns 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 with POST /admin/sellers/:id/regions and
    { "add": ["reg_…"] }.
  • New sellers no longer default to a lead time of 2 (#1687, #1730). They
    start at null and use the marketplace default from Settings → Marketplace.
    Existing sellers keep their current value, including 2; clear a store's lead
    time to move it to the marketplace default. If you ran the migration on a
    v2.3.9 canary, it cleared values of 2, so those sellers need them set again.
  • Offers honour the product–seller allowlist (#1697).
    createOffersWorkflow now 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. Use orders.items.product_handle and
    orders.items.product_title.
  • GET /vendor/payments scopes 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 sending blocks.json contents, aliasPrefix, CPU model and
      email, and the email prompt is gone.
    • Opt out with MERCUR_DISABLE_TELEMETRY, DO_NOT_TRACK or
      withMercur({ projectConfig: { mercur: { telemetry: false } } }). It's also
      off in CI, under NODE_ENV=test and in worker processes. Set
      MERCUR_TELEMETRY_DEBUG=true to print payloads instead of sending them.
      Every event and property is listed on the telemetry docs page.

✨ 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
    processPaymentWorkflow is 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 EXISTS subqueries instead of id 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

  • offerPricesUpserted hook, plus previous values, snapshots and updated_by
    on the other offer hooks (#1654).
  • getStatistics on the seller and offer modules, with
    GET /admin/sellers/statistics and GET /admin/offers/statistics (#1659).
  • deleted_at filter and with_deleted on admin offers and sellers, so a delta
    sync can see removals (#1683).
  • order_group.metadata, copied from cart.metadata (#1683).
  • POST /store/carts/:id/complete now returns the seller orders (#1697).
  • is_replay on the paymentRefunded hook (#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.offer and items.offer.seller on store cart routes, so carts
    group by the right seller (#1712).
  • Stop GET /store/order-groups returning 400 without fields, which crashed
    the storefront's order page (#1727).
  • Ignore an empty currency_code on POST /store/carts, fix the 500 on
    GET /admin/products?sku=, and emit product.published when 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

  • @rsat made their first contribution in #1668 — thank you!

Full Changelog: v2.3.7...v2.4.0