How it works

The architecture behind StoreKit — one universal API and per-framework SDK adapters.

StoreKit has two layers. Understanding how they fit together makes everything else in these docs click.

The universal API

The Storefront API is a stateless HTTP API. Every storefront capability is an endpoint under /v1:

GET /v1/products, GET /v1/categories, GET /v1/search — the catalog
POST /v1/cart, POST /v1/checkout — buying
POST /v1/auth/otp/verify, GET /v1/customer — accounts
GET /v1/store, GET /v1/menu — store config

It's framework-agnostic and language-agnostic: anything that can make an HTTP request can use it. Each request identifies the store with a publishable store key header, and optionally a customer with a bearer token. See Authentication.

The SDK

The SDK wraps that API so you don't hand-build requests, headers, and types. It comes in three layers:

Core client

createStorefrontClient() — framework-agnostic, works in any JS runtime. Every resource method maps to one endpoint.

Next.js adapter

initStorekit() — server-side resources with caching, cookie-backed cart and auth, and a proxy handler.

Browser hooks

createStorekitClient() — a same-origin client plus React hooks like useCart().

The two surfaces of a real app

In a typical Next.js storefront you use two SDK surfaces at once:

Server code (initStorekit()) holds the secret store key and reads data for Server Components.
Browser code (createStorekitClient()) never sees the key. It calls your same-origin proxy (storekit.handler()), which adds the key and session server-side.

This split is what keeps your store key secret while still letting client components add to cart and log in.

Request lifecycle (browser mutation)

When a shopper clicks "Add to cart":

The useCart().add() hook POSTs to /api/storefront/cart/items on your own origin.

storekit.handler() reads the cart-id cookie, attaches the store key and session token, and forwards to POST /v1/cart (or updates the existing cart).

The API responds with the updated cart; the handler refreshes the cart cookie.

The hook updates a shared store so every component using useCart() re-renders with the new count.

Where to go next

Authentication — store keys, OTP login, sessions.
Carts & checkout — guest vs customer carts and the order flow.
Payments — the redirect-and-reconcile flow.