Basic Configuration

After installation, Sylius has a working store skeleton — but before you can sell anything, you need to configure five foundational concepts: Channels, Locales, Currencies, Countries, and Zones. These aren't just admin settings. They're the data model that everything else in Sylius is built on.

This page walks through each one and explains what it is, why it exists, and what to configure.

The installation command already created one Channel, one Locale (default:English US), and one Currency (default: USD) as defaults. You're configuring and expanding from there, not starting from scratch.

How these concepts relate

Before diving in, it helps to understand the hierarchy:

• A Channel is a storefront. It defines which locales, currencies, and countries are available in that store.
• Locales and Currencies exist independently and are assigned to Channels.
• Countries define where you ship. Zones group countries together for shipping and tax rules.

One Sylius installation can run multiple Channels — each with its own configuration. Common setups include separate Channels per country (different language, currency, and tax rules), per sales context (web store, mobile app, B2B portal), or per sales channel type (online vs. point of sale). That's the multi-channel architecture at the core of Sylius.

Channels

A Channel represents a single storefront. It holds the core identity of your store: its hostname, the locales and currencies it supports, its billing details, and its tax configuration.

Every product, order, and customer in Sylius belongs to a Channel. Common patterns:

• Per country — a separate Channel for each market, each with its own language, currency, tax zone, and pricing
• Per sales context — a web store and a B2B portal sharing the same product catalog but with different pricing rules and checkout flows
• Per sales channel type — an online store and a point-of-sale terminal running off the same backend

What to configure on your default Channel:

• Hostname — the domain your store runs on
• Base currency — the primary currency for pricing
• Available locales — the languages your store supports
• Countries — the shipping destinations for this storefront
• Billing data — your company details for invoices
• Tax zone — the default zone used for tax calculations

Locales

A Locale represents a language and regional format — en_US, de_DE, pl_PL. Sylius uses locales to translate product names, taxons, and all other content for your customers.

Your base locale was set during installation. Any product, taxon, or content you create must have at least a name in that base locale.

To add a locale:

1. Go to Configuration → Locales in the admin panel
2. Add the locales you want to support
3. Assign them to your Channel under Look & Feel → Locales

Currencies

Each Channel has one Base Currency — the currency used for storing prices internally. You can display prices in additional currencies, with conversion managed through Exchange Rates.

USD is the default set during installation. If your store operates in EUR or GBP, update the base currency on your Channel before creating any products.

To add a currency:

1. Go to Configuration → Currencies
2. Add the currencies you need
3. Configure Exchange Rates if you're displaying prices in multiple currencies
4. Assign currencies to your Channel

Countries

Countries define which shipping destinations are available in your store. Without at least one country configured, customers won't be able to complete checkout.

To add countries:

1. Go to Configuration → Countries
2. Add the countries you ship to
3. Countries become available as shipping destinations in your Channel

Once added, countries will be displayed in the index:

Zones

Zones group countries (or provinces, or other zones) together so you can apply the same shipping rules or tax rates to an entire region. A Zone named "European Union" containing all EU member states lets you create one shipping method or tax rate that applies to all of them at once.

Zones are referenced in two places: shipping methods (which zones a method is available in) and tax rates (which zones a rate applies to). You need at least one Zone before you can configure either.

To create a Zone:

1. Go to Configuration → Zones
2. Create a Zone and choose its type: countries, provinces, or other zones
3. Add the member countries to the Zone

After creating this zone, your basic shop configuration will be complete:

What's next

Once these five concepts are configured, your store has the foundation it needs. The next step is setting up how customers can pay and how orders are shipped.