Shoppex works as a commerce engine behind your own frontend. You own the UI, routing, and brand experience. Shoppex owns the catalog, payments, invoices, subscriptions, license delivery, and fulfillment.Documentation Index
Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
Use this file to discover all available pages before exploring further.
You do not need to use a Shoppex theme or a Shoppex storefront domain as the customer-facing surface. Everything here is reachable from a plain Next.js, Nuxt, SvelteKit, Astro, Remix, React Native, or native mobile app.
When to Go Headless
You already have a brand site
You run a marketing site, landing pages, or an app and want checkout + invoices + licenses without redesigning around a theme.
You want custom UX
Your storefront is part of a larger product — a Discord bot UI, a SaaS paywall, a mobile app, an internal reseller tool — and a hosted shop does not fit.
You want API-first automation
You generate catalog entries, licenses, or orders programmatically and want the frontend to stay thin.
You ship to native clients
You need commerce inside iOS, Android, or Electron apps where a hosted web checkout is not ideal.
What You Keep, What Shoppex Runs
| You keep | Shoppex runs |
|---|---|
| UI, routing, layout, auth surface | Catalog, pricing, invoices, orders |
| Brand domain + SEO | Payment session creation across PSPs |
| Customer session / login form | PSP orchestration + 3DS + crypto |
| Product pages and cart UI | License keys, serial pools, dynamic delivery |
| Email + notification style | Subscriptions, trials, renewals, dunning |
| Anything you want to own | Webhooks, fraud shield, blacklist, disputes |
Pick Your Integration Shape
Dev API
Server-to-server. Bearer API keys or OAuth2. Full control over catalog, orders, customers, licenses, subscriptions, webhooks.
Storefront SDK
Browser-side reads (products, pages, reviews, navigation) plus hosted-checkout redirect. Good fit for SPAs and SSR storefronts.
Checkout Embed SDK
Drop-in modal checkout on any existing site with one script tag. No backend wiring required for the checkout UI.
Headless Checkout SDK
Build your own checkout UI with a publishable key and allowed origins while Shoppex handles payment sessions.
Decision Tree
Do you need to read catalog or orders from a backend?
Use the Dev API with
@shoppexio/sdk (Node, Python, PHP) or plain HTTP.Do you need product, cart, or page data in the browser?
Use the Storefront SDK (
@shoppexio/storefront) for public read endpoints and hosted-checkout redirect.Do you only need a buy button on an existing page?
Use the Checkout Embed SDK — drop one script tag, add
data-shoppex-* attributes, done.Do you need to build the checkout UI itself?
Use the Headless Checkout SDK (
@shoppexio/checkout-js/headless) with a dashboard-generated publishable key and allowed origins.Not sure which to pick? Start with the Next.js Quickstart. It uses the Dev API from the server, redirects into hosted checkout, and verifies signed webhooks.
Next.js Quickstart
Build a custom storefront in Next.js 16 in under 15 minutes.
Storefront Starter
Start from a self-hosted Next.js storefront with cart, checkout, customer portal links, and webhook fulfillment already wired.
Reference Architecture
A typical headless flow looks like this:- Your frontend reads public catalog data with the Storefront SDK or through your own backend.
- Your backend calls the Dev API with a server-held
shx_*key to create the payment. - The buyer is redirected to Shoppex hosted checkout, or you open the Embed SDK modal.
- Shoppex sends signed webhook events back to your webhook receiver after payment or subscription state changes.
- Your backend fulfills the order, grants access, or updates your own app state.
- Reads → Storefront SDK or Dev API, depending on where the read happens.
- Checkout → hosted checkout session (redirect) or Embed SDK (modal). Shoppex owns the PSP and 3DS dance.
- Events → signed webhooks back to your server for order, subscription, dispute, and related lifecycle events.
Authentication Shape
| Surface | Token type | Where it lives |
|---|---|---|
| Dev API (server-to-server) | API key shx_* or OAuth2 access token | Your server env / secret manager |
| Storefront SDK (browser) | None for public reads; shop slug identifies the shop | Browser bundle |
| Checkout Embed SDK | None; shop id + product id in markup | Browser bundle |
| Customer portal OTP | Email + one-time code verified server-side by Shoppex | Your login UI calls the public OTP endpoints |
Package names are intentionally separate: use
@shoppexio/storefront in customer-facing browser/headless code, and use @shoppexio/sdk only in trusted backend code that talks to the Developer API.Authentication
API keys, OAuth2 authorization code flow, scopes, and key rotation.
Webhook Model
Your backend receives signed events after state changes:order:created,order:paid,order:cancelled,order:disputedproduct:created,product:edited,product:stock,product:dynamicsubscription:created,subscription:renewed,subscription:cancelled,subscription:trial:started,subscription:trial:ended,subscription:upcomingquery:created,query:replied,feedback:received,affiliate:payout_requested
:product variants (for example order:paid:product) when you need full product payloads in the webhook. New handlers should verify the timestamped X-Shoppex-Signature-V2 header.
Webhooks
Event catalog, signing, retries, and the dynamic delivery contract for
DYNAMIC products.Next Steps
Next.js Quickstart
End-to-end build: list products, create a checkout session, verify webhooks.
Storefront Starter
Use the official starter when you want a complete custom storefront foundation.
Headless Checkout SDK
Build the payment step on your own domain with a publishable key and origin allowlist.
Architecture Reference
Three reference setups: pure SPA, Next.js SSR, mobile with backend-for-frontend.
Use Cases
Discord bots, SaaS paywalls, mobile apps, gaming resellers.
Dev API Reference
Every endpoint, request shape, and response schema under
/dev/v1/*.