REST API

What is the REST API?

The REST API is the HTTP interface your storefront app uses to read catalog data, manage customer auth, and place orders. StoreOS hosts it — you call it over HTTPS from your app.

https://storefront-api.storeos.dev/api/v1/...

REST means each action is a URL + HTTP method (GET, POST, …). If you use @storeos/storefront-client, it calls these routes for you. If not, you call them with fetch, curl, or any HTTP client.

Same data as GraphQL — pick whichever style fits your stack.

Interactive reference (Swagger)

storefront-api.storeos.dev/docs — try requests, see request/response schemas, test auth.

Headers on every request

Header	What it does	When
`x-tenant`	Tells StoreOS which store — your tenant UID	Every route
`Authorization: Bearer <jwt>`	Identifies the logged-in customer	Order history, profile, cancel
`Content-Type: application/json`	JSON request body	`POST`, `PATCH`

API areas

The REST API is organized into five areas. Each maps to part of your storefront.

Catalog — products & collections

What it is: Everything customers browse before buying.

Route	What it does	Your page
`GET /api/v1/products`	List published products (search, filter, paginate)	Shop, search
`GET /api/v1/products/handle/:handle`	One product by URL slug	`/product/[handle]`
`GET /api/v1/products/:id`	One product by internal ID	Cart, admin picks
`GET /api/v1/collections`	List product groups (e.g. "Sale")	Nav, homepage
`GET /api/v1/collections/:id`	One collection	Collection page

Auth: Not required — public catalog.

SDK: getProducts, getProduct, getCollections, getCollection

List params: page, limit, sort, sortBy, search, collectionIds[]

Store config — tenant

What it is: Store-wide settings you manage in the StoreOS console — not products, but rules that affect checkout and your site footer.

Route	What it returns	Your page
`GET /api/v1/tenant`	Name, delivery charges, support contact, legal policies, social links	Checkout, footer, policy pages

Auth: Not required.

SDK: getTenant · GraphQL: storeFront query

Auth — customer accounts

What it is: Sign-up, login, and profile for shoppers on your storefront.

Route	What it does	Auth
`POST /api/v1/auth/register`	Create account	Tenant only
`POST /api/v1/auth/login`	Email/phone + password	Tenant only
`POST /api/v1/auth/otp/send`	Send 4-digit SMS code	Tenant only
`POST /api/v1/auth/otp/verify`	Verify code, sign in	Tenant only
`GET /api/v1/auth/me`	Current customer profile	Bearer required
`PATCH /api/v1/auth/profile`	Update name, phone, address	Bearer required
`POST /api/v1/auth/change-password`	Change password	Bearer required
`POST /api/v1/auth/logout`	End session (client drops token)	Tenant only

SDK: register, login, sendOtp, verifyOtp, getMe, …

→ GraphQL auth · Phone OTP guide

Orders — checkout & history

What it is: Turning a cart into a placed order and letting customers track or cancel it.

Route	What it does	Auth
`POST /api/v1/orders/coupons/verify`	Check if discount code applies to cart	Optional
`POST /api/v1/orders`	Place order (guest or logged-in)	Optional
`GET /api/v1/orders`	Customer's order history	Bearer required
`GET /api/v1/orders/:orderId`	One order by invoice UID	Tenant only (public tracking)
`POST /api/v1/orders/:orderId/cancel`	Cancel an order	Bearer required

SDK: verifyCoupon, createOrder, getMyOrders, getOrder, cancelOrder

→ Checkout guide

Pagination

List routes return:

{
  "nodes": [ /* items */ ],
  "meta": {
    "totalCount": 42,
    "currentPage": 1,
    "hasNextPage": true,
    "totalPages": 5
  }
}

Param	Purpose
`page`, `limit`	Page number and page size
`limit: -1`	Return all items in one response (no paging)

Easier integration

Approach	Docs
TypeScript SDK (recommended)	storefront-client
GraphQL (same backend)	GraphQL API

REST API

On this page