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

# Headless Commerce with Shoppex

> Run Shoppex as the commerce engine behind any frontend — your UI, our orders, payments, invoices, licenses, subscriptions, and fulfillment.

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.

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

## When to Go Headless

<CardGroup cols={2}>
  <Card title="You already have a brand site" icon="palette">
    You run a marketing site, landing pages, or an app and want checkout + invoices + licenses without redesigning around a theme.
  </Card>

  <Card title="You want custom UX" icon="wand-magic-sparkles">
    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.
  </Card>

  <Card title="You want API-first automation" icon="code">
    You generate catalog entries, licenses, or orders programmatically and want the frontend to stay thin.
  </Card>

  <Card title="You ship to native clients" icon="mobile">
    You need commerce inside iOS, Android, or Electron apps where a hosted web checkout is not ideal.
  </Card>
</CardGroup>

## 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

<CardGroup cols={3}>
  <Card title="Dev API" icon="server" href="/api-reference/introduction">
    Server-to-server. Bearer API keys or OAuth2. Full control over catalog, orders, customers, licenses, subscriptions, webhooks.
  </Card>

  <Card title="Storefront SDK" icon="browser" href="/sdk/introduction">
    Browser-side reads (products, pages, reviews, navigation) plus hosted-checkout redirect. Good fit for SPAs and SSR storefronts.
  </Card>

  <Card title="Checkout Embed SDK" icon="window-maximize" href="/guides/embeds">
    Drop-in modal checkout on any existing site with one script tag. No backend wiring required for the checkout UI.
  </Card>

  <Card title="Headless Checkout SDK" icon="credit-card" href="/headless/checkout">
    Build your own checkout UI with a publishable key and allowed origins while Shoppex handles payment sessions.
  </Card>
</CardGroup>

### Decision Tree

<Steps>
  <Step title="Do you need to read catalog or orders from a backend?">
    Use the **Dev API** with `@shoppexio/sdk` (Node, Python, PHP) or plain HTTP.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

<Card title="Next.js Quickstart" icon="bolt" href="/headless/quickstart-nextjs">
  Build a custom storefront in Next.js 16 in under 15 minutes.
</Card>

<Card title="Storefront Starter" icon="store" href="/headless/storefront-starter">
  Start from a self-hosted Next.js storefront with cart, checkout, customer portal links, and webhook fulfillment already wired.
</Card>

***

## 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

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

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

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

<Card title="Authentication" icon="key" href="/api-reference/authentication">
  API keys, OAuth2 authorization code flow, scopes, and key rotation.
</Card>

***

## 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.
For paid purchases that reduce stock, handle `order:paid:product`; `product:stock` is for direct catalog stock edits.
New handlers should verify the timestamped `X-Shoppex-Signature-V2` header.

<Card title="Webhooks" icon="bolt" href="/api-reference/webhooks/overview">
  Event catalog, signing, retries, and the dynamic delivery contract for `DYNAMIC` products.
</Card>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Next.js Quickstart" icon="bolt" href="/headless/quickstart-nextjs">
    End-to-end build: list products, create a checkout session, verify webhooks.
  </Card>

  <Card title="Storefront Starter" icon="store" href="/headless/storefront-starter">
    Use the official starter when you want a complete custom storefront foundation.
  </Card>

  <Card title="Headless Checkout SDK" icon="credit-card" href="/headless/checkout">
    Build the payment step on your own domain with a publishable key and origin allowlist.
  </Card>

  <Card title="Architecture Reference" icon="sitemap" href="/headless/architecture">
    Three reference setups: pure SPA, Next.js SSR, mobile with backend-for-frontend.
  </Card>

  <Card title="Use Cases" icon="shapes" href="/headless/use-cases/discord-bot-shop">
    Discord bots, SaaS paywalls, mobile apps, gaming resellers.
  </Card>

  <Card title="Dev API Reference" icon="code" href="/api-reference/introduction">
    Every endpoint, request shape, and response schema under `/dev/v1/*`.
  </Card>
</CardGroup>