Storefront API
Build your own e-commerce frontend on top of your Periscale store. The Storefront API exposes everything a live shop needs — store configuration, product catalog, cart, checkout, orders, shopper accounts, and content — as plain HTTP endpoints, so you can build the storefront in any framework you like.
Environments
| Environment | Base URL | Use it for |
|---|---|---|
| Production | https://storefront.periscale.app | Your live store and real orders. |
| Sandbox | https://dev-storefront.periscale.app | Integration work and testing. Separate data — nothing here touches production. |
Both environments expose an identical surface, so promoting an integration is a base-URL change and nothing else.
Keys are per-environment
Each environment issues its own API key. A sandbox key will not authenticate against production, and vice versa — you get a 401 rather than silently reading the wrong store.
Endpoints are mounted under /api/v1/business/website/, and shopper account endpoints under /api/v1/customer/auth/.
curl https://dev-storefront.periscale.app/api/v1/business/website/products/?limit=2 \
-H "X-Periscale-Key: sb_live_..."Authentication at a glance
| Request type | Send |
|---|---|
| Public reads (config, catalog, content) | X-Periscale-Key: sb_live_... |
| Shopper actions (cart, checkout, orders, account) | X-Periscale-Key + Authorization: Bearer <shopper_token> |
| Shopper login / register | X-Periscale-Key |
The sb_live_* key is your business API key — the same key the chat widget and analytics tag use. It identifies which store the request is for, so there is no subdomain or tenant parameter to pass. Keep it in your server environment and proxy requests through your backend. See Authentication for details.
What the API exposes
- Store config — identity, theme, hero, navigation, footer, pages, payment methods, announcement bar: everything needed to render the shell of the shop
- Catalog — products, categories, top products, new arrivals, flash deals, bundles, reviews
- Shopper accounts — register, login, JWT refresh, OTP verification, profile, password reset
- Cart & checkout — cart management, coupon validation, order creation, COD risk check, payment gateway initiate/verify
- Orders — order history, cancellations, refund requests
- Content — custom pages and blog posts
Response shape
Every response is wrapped in the same envelope:
{ "status": true, "status_code": 200, "message": "", "data": { } }Collections always look the same inside data:
{ "items": [], "next_cursor": "eyJ2IjoxLCJz…", "has_more": true }See Pagination & fields for walking pages and trimming payloads.
Next steps
- Authentication — keys, shopper tokens, refresh
- Pagination & fields — cursors and sparse responses
- Build a storefront — an end-to-end walkthrough
- API reference — every endpoint