Sylius official documentation: architecture and API map
The Sylius official documentation lives at docs.sylius.com. It splits into public getting started guides and The Book, the full reference for features and architecture, which requires a login. It describes a Symfony application with an API built on API Platform, usable headless, and a channel model for multi channel selling. Reading it well means knowing what it covers for free, what it covers only for Plus, and which older pages to ignore.
How the official documentation is organised in 2026
The documentation home arranges content by project stage. Under evaluating, you find a guide called Choosing Sylius, the live demo and open source information such as the release cycle. Under installing, you find prerequisites and installation with or without Docker. Under building, you find basic configuration and The Book. The home page also lists experimental AI tools, including a Shop MCP Server and a Documentation MCP Server, which are marked as such.
If you are a buyer rather than a developer, read Choosing Sylius and the release cycle first, then hand the rest to whoever will write the code. One practical point: the reference requires a login through Sylius Connect, so a quick look without an account will make the documentation seem thinner than it is. I also found that old version pages still rank in searches. They are useful as history, but they can mislead you about the current product.
| You want to know | Where to look | Access |
|---|---|---|
| Is Sylius right for us? | Choosing Sylius, release cycle | Public |
| What does a channel hold? | Basic Configuration | Public |
| How is it built? | The Book, Architecture | Login |
| What changes in this version? | Release posts and upgrade files | Public |
| What does a paid module do? | Addons marketplace listing | Public |
Architecture: what the documentation tells you
According to its architecture chapter, Sylius is a full stack Symfony application that can also be used as decoupled components and bundles. For a buyer, this means your developer does not have to fight a closed system. Business behaviour lives in ordinary Symfony code that another Symfony developer can read, which reduces your dependence on one supplier.
The chapter on the state machine is worth a mention. A state machine is the set of rules saying which steps an order or a checkout may move through, such as from cart to addressed to completed. Symfony Workflow is the default, with Winzou State Machine still an option. This is where custom checkout rules usually land, so it is a good topic to raise when you interview a developer.
Customisation follows the same logic. Plugins are Symfony bundles that extend the platform without editing its core. The customisation guide recommends Twig Hooks rather than overriding whole templates, since overrides conflict when several plugins touch the same page. If an audit of your shop finds many full template overrides, expect upgrades to take longer.
API and headless: what is really available
The API is built on API Platform, which the documentation presents as part of an API first, headless design. The architecture chapter says operations are grouped under shop and admin prefixes and that the whole API can be switched off with one parameter. Version 2.3 supports API Platform 5 and shows the kind of detail that matters in production: a new endpoint at /api/v2/shop/customers/verification-request always answers 202 Accepted, so nobody can test which e-mail addresses have accounts. Upgrade notes for the API get their own file.
Headless does not automatically mean better. It means building and maintaining a second application, the storefront, in addition to the back end. It is worth the cost when a mobile app, several front ends or a very specific experience share one engine. For a single website, the built in storefront is often the sensible choice, and that decision alone can change the budget considerably.
Multi channel in the docs, and the limit to note
The Basic Configuration page says a channel represents a single storefront, with its own hostname, locales, currencies, billing details and tax setup, and that every product, order and customer belongs to a channel. Each channel has one base currency. Zones group countries so that one shipping rule or tax rate can cover a region, and at least one is needed before configuring either.
The limit concerns organisation rather than storefronts. Sylius's own article on international selling places management across business units and legal entities in the Plus multi-store module. Customer accounts can also be split into pools, by domain or country for example. Ask early whether a customer in Belgium and one in France should share an account, because changing that later touches real data.
When the documentation will not be enough
Documentation describes the product, not your project. It will not tell you whether a Plus module fits your rules, and a marketplace listing can trail behind a release: the B2B Suite listing showed a version field running from 1.11 to 2.2 when I read it, while Sylius 2.3 was already out. If a simple catalogue and standard checkout describe you, you may not need this level of depth, and a hosted platform could serve you better.
What to do next
I work on Sylius projects, so I have an interest in you choosing this platform, but the sources above let you judge for yourself. If you want to know what your project would demand, write down your channels, currencies and integrations, then send them through the Sylius developer page. I reply within 24 working hours, and you speak directly with the person who would write the code.