Headless Storefront API v1

Token-authenticated REST API for headless commerce. Build mobile apps, SPAs, and custom storefronts without managing session cookies.

Authentication

The Headless Storefront API uses two token types:

Storefront Access Token (SAT) — Issued per sales channel. Required on every request. Pass as X-Shopify-Storefront-Access-Token: sat_... or Authorization: Bearer sat_....
Customer Access Token (CAT) — JWT issued at customer login. Required for customer-protected routes (/customer/*). Pass as Authorization: Bearer cat_....

Create a Sales Channel

Issue POST /admin/sales-channels (Admin JWT required) to create a channel and receive your SAT. The token is shown only once — store it securely.

POST/admin/sales-channelsadmin-jwt

Create a sales channel and receive a one-time Storefront Access Token (SAT).

Request Body

json

{
  "allowed_origins": [
    "https://app.example.com"
  ],
  "locale": "en",
  "name": "Mobile App"
}

Key Endpoints

All routes under /storefront/v1/ require SAT header

Name	Type	Required	Description
GET /storefront/v1/shop	endpoint	No	Shop config, theme, and navigation menus
GET /storefront/v1/products	endpoint	No	List published products with variants (limit, offset, collection, q params)
GET /storefront/v1/products/:handle	endpoint	No	Get product by slug
GET /storefront/v1/collections	endpoint	No	List collections
GET /storefront/v1/search?q=	endpoint	No	Full-text product search
POST /storefront/v1/cart	endpoint	No	Create empty cart — returns cart ID
GET /storefront/v1/cart/:cartId	endpoint	No	Get cart with line items, subtotal, discount
POST /storefront/v1/cart/:cartId/items	endpoint	No	Add variant to cart
POST /storefront/v1/customer/token	endpoint	No	Customer login — returns CAT (JWT)
GET /storefront/v1/customer	endpoint	No	Get current customer (CAT required)
GET /storefront/v1/customer/orders	endpoint	No	List customer orders (CAT required)
GET /storefront/v1/seo/hreflang	endpoint	No	Hreflang alternate links for all markets

TypeScript Examples

typescript

const SAT = "sat_your_token";
const BASE = "https://cartly.pro/storefront/v1";

// List products
const { products } = await fetch(BASE + "/products?limit=10", {
  headers: { "X-Shopify-Storefront-Access-Token": SAT },
}).then(r => r.json());