Saleor Core: a GraphQL-only commerce backend you assemble yourself

What Saleor Core actually is, and who ends up running it

Saleor Core is the backend half of Saleor. The README describes it as a "GraphQL native, API-only platform for scalable composable commerce", and the package metadata in pyproject.toml names the stack directly: Python, GraphQL, Django and React, published as the saleor package under BSD-3-Clause. There is no server-rendered storefront inside this repository. The dashboard and the storefront are separate projects, and the README points at saleor-dashboard and react-storefront as their own repositories.

That split defines the audience. You are expected to bring a frontend, or to use one of the decoupled ones, and to talk to the backend over GraphQL. The README is explicit that APIs are the only way to interact with, configure or extend the backend. There is no admin plugin directory to install into, and no template layer to override. If your team's mental model is "install the platform, theme it, add plugins", this is a different shape of product.

The stated fit is a business that deploys on a daily basis, cares about uptime, works with several developers, or has non-trivial requirements. The README makes the counter-case itself: for a single developer running a small business without high traffic or a 24/7 availability requirement, the service-oriented approach "might feel more complex" than WordPress or Magento. That is an unusually direct statement of who the project is not for, and it is worth taking at face value.

Why the extension model is webhooks and apps instead of plugins

The architectural decision that shapes everything else is that custom logic lives outside the core process. The README lists the extension surfaces: webhooks, attributes, metadata, apps, subscription queries, synchronous API extensions and dashboard iframes. An app is a separate service that the core calls, rather than code loaded into the Django process.

The trade-off is stated in the README as a list of benefits: apps deploy independently so there is less downtime, custom logic is separated from the core for reliability and performance, and upgrade paths are simplified because extension incompatibility conflicts are eliminated. The same list argues that extensions can be scaled independently and that parallel development is easier than collaborating inside a monolithic core.

The cost is real and the README acknowledges it indirectly. Synchronous extensions sit in the request path, so a slow app becomes slow checkout. Subscription queries and webhooks introduce eventual consistency between the core and whatever state your app keeps. And because apps are separate services, you now operate them: their deployments, their secrets, their failure modes. The repository ships a socket.yml file and a .semgrep directory, which suggests the project treats supply-chain and static-analysis checks as part of its own process, but nothing in the README describes what your apps must do to stay compatible across upgrades.

Channels: the mechanism behind multichannel pricing and stock

Saleor's multichannel story is not a marketing layer over one catalog. The README describes native multichannel as per-channel control of pricing, currencies, stock, product and more, and links to a channels overview in the docs. In practice a channel is the unit you attach commercial rules to: a given product can be priced differently, sold in a different currency, and drawn from different stock depending on which channel the request targets.

This is the part that distinguishes Saleor from storefronts that bolt a second currency onto a single price field. It also raises the modelling work up front. Attributes and metadata are the extension points the README names for describing products beyond the built-in fields, so a catalog with unusual dimensions (regulated goods, region-specific variants, B2B tiers) is expressed through those, not through a plugin that rewrites the product table.

The rest of the feature list follows the same pattern of breadth: promotions with sales, vouchers, cart rules and gift cards; payment orchestration with multiple gateways and an extensible payment API; order management with split payments, multi-warehouse and returns; a CMS for product or marketing content; and full catalog translation. Each is exposed through the API rather than a bundled UI, which is why the dashboard is a separate repository.

Installing Saleor Core and making a first GraphQL call

The README does not inline installation steps. It points to the Saleor docs for step-by-step installation and deployment, specifically the docker-compose setup page, and to CONTRIBUTING.md for local development without Docker. So the honest first move is to read those two documents rather than improvise a setup.

What the repository does give you is the environment contract. The .env.example file lists the variables the application expects, and it is short enough to show in full:

CACHE_URL=redis://localhost:6379/0
CELERY_BROKER_URL=redis://localhost:6379/1
[email protected]
EMAIL_URL=smtp://localhost:1025
SECRET_KEY=changeme
HTTP_IP_FILTER_ALLOW_LOOPBACK_IPS=True
DASHBOARD_URL=http://localhost:9000/

Two of those are Redis URLs on different database numbers, one for the cache and one for the Celery broker, so a working Redis instance is a prerequisite before the API will behave. SECRET_KEY is a placeholder and must be replaced. HTTP_IP_FILTER_ALLOW_LOOPBACK_IPS is set to True, which is what lets a local dashboard talk to the API during development.

The project also publishes a container image. The Dockerfile builds on python:3.12-slim, installs the runtime libraries needed by Pillow, lxml and file-type detection, and exposes port 8000:

FROM python:3.12-slim
RUN groupadd -r saleor && useradd -r -g saleor saleor
EXPOSE 8000
ENV PYTHONUNBUFFERED=1

Once the stack is running, the only interface is GraphQL. The README links to docs.saleor.io for usage, and the API is reachable at the GraphQL endpoint the docs describe; the repository does not restate the schema here. Expect to authenticate before anything useful, since the README lists a login flow among the things the docs cover, and expect to configure channels before you can price a product, because pricing is channel-scoped.

The main branch is not the product you should deploy

The README carries a warning that is easy to skim past: the main branch is the development version and may be unstable, and the latest stable version should come from the Releases page or a release tag. The package metadata confirms the split, since pyproject.toml and package.json both declare version 3.24.0-a.0, an alpha. If you clone the default branch and deploy it, you are running alpha code.

The README goes further and says the current production-ready version is 3.x, and that all three components should be on that version: Saleor itself, the dashboard, and the storefront. That is a version-lock constraint across three repositories, and it is the most common place a self-hosted install goes wrong. A dashboard built against one 3.x release talking to a core on another is not a configuration the README endorses.

The release cadence visible in the repository is high, with 3.22.70 and 3.23.35 published days apart in September 2026, and the last push to main on 2026-09-18. That cadence is good for fixes and bad for anyone who pins nothing. Treat the version string as a deployment input, not an afterthought.

Saleor Core versus Medusa, and when a hosted platform wins

The comparison people reach for is Medusa, and the difference is not cosmetic. Saleor Core is Python and Django with a GraphQL-only API; Medusa is a Node.js commerce framework whose API surface includes REST alongside GraphQL. If your team writes Python, reads Django ORM code, and wants one query language across every operation, Saleor's constraint is a feature. If your team is JavaScript-first and wants REST endpoints that any HTTP client can call without a GraphQL client library, that same constraint is friction on day one.

The second real alternative is a hosted platform, and the README answers that comparison itself by pointing at Saleor Cloud as the fastest way to develop with Saleor. The trade is control for operational load: Cloud removes the Redis, Celery, database and upgrade work that self-hosting the core requires, at the cost of running on someone else's infrastructure. The README's own framing of the self-hosted trade-off, that a service-oriented approach is more complex for a small operator, applies here too.

Where Saleor Core is plainly the wrong tool: a content-heavy brochure site with a handful of SKUs and no engineering capacity, or any project where the requirement is a themeable storefront shipped this week. Nothing in this repository produces a storefront, and the extension model assumes you can run services.

Licence, maintenance and what an upgrade actually costs

Saleor Core is BSD-3-Clause, declared in both pyproject.toml and package.json. That is a permissive licence, and the README contrasts it with commercial editions by stating there is a single version of Saleor without feature fragmentation or commercial limitations. Nothing in the README suggests a separate enterprise build of the core. This is a description of the repository's licensing, not legal advice; read the LICENSE file for the terms that bind you.

The runtime floor is Python >=3.12,<3.13 per pyproject.toml, with a Dockerfile pinned to python:3.12. The Node engines field requires Node >=20 <22, but that applies to the release tooling in package.json rather than the API itself. Dependencies are pinned with ranges in pyproject.toml and locked in uv.lock, and the Dockerfile installs with uv sync --locked, so a container build reproduces the lock file rather than resolving fresh versions. That is the mechanism that makes upgrades deliberate.

The upgrade cost lands on your apps. The README claims simplified upgrade paths as a benefit of the app model, and that holds for the core process, which you replace wholesale. It does not hold for the contracts your apps depend on: webhook payloads, subscription queries and synchronous extension events are all versioned surfaces, and the README does not describe a compatibility guarantee across 3.x releases. Before upgrading, check the release notes for the target version and re-read the webhook and synchronous events documentation for any payload change that touches your apps.

Editorial conclusion

Adopt Saleor Core if you have engineers who are comfortable with GraphQL, Django and container deployment, and you need per-channel pricing, stock and currency rather than a hosted storefront. Do not adopt it if a single developer is expected to run a small shop end to end, since the README itself says a service-oriented approach can feel more complex than WordPress or Magento in that situation. Before committing, verify three things in the repository: that your target is a 3.x release tag rather than the unstable main branch, that your Python version satisfies the requires-python range in pyproject.toml, and that your deployment provides Redis for CACHE_URL and CELERY_BROKER_URL, because the example environment file assumes both.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. README
4. Releases
5. saleor/saleor on GitHub