Headless customer accounts

Use @shoppexio/storefront/customer when your storefront runs on your own domain and you want to build the customer panel yourself. Shoppex handles email OTP login, tenant isolation, orders, and download authorization. Your frontend owns the UI.

Headless customer accounts require an active Business plan. They reuse the same publishable key and allowed origins as Headless Checkout.

Setup

Open Dashboard -> Settings -> Developer -> Headless Checkout. Generate a publishable key and add the exact origin that hosts the customer page, for example https://yourstore.com.

npm install @shoppexio/storefront

import { createCustomerClient } from '@shoppexio/storefront/customer';

const customer = createCustomerClient({
  shop: 'your-shop-slug',
  publishableKey: 'pk_live_your_key',
});

The publishable key is browser-safe. Never use a secret shx_ Developer API key in this client.

await customer.requestOtp('[email protected]');

await customer.verifyOtp('[email protected]', '123456', {
  rememberMe: true,
});

Normal login is stored in sessionStorage and is valid for up to 12 hours. rememberMe: true stores it in localStorage and keeps the customer signed in for up to 30 days. Both are capped by the underlying Shoppex buyer session. A logout or an unauthorized response removes the saved session. Use rememberMe only after the buyer explicitly selects a Keep me signed in option on a private device.

Customer and orders

const profile = await customer.me();

const firstPage = await customer.orders({
  page: 1,
  limit: 20,
  status: 'COMPLETED',
  search: 'invoice-id',
});

const order = await customer.order('invoice-uuid');

The client validates the me, order-list, and order-detail response contracts before returning them. Prices remain decimal strings so your UI does not introduce floating-point rounding.

Downloads

const order = await customer.order('invoice-uuid');
const downloadIndex = order.lineItems
  .flatMap((item) => item.deliverySummary?.links ?? [])
  .find((item) => item.downloadIndex !== undefined)?.downloadIndex;

if (downloadIndex === undefined || downloadIndex === null) {
  throw new Error('This order has no downloadable file');
}

const file = await customer.download(order.uniqid, downloadIndex);
const url = URL.createObjectURL(file.blob);

const link = document.createElement('a');
link.href = url;
link.download = file.filename ?? 'download';
link.click();
URL.revokeObjectURL(url);

Shoppex checks that the invoice belongs to the signed-in buyer before it returns the file. Always pass the downloadIndex returned by order(). The SDK removes hosted-portal-only download URLs so a self-hosted site never follows a broken /api/customer/* link or receives an unsafe aggregate HTML launcher.

Logout and session state

const activeSession = customer.getSession();

await customer.logout();
customer.clearSession();

logout() revokes only this external customer session. It does not sign the buyer out of a separate Shoppex-hosted customer portal tab. If the network request fails, the SDK keeps the local token so your UI can retry the revocation; a successful logout or an already-unauthorized response clears it.

Security boundary

Every customer request must pass all of these checks:

valid pk_live_ or pk_test_ publishable key
exact browser Origin in the shop’s allowed-origin list
active Business plan
valid hcs_ customer session bound to the same origin and shop
invoice ownership for order detail and downloads

The first release is intentionally read-only. It exposes profile data, order history, order detail, downloads, and logout. Customer mutations, wallet actions, subscription changes, reseller orders, and merchant APIs are not available through this token.

Start here

Invoices and payments

Webhooks

Headless commerce

Storefront SDK

Checkout embeds

Integrations

Resellers

Email marketing

Tutorials

Headless customer accounts

Setup

Customer and orders

Downloads

Logout and session state

Security boundary

​Setup

​OTP login

​Customer and orders

​Downloads

​Logout and session state

​Security boundary

Setup

OTP login

Customer and orders

Downloads

Logout and session state

Security boundary