Introduction

Understand StoreOS, the API, and the storefront package — then build your shop.

The big picture

StoreOS runs the API (catalog, orders, auth). The SDK connects it to your storefront app — and your customers shop your store.

Piece	What it is	Who provides it
Storefront API	Hosted backend — your products, orders, store settings	StoreOS
`@storeos/storefront-client`	SDK wired to that API — fetch catalog, checkout, auth with typed methods	StoreOS (you install in your app)
Your storefront app	Pages, design, cart UI, deploy	You

You don't run the backend or wire HTTP yourself. Install the SDK, pass your tenant UID, call getProducts() — your catalog appears in your app.

What the API does

The StoreOS Storefront API is how your app reads and writes commerce data. It is grouped into four areas:

Area	What it does	Example in your app
Catalog	Products and collections customers browse	Shop page, product detail
Store config	Delivery charges, support info, policies	Checkout totals, footer
Auth	Customer sign-up, login, phone OTP	`/auth`, account page
Orders	Place orders, track status, cancel	Checkout, order history

Two ways to call the same backend:

Surface	Best for
REST + `@storeos/storefront-client`	Most storefront apps — recommended
GraphQL	Custom queries, existing GraphQL tooling

Interactive reference: storefront-api.storeos.dev/docs

Service health: status page

What the SDK does

@storeos/storefront-client is the bridge between your app and StoreOS. It is built to work with the Storefront API out of the box:

getProducts() → your published products in the shop
getProduct({ handle }) → product detail pages
createOrder() → checkout completes on StoreOS
login() / verifyOtp() → customers sign in to your store

The SDK handles API URLs, your tenant UID, and auth headers. You focus on UI. Pages and design are yours; the optional React SDK also includes cart + auth providers. See package vs your app.

Launch your storefront

bun create next-app my-store && cd my-store
bun add @storeos/storefront-client

Set NEXT_PUBLIC_SITE_API_TENANT, create a StoreFront client, fetch products, build pages, deploy.

→ Getting started — full walkthrough

Documentation map

Section	What you'll learn
Getting started	Create app, install package, configure, first request
TypeScript SDK	What `@storeos/storefront-client` is and how to configure it
SDK methods	REST methods — catalog, auth, checkout, orders
React SDK	Providers, hooks, GraphQL helpers for React / Next.js
REST API	HTTP routes, headers, and Swagger
GraphQL API	Queries and mutations (alternative to REST)
Guides	Checkout and phone OTP end-to-end
Roadmap	What's available today