Skip to main content
The Shoppex Storefront Starter is for merchants who want a custom storefront without rebuilding commerce. Simple example: 
yourdomain.com          -> your Next.js storefront
checkout.shoppex.io     -> Shoppex hosted checkout
account.yourdomain.com  -> Shoppex customer portal
Use this starter when you want to own the frontend. Use a hosted Shoppex theme when you want Shoppex to own the storefront UI too.

​
Create a Storefront

bunx create-shoppex-storefront my-store
cd my-store
bun install
bun run dev
For non-interactive setup: 
bunx create-shoppex-storefront my-store \
  --shop-slug your-shop \
  --customer-portal-url https://account.yourdomain.com \
  --checkout-mode cart
The command creates a Next.js app, writes .env.local, and points the starter at your Shoppex shop.

​
What Is Included

Storefront UI

Homepage, product grid, product detail pages, product images, variants, stock count, and sold-out states.

Cart and Checkout

Browser-local cart, checkout review, email capture, coupon field, terms acknowledgement, and Shoppex invoice handoff.

Customer Portal Link

Link buyers to orders, downloads, license keys, and support through the Shoppex customer portal.

Webhook Example

Signed webhook route for paid order events, with a Discord notification example for fulfillment visibility.

​
Configure Shoppex

Set these values in .env.local: 
NEXT_PUBLIC_SHOPPEX_SHOP_SLUG=your-shop
NEXT_PUBLIC_CUSTOMER_PORTAL_URL=https://account.yourdomain.com
SHOPPEX_WEBHOOK_SECRET=whsec_your_secret
SHOPPEX_DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/...
Then edit: 
shoppex.config.ts
theme.config.ts
Simple example: 
export const shoppexConfig = {
  shopSlug: process.env.NEXT_PUBLIC_SHOPPEX_SHOP_SLUG ?? "demo",
  checkoutMode: "cart",
  showStockCount: true,
  customerPortal: {
    mode: "branded-subdomain",
    url: process.env.NEXT_PUBLIC_CUSTOMER_PORTAL_URL ?? "https://demo.myshoppex.io/dashboard",
  },
};

​
Checkout Modes

ModeUse it for
cartNormal stores with multiple products and a cart drawer
buy-nowOne-product stores where the product page should go straight to checkout
embedSimple product-button flows that use the Checkout Embed SDK
The default is cart.

​
Cart Model

The starter cart lives in the buyer’s browser until checkout. At checkout, Shoppex rechecks:
  • product availability
  • selected variants
  • quantity limits
  • prices
  • coupons
  • stock
If something changed, the checkout page shows a recovery state instead of a generic error. Simple example: 
Buyer has 5 items in cart
Shop stock changes to 2
Checkout asks the buyer to reduce the quantity before payment
The starter does not reserve stock when a buyer adds an item to the cart. Stock is validated when the Shoppex invoice is created.

​
Customer Portal

For a fully self-hosted storefront, use a branded account subdomain: 
yourdomain.com          -> Next.js storefront
account.yourdomain.com  -> Shoppex customer portal
Fastest setup: 
https://your-shop.myshoppex.io/dashboard
Use /dashboard only when the storefront domain is routed through the Shoppex Storefront Worker.

​
Moving from Another Platform

Treat this as a fresh storefront cutover. Move these into Shoppex:
  • products
  • prices
  • variants
  • stock
  • checkout settings
  • fulfillment webhooks
The starter does not automatically import old order history, old customer accounts, or previous platform-specific embeds.

​
Deploy

Deploy the generated project to Vercel and set the same environment variables there. 
NEXT_PUBLIC_SHOPPEX_SHOP_SLUG
NEXT_PUBLIC_CUSTOMER_PORTAL_URL
SHOPPEX_WEBHOOK_SECRET
SHOPPEX_DISCORD_WEBHOOK_URL
After deploy, create a Shoppex webhook endpoint: 
https://yourdomain.com/api/shoppex/webhook
Subscribe it to paid order events such as order:paid and order:paid:product.

​
Next Steps

Headless Overview

Understand the three integration shapes: Dev API, Storefront SDK, and Checkout Embed SDK.

Checkout Embed SDK

Add modal checkout to existing pages or product buttons.

Storefront SDK

Read public product and storefront data from your custom frontend.

Webhooks

Verify paid order events and run fulfillment after payment.