v2.22.0

<!--

![v2.22.0](https://res.cloudinary.com/dza7lstvk/image/upload/v1792580034/Releases/v2-22-0-e8c8a3.png)

# v2.22.0: Node.js 22 Required, Export Customers, Multiple Payment Accounts

Node.js 20 support has been dropped; v22.22.0 or later is now required. This release also ships customer CSV exports and support for multiple payment accounts in Medusa Payments.

CMS_BREAK -->

## Highlights

### Node.js v22.22.0 or Later Required

🚧 Breaking change

> This change only affects projects running Node.js 20. Projects already on Node.js 22 are unaffected.

Node.js 20 has reached end-of-life and is no longer supported. Medusa now requires Node.js v22.22.0 or later. Update your runtime environment before upgrading to this release.

```bash
node --version  # must print v22.22.0 or higher
```

[#17089](https://github.com/medusajs/medusa/pull/17089)
[#17107](https://github.com/medusajs/medusa/pull/17107)

---

## Configurable HTTP Query Params in Traced Spans

When instrumentation is enabled for HTTP requests, query parameters are now traced in the `url.query` property instead of the `http.url` property. Also, by default, only the values of the `fields`, `expand`, `limit`, `offset`, `order`, and `with_deleted` query parameters are displayed. Other values are traced as `REDACTED`.

You can configure this behavior by setting the `http.allowedQueryParams` option in the instrumentation settings:

```ts
export function register() {
  registerOtel({
    serviceName: "medusajs",
    exporter,
    instrument: {
      http: {
        // change allowed query param values
        allowedQueryParams: ["q", "limit", "offset"],
        // or to allow everything
        // allowedQueryParams: "*",
      },
      workflows: true,
      query: true,
      db: true,
      cache: true,
    },
  })
}
```

---

### Export Customers

Admin users can now export customer data as a CSV file directly from the dashboard. The export is backed by a new workflow and step in `@medusajs/core-flows`, a new admin API endpoint, and a new `admin.customers.export()` method in the JS SDK.

[#16142](https://github.com/medusajs/medusa/pull/16142)

---

### Multiple Payment Accounts for Medusa Payments

Medusa Payments now supports multiple payment provider accounts within the same project. This makes it possible to configure separate payment accounts per region or sales channel without running multiple Medusa instances.

[#17099](https://github.com/medusajs/medusa/pull/17099)

## Features

*   feat(dashboard, core-flows, js-sdk, types, medusa): add export customers feature by [@shahednasser](https://github.com/shahednasser) in [#16142](https://github.com/medusajs/medusa/pull/16142)
*   feat: Support multiple payment accounts for medusa payments by [@sradevski](https://github.com/sradevski) in [#17099](https://github.com/medusajs/medusa/pull/17099)
*   feat: Add missing events for price lists and few others needed to keep a product index up to date by [@sradevski](https://github.com/sradevski) in [#17067](https://github.com/medusajs/medusa/pull/17067)
*   feat(dashboard): add refund reason selector to balance settlement form by [@vansh17June](https://github.com/vansh17June) in [#16669](https://github.com/medusajs/medusa/pull/16669)
*   feat(dashboard): allow removing tracking rows in the create shipment form by [@AndyMik90](https://github.com/AndyMik90) in [#17154](https://github.com/medusajs/medusa/pull/17154)
*   feat(dashboard): add Iran provinces to country-states by [@soroush2025](https://github.com/soroush2025) in [#17199](https://github.com/medusajs/medusa/pull/17199)

## Bugs

*   fix(medusa): stop exporting sensitive HTTP headers and redact URL query params in spans by [@medusa-agents](https://github.com/apps/medusa-agents) in [#17361](https://github.com/medusajs/medusa/pull/17361)
*   fix(auth-emailpass,types): add `requireActorAssociation` option to refuse logins on unassociated actor types by [@medusa-agents](https://github.com/apps/medusa-agents) in [#17347](https://github.com/medusajs/medusa/pull/17347)
*   fix: Correctly reindex id-based filters by [@sradevski](https://github.com/sradevski) in [#17354](https://github.com/medusajs/medusa/pull/17354)
*   fix(auth): update the provider identity matching the entity_id from auth providers by [@medusa-agents](https://github.com/apps/medusa-agents) in [#17337](https://github.com/medusajs/medusa/pull/17337)
*   fix(docs): include imported MDX partials in agent markdown and mark override pages as human-only by [@medusa-agents](https://github.com/apps/medusa-agents) in [#17335](https://github.com/medusajs/medusa/pull/17335)
*   fix(@medusajs/medusa): accept case-insensitive order directions and report single-query errors on POST /store/search by [@medusa-agents](https://github.com/apps/medusa-agents) in [#17313](https://github.com/medusajs/medusa/pull/17313)
*   fix(loyalty-plugin): use one random byte per character in gift-card code generation to restore full entropy by [@medusa-agents](https://github.com/apps/medusa-agents) in [#17315](https://github.com/medusajs/medusa/pull/17315)
*   fix(dashboard): Load additional pages in product organization comboboxes by [@medusa-agents](https://github.com/apps/medusa-agents) in [#17309](https://github.com/medusajs/medusa/pull/17309)
*   fix(payment-stripe): don't fail deleting a payment session whose PaymentIntent already succeeded by [@medusa-agents](https://github.com/apps/medusa-agents) in [#17307](https://github.com/medusajs/medusa/pull/17307)
*   fix(medusa): remove undefined `allowed` from admin customers export query config by [@NicolasGorga](https://github.com/NicolasGorga) in [#17314](https://github.com/medusajs/medusa/pull/17314)
*   fix(workflows-sdk): don't compensate a completed workflow when event release fails by [@medusa-os-bot](https://github.com/apps/medusa-os-bot) in [#17293](https://github.com/medusajs/medusa/pull/17293)
*   fix(workflows-sdk): resolve transform results that have a `key` property by [@medusa-os-bot](https://github.com/apps/medusa-os-bot) in [#17282](https://github.com/medusajs/medusa/pull/17282)
*   fix(product): keep the selected variant id when updating variants and refuse an empty options map by [@medusa-os-bot](https://github.com/apps/medusa-os-bot) in [#17274](https://github.com/medusajs/medusa/pull/17274)
*   fix(core-flows): respect item-level allow_backorder when converting a draft order or confirming an order edit by [@medusa-os-bot](https://github.com/apps/medusa-os-bot) in [#17210](https://github.com/medusajs/medusa/pull/17210)
*   fix(order): return order item quantity and prices when selecting explicit item fields by [@medusa-os-bot](https://github.com/apps/medusa-os-bot) in [#17209](https://github.com/medusajs/medusa/pull/17209)
*   fix(event-bus-redis): push kept events in chunks and preserve the TTL when partially clearing a large event group by [@medusa-os-bot](https://github.com/apps/medusa-os-bot) in [#17208](https://github.com/medusajs/medusa/pull/17208)
*   fix(dashboard): remove stale Persian translation keys by [@soroush2025](https://github.com/soroush2025) in [#17197](https://github.com/medusajs/medusa/pull/17197)
*   fix(test-utils): remove the unused inApp option by [@bhupinder759](https://github.com/bhupinder759) in [#17129](https://github.com/medusajs/medusa/pull/17129)
*   fix(payment,core-flows): let refunds be retried safely with an idempotency key by [@shahednasser](https://github.com/shahednasser) in [#16964](https://github.com/medusajs/medusa/pull/16964)
*   fix: Allow replacing the transport for search by [@sradevski](https://github.com/sradevski) in [#17102](https://github.com/medusajs/medusa/pull/17102)
*   fix: Preserve all parts of provider ID, apply provider ID formatting everywhere by [@sradevski](https://github.com/sradevski) in [#17166](https://github.com/medusajs/medusa/pull/17166)
*   fix(types): type the `status` filter of product list params as an array of statuses by [@shahednasser](https://github.com/shahednasser) in [#17155](https://github.com/medusajs/medusa/pull/17155)
*   fix(js-sdk): don't throw a ReferenceError when setLocale is called outside the browser by [@sarmah-rup](https://github.com/sarmah-rup) in [#17157](https://github.com/medusajs/medusa/pull/17157)
*   fix(loyalty-plugin): make allowed gift card fields matcher more specific by [@NicolasGorga](https://github.com/NicolasGorga) in [#17141](https://github.com/medusajs/medusa/pull/17141)
*   fix(product): detach option values from variants when their option is removed from the product by [@shahednasser](https://github.com/shahednasser) in [#16925](https://github.com/medusajs/medusa/pull/16925)
*   fix(utils): aggregate non-Error promise rejections without crashing by [@fadiroot](https://github.com/fadiroot) in [#17048](https://github.com/medusajs/medusa/pull/17048)
*   fix(medusa): report a failed migration script instead of exiting 0 by [@gautamyash](https://github.com/gautamyash) in [#17035](https://github.com/medusajs/medusa/pull/17035)
*   fix(loyalty-plugin): correct transaction note for store credit debits by [@Suryaprakash1657](https://github.com/Suryaprakash1657) in [#17077](https://github.com/medusajs/medusa/pull/17077)
*   fix(dashboard): show collection update errors by [@ankitbuilds99](https://github.com/ankitbuilds99) in [#17112](https://github.com/medusajs/medusa/pull/17112)
*   fix(dashboard): use display_name from API in regions table countries cell in [#17060](https://github.com/medusajs/medusa/pull/17060)
*   fix(dashboard): use fields in region detail loader query key by [@azzliang6](https://github.com/azzliang6) in [#17084](https://github.com/medusajs/medusa/pull/17084)
*   fix(i18n): correct Czech plural forms for counts of 5 and above by [@Stratkoss](https://github.com/Stratkoss) in [#17083](https://github.com/medusajs/medusa/pull/17083)
*   fix(draft-order): guard customer lists against null entries by [@Dextheking1](https://github.com/Dextheking1) in [#16985](https://github.com/medusajs/medusa/pull/16985)
*   fix(ui): keep the gap between date and time segments in every locale by [@thomassarazin](https://github.com/thomassarazin) in [#16794](https://github.com/medusajs/medusa/pull/16794)
*   fix: correct "seperate" typo in two places by [@Dextheking1](https://github.com/Dextheking1) in [#17039](https://github.com/medusajs/medusa/pull/17039)

## Documentation

*   docs: fix deployments to work for next 15 (temporary) by [@shahednasser](https://github.com/shahednasser) in [#17386](https://github.com/medusajs/medusa/pull/17386)
*   docs(cloud): document hard minimums for search typo tolerance thresholds by [@medusa-agents](https://github.com/apps/medusa-agents) in [#17385](https://github.com/medusajs/medusa/pull/17385)
*   docs: document mcp cloud tools by [@shahednasser](https://github.com/shahednasser) in [#17368](https://github.com/medusajs/medusa/pull/17368)
*   docs: add marketplace integrations guide beyond Meta/Google product feeds by [@medusa-agents](https://github.com/apps/medusa-agents) in [#17365](https://github.com/medusajs/medusa/pull/17365)
*   docs: document Production environment branching and new-environment defaults by [@medusa-agents](https://github.com/apps/medusa-agents) in [#17364](https://github.com/medusajs/medusa/pull/17364)
*   docs: update info in cloud S3 docs by [@NicolasGorga](https://github.com/NicolasGorga) in [#17362](https://github.com/medusajs/medusa/pull/17362)
*   docs(cloud): document search-engine indexing of deployment URLs by [@medusa-agents](https://github.com/apps/medusa-agents) in [#17352](https://github.com/medusajs/medusa/pull/17352)
*   docs: document Create Project button on MCP consent page by [@medusa-os-bot](https://github.com/apps/medusa-os-bot) in [#17358](https://github.com/medusajs/medusa/pull/17358)
*   docs(cloud): add worked explanation of how compute hours accrue by [@medusa-agents](https://github.com/apps/medusa-agents) in [#17353](https://github.com/medusajs/medusa/pull/17353)
*   docs(cloud): explain that deployment and preview URLs are public, and how to gate a storefront with basic auth by [@medusa-agents](https://github.com/apps/medusa-agents) in [#17351](https://github.com/medusajs/medusa/pull/17351)
*   docs: explain how dependencies and workspace packages resolve from .medusa/server by [@medusa-agents](https://github.com/apps/medusa-agents) in [#17327](https://github.com/medusajs/medusa/pull/17327)
*   docs: fixes for agent-friendliness by [@shahednasser](https://github.com/shahednasser) in [#17308](https://github.com/medusajs/medusa/pull/17308)
*   docs: add entry on MCP for gemini cli by [@shahednasser](https://github.com/shahednasser) in [#17292](https://github.com/medusajs/medusa/pull/17292)
*   docs: add agent-friendly actions + fixes by [@shahednasser](https://github.com/shahednasser) in [#17291](https://github.com/medusajs/medusa/pull/17291)
*   docs: fix documentation issues from triage inbox by [@medusa-os-bot](https://github.com/apps/medusa-os-bot) in [#17281](https://github.com/medusajs/medusa/pull/17281)
*   docs: add troubleshooting guide for query not assignable types by [@shahednasser](https://github.com/shahednasser) in [#17202](https://github.com/medusajs/medusa/pull/17202)
*   docs: add n8n docs for connecting to mcp + querying custom data by [@shahednasser](https://github.com/shahednasser) in [#17180](https://github.com/medusajs/medusa/pull/17180)
*   docs: add doc on accessing MCP server from custom agents by [@shahednasser](https://github.com/shahednasser) in [#17178](https://github.com/medusajs/medusa/pull/17178)
*   docs: document onboarding removal and redesigned starters page by [@medusa-os-bot](https://github.com/apps/medusa-os-bot) in [#17167](https://github.com/medusajs/medusa/pull/17167)
*   docs: document starter updates by [@shahednasser](https://github.com/shahednasser) in [#17158](https://github.com/medusajs/medusa/pull/17158)
*   docs: document translation update merging and React version mismatch troubleshooting by [@shahednasser](https://github.com/shahednasser) in [#17152](https://github.com/medusajs/medusa/pull/17152)
*   docs: document organization Connections settings page by [@shahednasser](https://github.com/shahednasser) in [#17142](https://github.com/medusajs/medusa/pull/17142)
*   docs: add section on login with cloud requirement for mcp by [@shahednasser](https://github.com/shahednasser) in [#17138](https://github.com/medusajs/medusa/pull/17138)
*   docs: explain fixed changeset releases by [@ankitbuilds99](https://github.com/ankitbuilds99) in [#17111](https://github.com/medusajs/medusa/pull/17111)
*   docs: document pnpm 12 incompatibility with Cloud storefront builds by [@shahednasser](https://github.com/shahednasser) in [#17125](https://github.com/medusajs/medusa/pull/17125)
*   docs: note regional availability of Cloud free trial by [@shahednasser](https://github.com/shahednasser) in [#17109](https://github.com/medusajs/medusa/pull/17109)
*   docs: clarify fork remote setup by [@ankitbuilds99](https://github.com/ankitbuilds99) in [#17108](https://github.com/medusajs/medusa/pull/17108)
*   docs: fix localization route lists, created_at precision, Redis and MCP notes by [@shahednasser](https://github.com/shahednasser) in [#17103](https://github.com/medusajs/medusa/pull/17103)
*   docs: update claude connector info by [@shahednasser](https://github.com/shahednasser) in [#17106](https://github.com/medusajs/medusa/pull/17106)
*   docs: document conditional proxy check on custom domain DNS page by [@shahednasser](https://github.com/shahednasser) in [#17105](https://github.com/medusajs/medusa/pull/17105)
*   docs: changes to MCP docs by [@shahednasser](https://github.com/shahednasser) in [#17101](https://github.com/medusajs/medusa/pull/17101)
*   docs: fix links in search overview by [@shahednasser](https://github.com/shahednasser) in [#17148](https://github.com/medusajs/medusa/pull/17148)
*   docs: document resuming a Cloud plan after cancellation or trial end by [@shahednasser](https://github.com/shahednasser) in [#17080](https://github.com/medusajs/medusa/pull/17080)
*   docs: fix deleteCascade option name in module link examples by [@shahednasser](https://github.com/shahednasser) in [#17079](https://github.com/medusajs/medusa/pull/17079)
*   docs: document database IP allowlist, free trials, and app authorization by [@shahednasser](https://github.com/shahednasser) in [#17078](https://github.com/medusajs/medusa/pull/17078)
*   docs: fix codex tab in MCP server guide by [@shahednasser](https://github.com/shahednasser) in [#17076](https://github.com/medusajs/medusa/pull/17076)
*   docs: fix a typo in the digital products recipe by [@hungateJoseph](https://github.com/hungateJoseph) in [#17037](https://github.com/medusajs/medusa/pull/17037)
*   docs: remove initial user section from Cloud project creation docs by [@shahednasser](https://github.com/shahednasser) in [#17057](https://github.com/medusajs/medusa/pull/17057)
*   docs: doc changes for next release by [@shahednasser](https://github.com/shahednasser) in [#16926](https://github.com/medusajs/medusa/pull/16926)

## Chores

*   chore: drop Node.js 20 support and require Node.js v22.22.0 or later by [@shahednasser](https://github.com/shahednasser) in [#17107](https://github.com/medusajs/medusa/pull/17107)
*   chore: drop Node.js 20 support and require Node.js v22.15.0 or later by [@shahednasser](https://github.com/shahednasser) in [#17089](https://github.com/medusajs/medusa/pull/17089)
*   chore: add AGENTS.md and improve README.md across packages by [@shahednasser](https://github.com/shahednasser) in [#17382](https://github.com/medusajs/medusa/pull/17382)
*   chore(medusa,utils,modules-sdk,rbac,auth-oidc,test-utils,types): add license key checks by [@NicolasGorga](https://github.com/NicolasGorga) in [#16678](https://github.com/medusajs/medusa/pull/16678)
*   chore(dashboard): add missing translations by [@medusa-os-bot](https://github.com/apps/medusa-os-bot) in [#17332](https://github.com/medusajs/medusa/pull/17332)
*   chore(utils): bump `@graphql-tools/merge` and `@graphql-tools/schema` to pull patched `@graphql-tools/utils` by [@shahednasser](https://github.com/shahednasser) in [#17153](https://github.com/medusajs/medusa/pull/17153)
*   chore(deps): bump the security-updates group across 1 directory with 3 updates by [@dependabot](https://github.com/apps/dependabot) in [#17147](https://github.com/medusajs/medusa/pull/17147)
*   chore(deps): bump figlet to 1.12.0 to fix GHSA-62ch-8vmq-8xm7 by [@medusa-os-bot](https://github.com/apps/medusa-os-bot) in [#17145](https://github.com/medusajs/medusa/pull/17145)
*   chore(deps): bump dompurify from 3.4.13 to 3.4.16 in the security-updates group by [@dependabot](https://github.com/apps/dependabot) in [#17088](https://github.com/medusajs/medusa/pull/17088)
*   chore(deps): bump the security-updates group across 1 directory with 2 updates by [@dependabot](https://github.com/apps/dependabot) in [#17086](https://github.com/medusajs/medusa/pull/17086)
*   chore(deps): bump morgan to 1.12.1 to fix GHSA-9f6g-j8ch-75g4 by [@medusa-os-bot](https://github.com/apps/medusa-os-bot) in [#17085](https://github.com/medusajs/medusa/pull/17085)
*   chore(deps): bump multer from 2.3.0 to 2.4.0 in the security-updates group by [@dependabot](https://github.com/apps/dependabot) in [#17063](https://github.com/medusajs/medusa/pull/17063)
*   chore: improve the tsdocs related to currency lower case by [@shahednasser](https://github.com/shahednasser) in [#17071](https://github.com/medusajs/medusa/pull/17071)
*   chore(docs): Updated API Reference by [@github-actions](https://github.com/apps/github-actions) in [#17054](https://github.com/medusajs/medusa/pull/17054)
*   chore(docs): Generated References by [@github-actions](https://github.com/apps/github-actions) in [#17053](https://github.com/medusajs/medusa/pull/17053)
*   chore(docs): Updated UI Reference by [@github-actions](https://github.com/apps/github-actions) in [#17051](https://github.com/medusajs/medusa/pull/17051)
*   chore(docs): Update version in documentation by [@github-actions](https://github.com/apps/github-actions) in [#17052](https://github.com/medusajs/medusa/pull/17052)

## Other Changes

*   i18n restore dropped placeholders in the ar, el, es, fr and ptPT dashboard locales by [@theluckystrike](https://github.com/theluckystrike) in [#17118](https://github.com/medusajs/medusa/pull/17118)
*   i18n complete the th dashboard locale by [@theluckystrike](https://github.com/theluckystrike) in [#16934](https://github.com/medusajs/medusa/pull/16934)

## New Contributors

* @AndyMik90 made their first contribution in [#17154](https://github.com/medusajs/medusa/pull/17154)
* @soroush2025 made their first contribution in [#17199](https://github.com/medusajs/medusa/pull/17199)
* @azzliang6 made their first contribution in [#17084](https://github.com/medusajs/medusa/pull/17084)
* @thomassarazin made their first contribution in [#16794](https://github.com/medusajs/medusa/pull/16794)
* @fadiroot made their first contribution in [#17048](https://github.com/medusajs/medusa/pull/17048)
* @gautamyash made their first contribution in [#17035](https://github.com/medusajs/medusa/pull/17035)
* @Suryaprakash1657 made their first contribution in [#17077](https://github.com/medusajs/medusa/pull/17077)
* @Stratkoss made their first contribution in [#17083](https://github.com/medusajs/medusa/pull/17083)
* @vansh17June made their first contribution in [#16669](https://github.com/medusajs/medusa/pull/16669)
* @sarmah-rup made their first contribution in [#17157](https://github.com/medusajs/medusa/pull/17157)
* @bhupinder759 made their first contribution in [#17129](https://github.com/medusajs/medusa/pull/17129)
* @hungateJoseph made their first contribution in [#17037](https://github.com/medusajs/medusa/pull/17037)

**Full Changelog**: [v2.21.2...v2.22.0](https://github.com/medusajs/medusa/compare/v2.21.2...v2.22.0)