Highlights
This release open sources the Loyalty plugin and includes breaking changes related to Zod, account creation, and more. Please read carefully before updating.
Zod Updated to v4
🚧 Breaking change
Medusa has been upgraded its Zod dependency from v3 to v4. This includes updates to all internal validation schemas and type definitions. For most users, this upgrade is seamless, but if you're using custom validation schemas or directly interacting with Zod types in your project, you may need to:
- Explicitly install Zod v4.2.0 if you have Zod installed in your backend.
- Update your Zod usage based on their migration guide. We've also drafted the following prompt that you can use with agents like Claude Code to migrate your Zod usage:
Zod Migration Agent Prompt
I've updated my project to v2.14.0 of Medusa, which upgrades Zod to v4. This is a breaking change. Migrate all Zod v3 usage in my project to Zod v4.
Do NOT modify anything inside node_modules or the Medusa packages themselves — only migrate my custom code (e.g. custom API routes, modules, workflows, plugins, validators, admin customizations).
## Breaking changes to fix
### Error customization
- Replace `invalid_type_error` and `required_error` options with the unified `error` param
- BEFORE: z.string({ invalid_type_error: "Not a string", required_error: "Required" })
- AFTER: z.string({ error: (issue) => issue.input === undefined ? "Required" : "Not a string" })
- Rename `errorMap` option to `error` wherever used
### ZodError
- Replace `.format()` and `.flatten()` calls with `z.treeifyError(err)`
- Remove `.formErrors` usage (identical to deprecated `.flatten()`)
- Replace `.addIssue()` / `.addIssues()` calls with direct pushes to `err.issues`
### z.string() format validators
- Replace `z.string().email()` with `z.email()` (top-level)
- Replace `z.string().url()` with `z.url()` (top-level)
- Replace `z.string().uuid()` with `z.uuid()` — note: now RFC 9562 strict; use `z.guid()` if lenient matching is needed
- Replace `z.string().ip()` with `z.ipv4()` or `z.ipv6()` depending on intent
- Replace `z.string().cidr()` with `z.cidrv4()` or `z.cidrv6()` depending on intent
- Replace `z.string().emoji()` with `z.emoji()` (top-level)
- Replace `z.string().base64url()` — note it no longer accepts padding
### z.number()
- Remove any inputs passing Infinity or -Infinity — they are now rejected
- Review `.safe()` usage — it now behaves like `.int()` and rejects floats
### z.object()
- Replace `.strict()` with `z.strictObject({ ... })`
- Replace `.passthrough()` with `z.looseObject({ ... })`
- Replace `.strip()` — it's now the default; just remove it
- Remove `.nonstrict()` — deleted entirely
- Remove `.deepPartial()` — deleted; implement manually if needed
- Replace `.merge(other)` with `.extend(other.shape)` or spreading shapes
### z.nativeEnum()
- Replace `z.nativeEnum(MyEnum)` with `z.enum(MyEnum)` — `z.enum()` now handles
native TypeScript enums directly
### z.array()
- Review `.nonempty()` usage — it now returns `string[]` (not a tuple), so type
inference changes if you relied on the first-element guarantee
### z.record()
- Replace single-argument `z.record(valueSchema)` with `z.record(z.string(), valueSchema)`
### .refine()
- Remove type predicate functions from `.refine()` — they no longer narrow types
- Remove any use of `ctx.path` inside refine callbacks — unavailable in v4
- Remove function as second argument to `.refine()` for custom error messages;
use the `error` option in the options object instead:
- BEFORE: schema.refine(fn, (val) => ({ message: `${val} is invalid` }))
- AFTER: schema.refine(fn, { error: (issue) => `${issue.input} is invalid` })
### Removed APIs
- Remove `z.ostring()`, `z.onumber()`, `z.oboolean()` — use `z.string().optional()` etc.
- Remove `z.literal()` with symbol values
- Remove `.create()` static factory calls — use the `z.*()` functions directly
- Remove `z.promise()` wrappers — await the value before parsing instead
### Internal / advanced usage
- Replace `._def` access with `._zod.def` if you introspect Zod schema internals
- Replace `ZodEffects` type references with the appropriate new types
## Instructions
1. Search the entire project (excluding node_modules) for Zod imports and usage.
2. For each file, apply the relevant fixes above.
3. After migrating, build the Medusa project (`medusa build`) which will run TypeScript type checking to catch any remaining type errors introduced by the generics restructure (ZodType now uses only Output and Input generics instead of three).
4. Run any existing tests to verify runtime behavior is unchanged.
5. Summarize what was changed per file.
#14309
React v19 Support in Icons Package
🚧 Breaking change
The Medusa Icons package has been upgraded to support React v19. If you've installed the icons package directly and haven't upgraded to React v19 yet, you may need to update your React version or pin to an earlier version of the icons package. Otherwise, no action is needed.
#14791
Monorepo Project Structure for New Applications
🚧 Breaking change
The create-medusa-app command and medusa new CLI now create projects using a monorepo structure based on the dtc-starter template. This provides better separation of concerns between the backend and storefront applications, and allows you to deploy your project to Medusa Cloud seamlessly.
yarn dlx create-medusa-app@latest my-medusa-store
# Creates a monorepo with separate backend and storefront packages
With this change, the medusa-starter-default and the Next.js Starter Storefront repositories are now deprecated in favor of the unified monorepo approach.
#14999
HTTP Types Consistent with Zod Schemas
🚧 Breaking change
We've updated our HTTP types exported from @medusajs/framework/types to match exactly the Zod schemas used to validate API routes in the Medusa core. This change doesn't impact most users, and it doesn't impact the API routes interfaces. However, if you've explicitly used or relied any of the following types, make sure to apply the required changes.
HTTP types breaking changes
Renamed types
InventoryLevel renamed to AdminInventoryLevel.AdminPricePreferenceParams renamed to AdminGetPricePreferenceParams.
Properties made required
AdminCreatePricePreference.attribute and .value: changed from optional string? to required string.AdminCreateProductVariantInventoryKit.required_quantity: changed from optional to required.
Properties removed
AdminProductCategoryListParams.name: removed from the filter type.BaseClaimListParams.q: search query field removed (also affects AdminClaimListParams).StoreCustomerAddressFilters.company and .province: removed from store-facing address filters.
Properties with changed types
AdminCreateProductVariantPrice.rules: changed from { region_id: string } | null to Record<string, string> — null is no longer a valid value.AdminUpdateProductVariant.prices: changed from AdminCreateProductVariantPrice[] to AdminUpdateProductVariantPrice[].AdminInventoryItemsParams.location_levels: changed from Record<"location_id", string | string[]> to { location_id?: string | string[] }.metadata in AdminCreateCollection, AdminUpdateCollection, AdminCreateOrderFulfillment, AdminCreateOrderShipment, AdminCreateProductCategory, AdminUpdateProductCategory: changed from Record<string, any> to Record<string, unknown> | null.AdminCreateFulfillmentItem.line_item_id and .inventory_item_id: changed from string | undefined to string | null.- Address string fields in
StoreAddAddress, OrderAddress, AdminFulfillmentDeliveryAddress, BaseCreateCustomerAddress, and BaseUpdateCustomerAddress (first_name, last_name, phone, company, address_1, address_2, city, country_code, province, postal_code, address_name): changed from string | undefined to string | null.
Open Source Loyalty Plugin
The Loyalty Plugin that was previously only available to Medusa Cloud users is now open sourced. It provides features related to gift cards and account credits. You can also build on top of it features like loyalty points, referrals, and more.
To use the Loyalty Plugin, you must install it manually. Run the following command to install it:
yarn add @medusajs/loyalty-plugin # replace with your package manager
Then, add it to your list of plugins in medusa-config.ts:
// medusa-config.ts
import { loadEnv, defineConfig } from '@medusajs/framework/utils'
loadEnv(process.env.NODE_ENV || 'development', process.cwd())
module.exports = defineConfig({
// ...
plugins: [
{
resolve: "@medusajs/loyalty-plugin",
options: { },
}
],
})
Finally, run migrations to create the necessary tables:
npx medusa db:migrate
#14711
Enhanced JavaScript SDK with ESM Support
The Medusa JavaScript SDK now includes explicit .js extensions for all relative imports, ensuring full ESM compliance and better compatibility with modern bundlers and Node.js environments.
#15037
Repository-wide Currency Code Normalization
Currency codes are now consistently normalized across all modules and APIs throughout Medusa. This ensures consistent handling of currency formatting, validation, and storage across cart, order, payment, pricing, and other commerce modules.
#13975
Features
- feat(core-flows,medusa,types): add no_notification to markOrderFulfillmentAsDeliveredWorkflow by @NicolasGorga in #15106
- feat: add support for custom arguments in Twilio Sendgrid email notifications by @420coupe in #14879
- feat(medusa-oas-cli, oas-github-ci): support versioning for outputted oas by @shahednasser in #15123
- feat(dashboard,types): add metadata form to Stock Location by @NicolasGorga in #15025
- feat(core-flows,order,medusa,types): Version shipping method adjustments & implement missing creation flow for versioned adjustments by @NicolasGorga in #14482
- feat(core-flows,order,medusa,types): allow to update the original order.email on order customer transfer requests by @NicolasGorga in #14234
- feat(settings): view configuration enhancement by @adrien2p in #14650
- feat(product,medusa,types): add external id to product tags, collections and types by @asgerjensen in #14855
- feat(admin): add British English for European-style date/time formatting by @mlindholm in #14902
- feat(admin): add Croatian translation by @luxapan in #14919
- feat(order): prevent canceling completed orders by @yangbobo2021 in #14874
- feat(product-category): add external_id to product-category by @asgerjensen in #14799
- feat(core-flows,order,medusa,types): update item metadata on item_update change action by @NicolasGorga in #14570
- feat: Implement event loop instrumentation by @sradevski in #14956
Bugs
- fix(order): remove fields causing excessive stack depth by @shahednasser in #15172
- fix(medusa): optimize currency code normalization migration by @shahednasser in #15165
- fix(loyalty-plugin): migrate to Zod v4 by @shahednasser in #15156
- fix(loyalty-plugin): remove delete gift cards action + cleanup by @shahednasser in #15150
- fix(loyalty-plugin): show gift card products section + error message for expiration date by @shahednasser in #15145
- fix(payment): fix currency code unset when updating payment collection by @shahednasser in #15144
- fix: migrate return reasons list to new DataTable component by @TheSeydiCharyyev in #14916
- fix(medusa): conditionally updated index_data for currency code normalization by @NicolasGorga in #15114
- fix(framework): fix plugin build not outputting server assets by @shahednasser in #15110
- fix(core-flows): consider price and metadata for multiple items linked to a single variant when resolving line action by @NicolasGorga in #14834
- fix: update link for Upgrade Guides in medusa/medusa README.md by @parion in #15038
- fix(dashboard): fix shadowed variable in variant media filters by @ashif323 in #15064
- fix(caching-redis): avoid KEYS scans during tag clears by @flatplanetpl in #14869
- fix(core-flows,types): Fix product export breaking when
sales_channel_id filter is passed by @NicolasGorga in #14450
- fix:#14410: (medusa,utils): add delay between module migrations to prevent timestamp collision by @bhagwatiprasad in #14436
- fix(admin): handle null sales channel references in product list and detail views by @Vitalini in #15009
- fix(promotion): handle fixed discount type in buy-get promotions by @pitzegluck in #14939
- fix(core-flows): force cart refresh on updatePromotionsWorkflow when refreshing items by @NicolasGorga in #14569
- fix(core-flows): ensure full pricing context when adding items to draft order by @NicolasGorga in #14941
Documentation
Chores
Other Changes
New Contributors
- @onwp made their first contribution in #14991
- @TheSeydiCharyyev made their first contribution in #14916
- @420coupe made their first contribution in #14879
- @mlindholm made their first contribution in #14902
- @luxapan made their first contribution in #14919
- @flatplanetpl made their first contribution in #14869
- @yangbobo2021 made their first contribution in #14874
- @parion made their first contribution in #15038
- @ashif323 made their first contribution in #15064
- @pevey made their first contribution in #15037
- @bhagwatiprasad made their first contribution in #14436
- @sradevski made their first contribution in #14956
- @Vitalini made their first contribution in #15009
- @pitzegluck made their first contribution in #14939
- @mabouguerra made their first contribution in #15026
Full Changelog: v2.13.6...v2.14.0
