GraphQL API
What the StoreOS GraphQL API is and when to use it over REST.
What is the GraphQL API?
GraphQL is another way to call the same StoreOS backend. Instead of many REST URLs, you send one POST with a query describing exactly the fields you need.
POST https://storefront-api.storeos.dev/graphql| REST | GraphQL | |
|---|---|---|
| Style | One URL per action (/products, /orders) | One endpoint, query in body |
| Package | @storeos/storefront-client REST, or React SDK (gqlClient) | Your own client (Apollo, urql, fetch) |
| Best for | Most storefront apps | Custom field selection, existing GraphQL stack |
| Docs | REST · Swagger | This section |
Both expose the same catalog, auth, and orders. Data is identical — only the calling style differs.
Headers
| Header | What it does |
|---|---|
Content-Type: application/json | Query/mutation in body |
x-tenant | Your store's tenant UID — every request |
Authorization: Bearer <jwt> | Logged-in customer — when required |
What you can do (same four areas as REST)
Catalog — read products & collections
Queries: products, productById, productByHandle, collections, collection
Use for shop pages and product detail. No login required.
Store config — read tenant settings
Query: storeFront
Delivery charges, support info, legal policies. Use at checkout and in footer.
Auth — customer sign-in
Mutations: register, login, sendOtp, verifyOtpToLogin, logout
Query: me
Returns JWT accessToken — store it in your app like REST auth.
Orders — checkout & history
Mutations: createOrder, verifyCoupon, cancelOrder
Queries: myOrders, orderDetailsById
Place orders (guest or logged-in), track by invoice UID.
Prefer less boilerplate?
Prefer the typed clients when you can:
- REST —
@storeos/storefront-client(StoreFront) - GraphQL + React —
@storeos/storefront-client/react(gqlClient, providers)
Pages
- Authentication — login, register, OTP
- Queries — catalog, config, orders (read)
- Mutations — checkout, account changes (write)