Sylius official documentation: architecture and API
The Sylius official documentation describes a headless, open source framework built on Symfony, where you own the code and can replace its parts. For architecture, customization, plugins and API, it tells a buyer one main thing: Sylius suits projects with a development team, not a store owner looking for a turnkey tool. Read it to decide whether your custom needs justify that commitment. This guide reflects the documentation as I read it on 1 November 2026.
A disclosure first: I sell Sylius development, so I have an interest in this topic. That is why I link each claim, so you can check it, and why this article also says when to choose something else.
What the Sylius documentation says about architecture
The documentation home calls Sylius a framework rather than a SaaS platform and adds that nothing is hardcoded. In plain terms, a SaaS platform is software you rent and configure, while a framework is a base your developers extend. The architecture page explains the layers. Components are standalone PHP packages, such as taxation, that can be used alone. Bundles connect those components to Symfony, the PHP framework underneath. The Core ties them together, and the shop, admin and API then sit on top as separate contexts.
For a buyer, this layering has a practical consequence. A rule such as a specific tax treatment lives in identifiable code and can be changed without patching the whole product. The price is that someone must understand Symfony to do it safely. The official page on choosing Sylius is open about the audience: agencies, technical teams and experienced developers.
Symfony customization: what the guide recommends
The customization guide matters more than the marketing claims, because it shows which methods stay maintainable. For templates, the documentation recommends Twig hooks, a system of named insertion points configured in YAML, and discourages overriding whole template files, especially in plugins where several may try to change the same one. For forms, extensions are recommended over replacing an entire form. For menus, the Sylius 2 approach combines hooks and event listeners.
Use this as an audit tool. If a provider's Sylius store overrides dozens of templates, each upgrade will require comparing those copies with the new originals. Ask how customizations were made before you ask how many were made.
| Project need | Where to look | What to ask your provider |
|---|---|---|
| Change the shop's appearance | Customizing templates | Do you use Twig hooks, or do you copy templates? |
| Connect a custom frontend | Using the API | Which endpoints do you add, and how are they tested? |
| Add or restrict API behaviour | Customizing the API | Which default endpoints do you disable, and why? |
| Add a payment provider | Payment gateway plugin guide | Do you build on Payment Request or on an older method? |
| Sell through several storefronts | Channels | What differs per channel, and what is shared? |
Plugins and the API for a headless build
Plugins are listed on the Sylius Addons marketplace, which the documentation home describes as a place for official and community extensions. On a custom project, I would treat each plugin as a dependency to review: who maintains it, which Sylius versions it supports, and what you would do if it stopped being updated.
The API is built on API Platform, and the architecture page says operations are split between shop and admin contexts. Headless means the storefront is a separate application that talks to Sylius through that API. Shop endpoints sit under /api/v2/shop/, and the customization guide explains how to remove or rename them through YAML files. It also notes that, by default, orders can only be modified while they are still a cart, which matters if your sales team edits orders after checkout.
Headless is not automatically the better option. It suits a project needing a very specific customer experience, or several frontends. For a standard shop, the included storefront can be cheaper to build and maintain, because there is only one application to keep running.
Versions: the part of the documentation many buyers skip
A custom build only stays safe if it can follow updates. The release cycle page announces minor versions roughly every three to six months and major versions every two to three years. According to endoflife.date, security support for Sylius 1.14 ends on 31 December 2026 and for 2.2 on 31 March 2027. Sylius 2.3, released in September 2026, requires PHP 8.3 and accepts Symfony 6.4, 7.4 and 8. If you start now, a provider should have a clear reason for not starting on a currently supported version. An existing 1.14 store should already have a plan, using the official upgrade guide.
When Sylius is not the right choice
The official page does not list cases to avoid, so here is my reading. If your catalog is simple, your budget is tight and no one will maintain the code, a hosted platform or a CMS with an established module ecosystem will usually serve you better. Sylius can also be excessive if your main need is publishing content with occasional sales. The same applies if you cannot name who will apply security updates next year. I compare the PrestaShop side in a separate reading of its developer documentation.
The next simple step is to write down the three rules that off the shelf tools cannot handle for you. If you can name them, ask for an opinion on my Sylius developer page. If you cannot, you may not need a framework yet, and that is a useful answer too.