# Medusa v2.20.0 — Release & Upgrade Intelligence
- **Product:** Medusa (https://medusajs.com)
- **Version:** v2.20.0
- **Released:** Sep 02, 2026
- **Impact Score:** 7/10
- **Breaking Changes:** Source flagged
- **Canonical Analysis:** https://changelogs.us/medusajs/updates/v2.20.0/

## Executive Summary (TL;DR)
Medusa v2.20.0. Source highlight: Medusa MCP users can update their project using the following prompt:

## Breaking Changes & Deprecations
- 🚧 Breaking change > This only affects Store API requests that expand deeply nested relations through `fields`. Admin routes are unaffected.
- Breaking Changes - **Relations limit on store routes** — Store API routes now enforce a default relations limit to cap query depth and improve performance. Requests that relied on unbounded relation expansion may see fewer nested associations returned. Run `db:migrate` after upgrading. ([#16688](https://github.com/medusajs/medusa/pull/16688))

## New Features
- **Vector-based search for Medusa Search** — Added foundational vector search support including namespace management, vector ingestion, and improved search-definition APIs. (#16631, #16673, #16676)
- **ESLint plugin: new workflow rules** — Three new rules for `@medusajs/eslint-plugin`: `no-nested-when-then` catches nested `when/then` blocks that silently do not compose correctly; `missing-when-name` requires all `when` calls to have a `name` argument for better traceability; `throw-in-workflow-definition` disallows `throw` statements in workflow definition functions, which must use `MedusaError` in steps instead. (#16520, #16585, #16517)

## Improvements
- **Relations limit on store routes** — Store API routes now enforce a default relations limit to cap query depth and improve performance. Requests that relied on unbounded relation expansion may see fewer nested associations returned. Run `db:migrate` after upgrading. (#16688)

## Bug Fixes
- **Payment provider validation on cart** — Validate that the payment provider selected for a cart actually belongs to the cart's region before processing. (#16690)
- **Store order routes field expansion** — Blocked field-expansion pivot paths on store order routes to prevent information leakage. (#16480)
- **Product category scalar fields** — Return all scalar fields from product category queries when no `select` is specified. (#16493)
- **Variant fields for inventory quantity** — Automatically select required variant fields when inventory quantity is requested; handle `null` variants gracefully. (#16444)
- **Order shipping method fields** — Select shipping method fields correctly when listing orders with totals. (#16241)
- **Credit line totals** — Preserve net negative credit line totals instead of zeroing them out. (#16303)