An Adobe Commerce upgrade rarely fails because the core platform is hard to update. It fails because a store has 60 to 120 third-party extensions, a heavily customized theme, a PHP version two releases behind, and nobody has a written list of what breaks at checkout when any of those change. The upgrade projects that finish on time treat the version bump as a dependency audit first and a deployment second.
This guide lays out how a realistic upgrade plan is built for a live store: the blockers, the extension audit, the infrastructure prerequisites, the regression scope, and the freeze and rollback setup that make the cutover boring. It sits alongside our broader guide on how to choose the right e-commerce platform for your store, because the decision to upgrade is, for some merchants, also the moment to ask whether they should stay on Magento at all.
In short
- Extensions, custom themes and PHP versions block most Adobe Commerce upgrades, in that order; the core version bump itself is usually the easy part.
- Adobe’s Upgrade Compatibility Tool and a manual composer audit should run before scoping, not after; the report drives the timeline, not the other way around.
- “Zero downtime” means minutes, not zero: database schema changes still need a short maintenance window unless the deployment is blue-green with a compatible schema.
- Test scope is checkout, pricing and integrations first; the catalog page rarely breaks in ways that cost money, the payment step does.
- Budget 6 to 16 weeks for a mid-size store on a recent release line and considerably more for stores several minor versions behind, according to ranges commonly reported by Magento agencies.
Why upgrades slip and what usually blocks them
Upgrade projects stall for a predictable set of reasons, and almost none of them are inside the Adobe Commerce core. The parts that break are the parts the merchant added on top over five or eight years.
The first blocker is extension compatibility. A mature store carries dozens of modules from Marketplace vendors, boutique agencies and internal developers. Each one declares supported Magento and PHP versions in its composer.json, and each vendor decides independently when, or whether, to publish a compatible release. A single abandoned module that touches checkout can hold an entire upgrade hostage.
The second blocker is the custom theme. Stores built on a heavily modified Luma theme inherit years of layout XML overrides, template copies and JavaScript patches. When Adobe changes a core template or a Knockout component, those copies silently drift from the parent and produce regressions that only show up on a specific page in a specific browser.
The third blocker is infrastructure drift. Each 2.4.x release narrows the supported PHP range, moves the database, search engine, cache and queue versions forward, and sometimes drops an option altogether. A store that has been running the same server stack since its launch typically needs to move PHP, MySQL or MariaDB, OpenSearch, Redis and Composer in the same project, and every one of those changes has its own regression surface.
The stalled six month project
The pattern behind a stalled upgrade looks the same across agencies. A team estimates the work from the core version delta, then discovers extension conflicts one by one as composer update fails or as staging pages error. Each discovery triggers a vendor ticket, a replacement search or a rewrite, and the timeline extends in two week increments.
Six months later the store is still on the old version and the merchant has paid for two parallel codebases. The fix is to move all of that discovery to the front of the project, before the timeline is committed. As we noted in Magento in 2026: who still needs Adobe Commerce, the merchants who still benefit from the platform are the ones with the engineering discipline to run it, and the upgrade is where that discipline is tested.
Which version delta you are actually crossing
Not every upgrade is the same size. A security patch release (for example moving from one -p patch to the next on the same release line) is typically a small change set. A minor version move within the 2.4 line (for example 2.4.6 to 2.4.8) changes framework dependencies and may deprecate modules. Anything crossing from 2.3 to 2.4 is a platform migration in all but name.
| Upgrade type | Typical scope | Main risk | Usual effort for a mid-size store |
|---|---|---|---|
Security patch (same release line, new -p patch) |
Core security fixes only, no new features | Patches that touch a customized core file | Days, including regression on checkout |
| Minor version (2.4.x to 2.4.y) | Framework and dependency updates, deprecations, new PHP range | Extension incompatibility, PHP migration, theme regressions | 6–16 weeks |
| Major line (2.3 to 2.4) | Search engine change, PHP major bump, removed modules, database changes | Everything above plus infrastructure rebuild | 3–6 months or more |
| Cloud infrastructure metapackage bump | Same as minor version plus ECE-Tools and services updates | Build and deploy hook changes, services version mismatches | 6–16 weeks |
Adobe publishes the supported upgrade paths and release notes on Experience League, and those pages, not agency folklore, should define which intermediate versions a store has to pass through.
Mapping extension compatibility before scoping
The single most valuable week in an upgrade project is the one spent on the extension inventory. Every module installed on the store is listed, its source is identified, its declared compatibility is checked against the target version, and a decision is recorded: upgrade, replace, remove or rewrite. Only after that list exists can anyone quote a credible timeline.
Start from the actual code, not from memory. composer show lists every Composer-managed package with its version, and the app/code directory reveals modules that were installed by copying files rather than through Composer. The second group is the dangerous one because it has no version metadata and often no vendor still supporting it.
Running the Upgrade Compatibility Tool
Adobe ships a command line utility called the Upgrade Compatibility Tool that scans a codebase against a target Adobe Commerce version and reports deprecated API usage, removed classes and known incompatibilities in custom and third-party code. It is available to Adobe Commerce license holders through Adobe’s repository and documented on Experience League. The report is not perfect, but it turns “we think the checkout module might break” into a list of specific files and lines.
Run it against the current production code, not a cleaned-up branch. Treat every critical finding as a work item with an owner. Findings inside a vendor module go to the vendor; findings in custom modules go to the in-house or agency team. The tool’s output is the first artifact a project manager should ask for, because it is the closest thing to an objective scope statement the project will get.
Deciding upgrade, replace, remove or rewrite
Every module lands in one of four buckets. The upgrade bucket holds modules whose vendor has already published a compatible release; those are the cheap ones. The replace bucket holds modules whose vendor has gone quiet but whose function is covered by another vendor or, increasingly, by core features that did not exist when the module was bought. The remove bucket is larger than most merchants expect: a store audit routinely turns up modules for a promotion that ended years ago or a shipping carrier no longer used.
The rewrite bucket is where budgets go to die. It holds custom modules that touch checkout, pricing or ERP integration, were written by someone who has since left, and rely on core APIs that the target version deprecates. Each of those needs a developer estimate on its own, and the project timeline should be quoted only after those estimates exist. Our guide to the Magento extension marketplace explained for store owners covers how to judge whether a vendor is still actively maintaining a module before you depend on it for an upgrade.
PHP, database and infrastructure prerequisites
Each Adobe Commerce release line supports a specific range of PHP versions, database versions, search engines, cache and queue services, and Composer. Adobe publishes that matrix on the system requirements page for each release on Experience League, and the matrix changes with every minor version. The upgrade plan needs to list every service that must move and treat each as its own change with its own test.
In practice, the moves that generate the most work are PHP and the search engine. A PHP major or minor bump changes behavior in third-party libraries and in custom code that was never written with strict typing in mind; deprecation notices that were harmless on the old version become fatal errors on the new one. The search engine move is disruptive because Adobe shifted its default engine over recent releases, and stores running an older Elasticsearch need to plan an OpenSearch migration, including reindexing and any custom search configuration.
A prerequisite checklist worth writing down
- PHP version and extensions. Confirm the target version’s supported PHP range on Adobe’s system requirements page, then check every third-party module and library against that PHP version separately from the Magento version.
- Database. Confirm the supported MySQL or MariaDB version, plan the database engine upgrade as its own step, and take a full backup with a tested restore before starting.
- Search. Confirm the supported OpenSearch or Elasticsearch version, budget a full reindex, and test layered navigation and search results on staging.
- Cache and sessions. Confirm supported Redis or Valkey versions; session storage changes can log every customer out if handled badly.
- Message queue. Confirm the supported RabbitMQ version if the store uses asynchronous operations, bulk API or inventory reservations.
- Composer and CLI tooling. Confirm the supported Composer major version and update the deployment scripts that depend on it.
- Web server and TLS. Confirm Nginx or Apache configuration against the new version’s sample configs, and confirm Varnish version if full page cache is in use.
Custom theme and layout regression risk
Theme regressions are the class of bugs most likely to reach customers, because they do not throw errors in logs. A price that renders in the wrong place, a mini cart that stops opening on mobile, a checkout step that loses its validation message: none of those break the server, all of them cost orders.
The mechanism is straightforward. A custom theme overrides core templates and layout files by copying them into the theme directory. When Adobe updates the core versions of those files, the copies do not update, and the theme continues to render old markup against new JavaScript and new block classes. The larger the theme, the larger the surface of stale copies.
Measuring the override surface
A diff of the theme’s template and layout directories against the corresponding core files on the current version shows how far each copy has already drifted; a diff against the target version shows how much the core is about to move. Files where both diffs are large are the priority list for a front-end developer.
Stores on the Luma-based front end should also account for Adobe’s direction of travel: the Luma theme has not been where new front-end investment lands. Many agencies now recommend a Hyvä theme rebuild or a headless storefront instead of another round of Luma patching, and an upgrade project is the natural point to price that decision, even if the answer is to defer it.
Deciding whether to rebuild the front end now
Rebuilding the theme inside the upgrade project doubles the scope and is usually the wrong call for a store that just needs to get onto a supported version. Rebuilding after the upgrade, on a clean and supported base, is cheaper and lower risk. The exception is a store where the override surface is so large that patching it costs as much as replacing it; the diff exercise above is how that judgment gets made with numbers rather than opinions.
Building the test scope: checkout, pricing, integrations
Regression testing an Adobe Commerce upgrade is a prioritization problem. A mid-size store has hundreds of page states and thousands of product configurations; testing all of them is impossible and testing a random sample is useless. The test scope needs to start from where money is lost when something breaks.
That ordering is almost always the same: checkout first, pricing and promotions second, integrations third, then customer account, then catalog and content. Checkout failures cost revenue by the hour. Pricing failures cost margin and create customer service load. Integration failures corrupt orders, inventory and accounting data in ways that take weeks to untangle.
Checkout and payment scenarios
Every payment method configured on the store needs a completed transaction on staging in the payment provider’s sandbox, including the failure paths: declined card, expired authorization, 3-D Secure challenge, cancelled wallet payment. Every shipping method needs a rate request and a label where applicable. Guest checkout, registered checkout, address validation, tax calculation for each configured region, and gift card or store credit redemption each get their own scripted case.
Checkout is also where third-party modules cluster most densely, so it is where the extension audit and the test scope meet. Any module in the upgrade or replace bucket that touches checkout should have a named test case tied to it.
Pricing, promotions and catalog rules
Price display is where theme regressions and business logic regressions overlap. Test tier pricing, customer group pricing, configurable product price ranges, bundle pricing, and every active cart price rule and catalog price rule with its coupon codes and conditions. Compare the totals on staging against the same cart on production line by line; a rounding change in a tax module can shift a total by a cent and still trip an accounting reconciliation.
ERP, OMS, PIM and marketing integrations
Integrations are tested end to end, not by watching the Magento side alone. An order placed on staging should appear in the ERP sandbox with the correct SKUs, quantities, prices, tax lines and customer data, and an inventory update from the ERP should reflect on the storefront. Product and price feeds to advertising platforms, email service provider syncs, review platforms and search personalization vendors each need one full cycle.
Where a store uses asynchronous operations through the message queue, the test has to confirm that consumers start and process messages on the new version. A queue consumer that silently fails to start is one of the more common post-upgrade surprises, and it presents as inventory or order status quietly falling behind rather than as an error page.
Freeze windows, deploy strategy and rollback
The word “zero downtime” is used loosely in Adobe Commerce upgrades, and the plan should use it precisely. Static content and code can be deployed without taking the store offline, and a well-configured pipeline builds static assets before the switch rather than during it. Database schema changes, which most minor version upgrades include, still require the store to be in maintenance mode while setup:upgrade runs, unless the deployment architecture keeps the old application serving traffic against a schema that both versions can use.
Adobe’s cloud deployment documentation describes how build, deploy and post-deploy phases are separated so that the maintenance period is limited to the database update step, and how static content deployment can be moved to the build phase to shorten it. On a well-prepared store that period is measured in minutes. On a store that has not tuned its deployment, it can be an hour or more, mostly spent generating static content and running indexers while customers stare at a maintenance page.
Choosing a deploy strategy
| Deploy strategy | Customer-facing downtime | Rollback path | Prerequisites |
|---|---|---|---|
| In-place deploy with maintenance mode | Minutes to an hour, during schema update and indexing | Restore code and database from pre-deploy snapshot | Tested database restore, static content built in advance |
| Cloud pipeline (build, deploy, post-deploy phases) | Minutes, limited to the deploy phase database step | Redeploy previous release; database restore if schema changed | ECE-Tools current, static content deployed in build phase |
| Blue-green with shared database | Near zero if schema is backward compatible | Switch traffic back to the previous environment | Load balancer control, schema compatibility review, session and cache strategy for both environments |
| Blue-green with database copy and sync | Near zero | Switch traffic back | Order and customer data sync between databases, which is rarely worth the complexity for a version upgrade |
For most mid-size stores the honest answer is the cloud pipeline or a tuned in-place deploy with a short, announced maintenance window at the lowest-traffic hour of the week. True blue-green deployment with a shared database is achievable, but it requires a developer to review every schema change in the target version for backward compatibility with the running version, and that review is a specialist task.
Setting the freeze window
A content and code freeze is the part of the plan that merchandising teams push back on and that engineering teams cannot do without. The freeze covers the period from the final staging sign-off to the post-deploy verification, and during it no promotions, catalog imports, configuration changes or hotfixes go to production unless they are also applied to the release branch. A change made to production during the freeze and not carried into the release is a change that disappears at cutover.
Freezes are shorter when the release branch is kept current with production throughout the project. Teams that rebase the upgrade branch on every production hotfix keep the freeze to a few days; teams that let the branches diverge for months face a painful merge at the end and a freeze of weeks.
Rollback that has actually been rehearsed
A rollback plan that exists only as a document is not a rollback plan. The team should rehearse it on staging: deploy the upgrade, take orders, then roll back and confirm that the store serves and that the orders taken during the upgraded window are either preserved or consciously reconciled. Restoring a database snapshot taken before the deploy will discard any orders placed after it, which is why the rehearsal also decides how those orders will be recovered, whether by exporting them before rollback or by keeping the window short enough that manual re-entry is acceptable.
Define the rollback trigger in advance. Typical triggers are a checkout error rate above a threshold, payment capture failures, or an integration that stops posting orders to the ERP. Name the person with authority to call it, and fix the decision point at a set time after cutover.
Budgeting time and cost honestly
Upgrade budgets fail because they are quoted before the extension inventory and the theme diff exist. A realistic budget is built after both, from a list of work items with individual estimates. The core version bump itself is a small line; the extension work, theme work, infrastructure work and testing are where the money goes, and each scales with how far behind the store has fallen.
Agencies serving mid-market Magento merchants commonly report minor version upgrade projects in the range of 6 to 16 weeks of elapsed time, with cost varying widely by extension count, customization depth and whether infrastructure must move. Stores several minor versions behind, or moving off an unsupported PHP or search engine version, land at the top of that range or beyond. Those figures are industry ranges rather than quotes, and a specific store’s number comes only from its own inventory.
Where the hours actually go
- Discovery and inventory: one to two weeks for the compatibility scan, the extension buckets and the theme diff.
- Extension work: the largest variable, from days for a store with well-maintained Marketplace modules to months for a store with a dozen abandoned custom modules on checkout.
- Infrastructure: one to three weeks, more if the database or search engine moves and the environment is self-managed.
- Theme regression: one to four weeks depending on the override surface measured earlier.
- Testing and sign-off: two to four weeks of scripted regression, integration cycles and fixes, often underestimated by half.
- Cutover and hypercare: the deploy itself plus one to two weeks of heightened monitoring and rapid fixes.
The cost of not upgrading belongs in the same spreadsheet. Running an Adobe Commerce release past the end of its support window means no security patches, which affects PCI DSS compliance posture and insurance conversations, and it means every future upgrade gets larger. Our breakdown of the total cost of ownership for Magento: budgeting beyond licenses puts upgrade cadence alongside hosting, licenses and agency retainers, because a store that budgets for one upgrade every four years is really budgeting for a re-platform.
Adobe Commerce versus Magento Open Source in the budget
The license tier changes the upgrade plan in a few concrete ways. Adobe Commerce customers have access to the Upgrade Compatibility Tool, Adobe support and, on cloud infrastructure, a managed service layer that takes on part of the infrastructure work. Magento Open Source merchants do the same audit with community tooling and carry the full infrastructure burden themselves, which is a large part of why the two editions diverge in real cost. We covered that split in detail in Magento Open Source versus Adobe Commerce: the honest comparison, and the upgrade line item is one of the places where the cheaper license turns out not to be cheaper.
Common mistakes that turn an upgrade into a re-platform
The mistakes below show up in post-mortems often enough to be worth listing as a checklist. Each one is avoidable at the planning stage and expensive to fix once the project is under way.
- Quoting the timeline before the extension inventory. The version delta tells you almost nothing about the effort; the module list tells you almost everything.
- Testing on a staging environment that does not match production. Different PHP minor version, different search engine version or different Redis configuration will hide the bugs that matter most.
- Letting the upgrade branch drift from production for months. The merge at the end becomes its own project and forces a long freeze.
- Bundling a front-end rebuild, a hosting migration and a version upgrade into one launch. Three change sets in one cutover means nobody can tell which one caused the regression.
- Skipping the rollback rehearsal. A database restore that has never been run is a hope, not a plan.
- Treating the -p security patches as optional between upgrades. Falling behind on patches enlarges the next upgrade and exposes the store in the meantime.
FAQ on Adobe Commerce upgrades
How often does Adobe release a new Adobe Commerce version?
Adobe has in recent years released roughly one minor version of the 2.4 line per year, with security patch releases on the supported lines in between. Adobe’s release schedule and its Software Lifecycle Policy on Experience League are the authoritative sources for current dates and end-of-support windows, and both change, so they should be checked at the start of every upgrade project rather than assumed from memory.
Can a store skip several versions and upgrade directly to the latest release?
Often yes, and Adobe’s upgrade documentation describes which paths are supported. Jumping several minor versions compresses every extension incompatibility, PHP change and theme regression into a single change set, which makes root-causing failures harder. Some teams prefer one large jump with a longer test phase; others step through versions to isolate problems. The extension inventory usually decides which approach is cheaper.
What does the Upgrade Compatibility Tool actually check?
The Upgrade Compatibility Tool is Adobe’s command line scanner that analyzes custom and third-party code against a target Adobe Commerce version and reports usage of deprecated or removed classes, methods and APIs, plus other known incompatibility patterns. It does not test business logic, runtime behavior or theme rendering, so it complements rather than replaces regression testing. Its main value is turning vague risk into a specific list of files and findings that can be assigned and estimated.
Is zero-downtime deployment really possible on Adobe Commerce?
Code and static asset deployment can be done without a maintenance page, and Adobe’s cloud tooling is designed to keep the maintenance period limited to the database update step. A true zero-downtime cutover for a version that changes the database schema requires a blue-green setup where both application versions can run against the same schema during the switch, which is a specialist engineering exercise. For most stores, a well-tuned deploy with a few minutes of announced maintenance at the quietest hour is the realistic and honest target.
Should the theme be rebuilt on Hyvä during the upgrade?
Usually not in the same project. Rebuilding the front end inside a version upgrade doubles or triples the scope. The stronger sequence is to upgrade first, stabilize, then rebuild the front end on a clean base. The exception is a store whose theme override surface is so large that re-applying it costs about as much as replacing it, which the theme diff exercise can quantify before the decision is made.
What happens if an extension vendor never releases a compatible version?
The module goes into the replace or rewrite bucket. Replacement means finding another vendor’s module, or a core feature that now covers the need, and migrating configuration and data. Rewrite means a developer patches the existing module for the new version, reasonable for small modules and risky for large unmaintained ones; continuing to run an incompatible module with local patches is technically possible but pushes the same problem into the next upgrade with interest.
How long should the content and code freeze last?
A freeze should cover the period from final staging sign-off through post-deploy verification, typically two to five days for a well-run project. It extends when the upgrade branch has drifted far from production, because the final merge and re-test take longer. Keeping the release branch rebased on every production hotfix throughout the project is the single most effective way to keep the freeze short and the merchandising team on side.
How is a rollback handled if orders were placed after the upgrade went live?
Restoring a pre-deploy database snapshot discards orders placed after the snapshot, so the rollback plan needs a decision on those orders in advance. Common approaches are exporting orders placed during the window before restoring and re-entering them, or keeping the decision window short enough that a handful of manual re-entries is acceptable. Rehearsing the rollback on staging, including that order reconciliation, is what turns the plan from a document into something the team can execute under pressure.
Next steps
The upgrade decision is also a moment to check whether Adobe Commerce is still the right platform for the store’s next five years, and our guide on how to choose the right e-commerce platform for your store lays out the criteria that matter. If the answer is to stay, run the extension inventory and the theme diff this month, get the Upgrade Compatibility Tool report in front of whoever owns the budget, and quote the timeline only after those documents exist. The store that follows that sequence spends its upgrade project fixing known problems rather than discovering them, and the cutover becomes a short, announced, rehearsed event rather than a six month drama.