Medusa Knowledge Patch

Medusa Knowledge Patch

Use this skill for Medusa backend, Admin, plugin, storefront API, SDK, module, workflow, migration, payment, pricing, promotion, fulfillment, inventory, shipping, tax, event, or upgrade work.

Start with the quick references below, then read the topic reference that matches the task. Preserve the stated scope of each behavior, especially experimental status, required migrations, removed fields, and changed method signatures.

Reference index

How to apply this patch

1. Identify the Medusa packages, API surface, or workflow involved in the task.
2. Read the matching reference before changing code or configuration.
3. For an upgrade, check every affected contract: dependencies, migrations, request and response shapes, module links, workflow behavior, and provider interfaces.
4. Keep experimental capabilities marked experimental and do not present their APIs as stable.
5. Do not infer replacement APIs or migration outcomes beyond what a reference states.

Breaking changes and upgrade hazards

Do not remain on 2.8.0

Medusa 2.8.0 can return Product Module service results in an inconsistent order. Positional follow-up work, including price updates in updateProductsWorkflow, can target the wrong product. Upgrade to 2.8.1 as soon as possible.

See Modules, data modeling, catalog, and Query.

Move core dependencies behind the framework

Remove direct dependencies on MikroORM, Awilix, pg, and the MikroORM CLI. Rewrite explicit imports through these framework paths:

• @medusajs/framework/mikro-orm/<subpath>
• @medusajs/framework/awilix
• @medusajs/framework/pg
• @medusajs/framework/opentelemetry/<subpath> for supported OpenTelemetry imports

See Upgrades, runtime, configuration, and CLI.

Migrate custom code to Zod 4.2

Backends that directly install Zod must use 4.2.0. Migrate Zod 3 usage in custom validators, routes, modules, workflows, plugins, and Admin extensions. The detailed rewrite list is in Upgrades, runtime, configuration, and CLI.

Update payment providers to the V2 contract

Payment-provider methods take dedicated single input objects. Providers must throw errors instead of returning errors to the Payment Module. Remove a caller-supplied context from Store payment-session creation requests.

See Payments, pricing, and promotions.

Respect module-link cardinality

link.create enforces declared one-to-one, one-to-many, and many-to-many cardinality. Use isList: true on one endpoint for one-to-many and on both endpoints for many-to-many.

See Modules, data modeling, catalog, and Query.

Update Shipping Option Type relations

The Shipping Option-to-Shipping Option Type relation changed from one-to-one to many-to-one, and its property was renamed. Release migrations apply the schema change.

See Fulfillment, inventory, shipping, and tax.

Update renamed and removed APIs

• Replace deprecated remoteLink and remoteQueryConfig with link and queryConfig. The generated declaration file is now query-entry-points.d.ts.
• Send singular create and delete, plus update, to the inventory location-level batch endpoint.
• Stop sending fulfillment- and payment-status filters removed from validators and request types.
• Remove calls to the removed JavaScript SDK user-creation method.
• Omit the redundant request body when marking a fulfillment delivered through the Admin JS SDK.

See API, authentication, HTTP types, and SDK, Modules, data modeling, catalog, and Query, and Fulfillment, inventory, shipping, and tax.

Update authentication callbacks and password reset

Forward every OAuth callback query parameter, including state and error. If the Auth Module definition is overridden, include the Cache Module dependency because OAuth state is stored there temporarily. Send the password reset token as a Bearer token, and replace reset-event actorType with actor_type.

See API, authentication, HTTP types, and SDK.

Account for removed payment fields

Payment Collections no longer store region_id; payments no longer store cart_id, order_id, or customer_id. Update integrations that read or write those fields.

See Payments, pricing, and promotions.

Check changed line-item and order behavior

Generated line-item titles come from products and subtitles from variants. Completed orders cannot be canceled. An item_update action updates item metadata, and line-action matching also considers price and metadata when multiple order items reference one variant.

See Carts, orders, and workflows.

Reconcile explicit HTTP type consumers

Exports from @medusajs/framework/types now exactly reflect core Zod route schemas. Several names, required fields, removed filters, metadata nullability, and address or fulfillment-item field types changed. Runtime API interfaces did not change.

See API, authentication, HTTP types, and SDK.

Keep direct UI dependencies aligned

Direct @medusajs/icons consumers must use React 19 or pin an earlier Icons release. Projects that directly declare react-router-dom must use 6.30.3. Medusa Next.js storefronts are incompatible with Node.js 25 in the documented release.

See Admin, plugins, and UI and Upgrades, runtime, configuration, and CLI.

High-value capabilities

Cross-module Index queries

The experimental @medusajs/index module can filter Products, Product Variants, Prices, and Sales Channels across module boundaries. It requires installation, registration, its feature flag, and migrations. Query it through query.index; $and, $or, $nin, and $not are supported. Its metadata count is a PostgreSQL planner estimate, not an exact count.

See Modules, data modeling, catalog, and Query.

Cached Query graphs

The early-preview Caching Module supports provider-backed caching, generated keys and tags, and tag invalidation from module-service mutations. Enable its feature flag, register the Redis provider, and opt individual Query graphs into caching. Earlier cache packages are deprecated.

See Upgrades, runtime, configuration, and CLI.

Workflow extension points

Cart workflows expose pre-operation validate hooks. Pricing-sensitive cart, order, shipping-option, claim, exchange, order-edit, and return workflows expose hooks.setPricingContext. Workflow implementations can also access step results through workflow context.

See Carts, orders, and workflows and Payments, pricing, and promotions.

Draft orders

Draft-order workflows and HTTP endpoints support creation and operation. The Draft Order plugin is installed by default from 2.10.0 and adds Admin flows for creating, editing, and finalizing draft orders with custom prices, line items, and shipping methods.

See Carts, orders, and workflows.

Generated custom-module types

Development mode writes valid custom-module container mappings to .medusa/types/module-bindings.d.ts. Generated create and update service methods infer approximate data-model inputs, but every inferred property is optional, so database constraints still matter.

See Modules, data modeling, catalog, and Query.

Promotion controls

Campaign budgets can limit use separately by customer_id, email, or another attribute through USE_BY_ATTRIBUTE. The once allocation method applies a promotion across at most max_quantity cart items, starting with the lowest-priced eligible items. Promotions can also have their own usage limits.

See Payments, pricing, and promotions.

Loyalty and account credits

@medusajs/loyalty-plugin provides gift cards, account credits, and a base for custom loyalty features. Install and register it under plugins, then run migrations.

See Modules, data modeling, catalog, and Query.

Shipping and tax controls

Shipping Option Types are manageable through Admin, the API, and the JS SDK. Promotions can restrict free shipping to selected types, and Tax Regions can define rates for individual Shipping Options.

See Fulfillment, inventory, shipping, and tax and Payments, pricing, and promotions.