Overview
What you can build on the platform, which approach suits which problem, and where to start.
There are four ways to extend a shop. Which you want depends on what you are trying to change.
| You want to | Build |
|---|---|
| Read or write shop data from elsewhere | The REST API |
| Add a feature inside the admin | An app |
| Change how the shop looks | A theme |
| React when something happens | A webhook |
Most integrations are an API token and a webhook. Reach for an app only when something has to live inside the admin.
The REST API
Every shop exposes an API at /api/v1 on its own domain, authenticated with a token the merchant issues.
It covers products, categories, the cart, orders, customers and inventory. Read Authentication first, then the endpoint you need.
Carts work through a token you hold rather than a session, since there is none here, and a cart can be handed to the shop's own checkout so the shopper pays without your code touching a card. See Cart.
Card readers have their own endpoints under /api/v1/terminal. They need the shop to have connected Stripe, and answer 503 with a stripe_not_configured code when it has not, which is worth handling: a till that cannot tell "no readers" from "no Stripe" will send somebody looking for a hardware fault that does not exist.
The full reference, generated from the code so it cannot drift from the real behaviour, lives at /docs/api on each shop.
Apps
An app is installed into a shop by its owner and can add screens to the admin, extend the checkout and subscribe to events. It is granted specific permissions at install time and cannot exceed them.
Build an app when a merchant needs to do something while they are already in the admin. Build an integration when the work happens somewhere else.
Themes
A theme is a directory of Twig templates with a manifest describing the settings a merchant can change. Themes can be built locally and uploaded, and are reviewed before they can be used.
Webhooks
A webhook tells your system that something happened, rather than you asking repeatedly whether it has.
The practical pattern for anything that matters is both: a webhook for speed, and a periodic read of the API to catch what went missing. No delivery mechanism is reliable forever.
Where to Start
| If you are | Read |
|---|---|
| Connecting another system | Your First Request |
| Writing anything that parses responses | Errors and Conventions |
| Building a storefront design | Building a Theme |
| Building something inside the admin | Building an App, Step by Step |
The Generated Reference
Each shop publishes a complete API reference at /docs/api on its own domain, generated from the code so it describes the real behaviour rather than an intention.
These pages are for how things fit together and what goes wrong. That reference is for exact fields and types. Use both.
One Thing to Understand First
Every shop is a separate tenant with its own database. There is no cross-shop API: a token is issued by one merchant, for one shop, and reaches nothing else.
If you are building something several merchants will install, you are holding one token per shop and calling each shop's own domain.