Skip to main content
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.
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 keepShoppex runs
UI, routing, layout, auth surfaceCatalog, pricing, invoices, orders
Brand domain + SEOPayment session creation across PSPs
Customer session / login formPSP orchestration + 3DS + crypto
Product pages and cart UILicense keys, serial pools, dynamic delivery
Email + notification styleSubscriptions, trials, renewals, dunning
Anything you want to ownWebhooks, 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.

​
Decision Tree

1

Do you need to read catalog or orders from a backend?

Use the Dev API with @shoppexio/sdk (Node, Python, PHP) or plain HTTP.
2

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.
3

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.
4

Do you mix all three?

That is the normal case. Dev API for server workflows, Storefront SDK for browser reads, Embed SDK for buy buttons.
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.

​
Reference Architecture

A typical headless flow looks like this:
  1. Your frontend reads public catalog data with the Storefront SDK or through your own backend.
  2. Your backend calls the Dev API with a server-held shx_* key to create the payment.
  3. The buyer is redirected to Shoppex hosted checkout, or you open the Embed SDK modal.
  4. Shoppex sends signed webhook events back to your webhook receiver after payment or subscription state changes.
  5. Your backend fulfills the order, grants access, or updates your own app state.
Three pipes, three responsibilities:
  • 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

SurfaceToken typeWhere it lives
Dev API (server-to-server)API key shx_* or OAuth2 access tokenYour server env / secret manager
Storefront SDK (browser)None for public reads; shop slug identifies the shopBrowser bundle
Checkout Embed SDKNone; shop id + product id in markupBrowser bundle
Customer portal OTPEmail + one-time code verified server-side by ShoppexYour login UI calls the public OTP endpoints
Never ship shx_* API keys to the browser. They authenticate as your shop and can read or mutate anything in scope. Keep them on the server.

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:disputed
  • product:created, product:edited, product:stock, product:dynamic
  • subscription:created, subscription:renewed, subscription:cancelled, subscription:trial:started, subscription:trial:ended, subscription:upcoming
  • query:created, query:replied, feedback:received, affiliate:payout_requested
Order and subscription events also have :product variants (for example order:paid:product) when you need full product payloads in the webhook. Payloads are signed with HMAC-SHA512 via the X-Shoppex-Signature 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.

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/*.