Sylius 2 upgrade guide: planning a 1.14 migration
The official Sylius 2 upgrade guide for a migration from Sylius 1.14 is the file UPGRADE-2.0.md in the Sylius repository. It is a long technical inventory, not a project plan. Before opening it, decide which 2.x version you are aiming for, list what your shop customizes, and treat the upgrade as a small project with its own test phase.
Where the official Sylius 2 upgrade guide stops
The file tells a developer what changed: packages, routes, services, configuration. It warns that even a barely customized application needs manual adjustments before it can run again. What it cannot tell you is how much of that list touches your shop, in what order your team should work, or how to protect sales during the switch. Those answers come from your code.
It also ends at 2.0. Sylius has moved on since then: version 2.3 came out on 28 September 2026, with its own UPGRADE-2.3.md and UPGRADE-API-2.3.md files. A migration planned today therefore reads several documents, not one.
A word on my position: I sell Sylius work, so I have an interest in this subject. I have taken over a Sylius shop with about 15,000 orders, but I have not yet delivered a 1.x to 2.x migration that I could show you as a reference. Ask any provider the same direct question.
Choose the target version first
This is the decision that shapes everything else, and it is more commercial than technical. The support calendar and your dependencies should drive it together.
| Target | Security support | Choose it when |
|---|---|---|
| Sylius 2.2 | Until 31 March 2027 | You depend on an add-on whose listing stops at 2.2 and you accept a second upgrade very soon |
| Sylius 2.3 | Ongoing, no end date listed | Your hosting can run PHP 8.3 and your plugins are confirmed compatible |
Version 2.1 is no longer an option: its security support ended on 30 September 2026. Note too that several official add-ons are listed up to 2.2 at the time of writing, such as the B2B Suite. A listing may lag behind reality, so ask the vendor rather than assume either way.
Inventory your customizations before estimating
Four areas tell you most of what you need to know. The first is overridden services and constructors, because the guide lists many changed signatures and renamed service identifiers. The second is templates: the old template events and Sonata blocks give way to Twig hooks, and any heavily themed storefront is affected. The third is third-party plugins, since each one must have a 2.x version or a replacement. The fourth is payment, because Payum Stripe and PayPal Express Checkout dependencies were removed from the 2.0 composer file and the new Payment Request system changes how gateways plug in.
A team that can produce this inventory in writing, with a line for each customization, is ready to estimate. One that quotes a price from a homepage screenshot is guessing.
A work order that limits risk
What follows is my own suggested sequence, not an official Sylius procedure. Start by bringing the 1.14 shop to its latest patch release, which was 1.14.21 in October 2026, and by getting an automated test or at least a written checklist covering browsing, cart, checkout, payment, invoices and back office. Next, make a copy of the production database and work on a separate branch.
Then follow the guide's logic: update packages, routing and bundle configuration until the application boots, adapt the overridden code, and check it against the lists of removed classes and routes. The guide states that migrations were regenerated into a single file, so read that section closely before running anything on real data. Password hashing configuration and the user fields that were removed also deserve a careful check, because a mistake there locks customers out.
Only after that should you tackle the storefront, which is usually the most visible work. The Legacy Shop Bridge plugin can buy time by restoring the 1.x shop inside Sylius 2, which allows a page by page transition. Rehearse the production switch at least once on a copy, with a timed runbook and a rollback plan.
What to ask a provider
Ask which target version they recommend and why. Ask how they will test the payment flows of your actual gateways, how long the shop will be closed during the switch, and who is responsible if an abandoned plugin has to be rewritten. Ask for the code to remain in a repository you own from the first day. Vague answers to these questions matter more than the day rate.
When not to migrate now
If the shop is due to be replaced within months, or if the business no longer justifies custom development, a migration may be money spent in the wrong place. A hosted platform can be a better fit for a simple catalogue with no specific logic, and a larger agency may suit you better when several teams and strict procurement rules are involved. In the meantime, you still need a plan for the end of 1.14 support, which I cover in my article on Sylius 1.14 end of support. For the list of technical changes themselves, see the companion piece on Sylius 2.0 breaking changes.
The next simple step
You do not need to commit to a full migration to find out where you stand. Gather your composer.json, your plugin list and a description of what was customized, then ask for a written assessment. As an independent developer, I work directly on the code and you speak to me throughout: you can reach me from my Sylius developer page, and if the assessment shows that the migration is not worth it, that is what I will tell you.