Overview

SaveLayer is designed around one shared service layer with multiple ingress channels.

Online Store themes

Online Store traffic uses Shopify app proxy requests. The recommended storefront integration is the SaveLayer theme app embed, which loads the SDK and exposes window.SaveLayer. Full endpoint and schema reference lives on the SaveLayer marketing documentation site under Documentation → API reference (/docs/api-reference).

Headless storefronts

Headless storefronts use direct APIs under /api/headless/*: a backend-only exchange (POST /api/headless/auth/exchange) with a Customer Account API access token, then short-lived SaveLayer JWTs (Authorization: Bearer …, 300s TTL) on operation routes. They do not go through the Shopify app proxy path.

Customer account extensions

Customer account extensions use direct APIs under /api/customer-account/*: a session-token exchange (POST /api/customer-account/auth/exchange), then the same SaveLayer JWT model on operations. Exchange responses use Shopify’s CORS helper; other routes use the same customer-account authenticate path for OPTIONS preflight.

Full diagrams, secret setup, and security boundaries: SaveLayer marketing documentation Documentation → Authorization (/docs/authorization).

Current repository shape

• apps/pages: Shopify React Router app, app proxy routes, direct API routes, admin UI
• apps/worker: Cloudflare Worker for shared background and gatekeeping logic
• packages/contracts: shared Zod schemas
• packages/sdk: browser-safe SaveLayer SDK
• extensions/savelayer-theme: Shopify theme app extension