${shoppex.formatPrice(product.price, product.currency)}
` from the current URL and stores the normalized code for 30 days (last click wins). `checkout()` and `quoteCart()` pick the stored code up automatically, so this one call is what makes affiliate links like `https://mystore.com/product?ref=creator10` actually apply the discount and credit the affiliate.
```javascript theme={"system"}
// Call once on every page load, right after shoppex.init(...)
await shoppex.captureAffiliateFromUrl();
```
If you build a storefront on your own code (instead of starting from an official template), you must make this call yourself on page load. Without it, buyers arriving through affiliate links pay full price and the affiliate is never credited — with no error anywhere. The official code storefront templates already include it.
The call also reports the referral click to the backend for the affiliate's click statistics, and it validates the code — a code the shop refuses is cleared again. A network failure keeps the raw code stored; checkout validates it server-side either way. Pass a custom parameter name to capture something other than `?ref=`: `captureAffiliateFromUrl('via')`.
**validateAffiliateCode**
Validates an affiliate or referral code without storing it.
```javascript theme={"system"}
const result = await shoppex.validateAffiliateCode('creator10');
if (result.success && result.data.valid) {
console.log(result.data.affiliate_code);
} else if (result.data?.program_enabled === false) {
console.log('Affiliate program is disabled for this shop');
}
```
**applyAffiliateCode**
Validates and stores the normalized affiliate code. `checkout()` sends the stored code as `affiliate_code`.
```javascript theme={"system"}
const affiliate = await shoppex.applyAffiliateCode('creator10');
await shoppex.checkout({
coupon: 'SAVE10',
affiliateCode: affiliate.data?.affiliate_code,
});
```
**getAffiliateCode / clearAffiliateCode**
`getAffiliateCode()` returns the currently stored (non-expired) affiliate code or `null` — useful for showing a "referral applied" badge. `clearAffiliateCode()` removes it.
**Example: coupon input with validation**
```html theme={"system"}
```
### Checkout flow
```
┌─────────────────────────────────────────────────────────────────┐
│ Your Website │
├─────────────────────────────────────────────────────────────────┤
│ 1. Customer browses products │
│ 2. Adds items to cart (SDK stores in localStorage) │
│ 3. Clicks "Checkout" │
│ 4. SDK calls shoppex.checkout() │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Shoppex Checkout │
│ (yourstore.shoppex.io) │
├─────────────────────────────────────────────────────────────────┤
│ 5. Customer enters email, billing info │
│ 6. Selects payment method (Stripe, PayPal, Crypto) │
│ 7. Completes payment │
│ 8. Receives confirmation + delivery │
└─────────────────────────────────────────────────────────────────┘
```
### After checkout
After successful checkout, the cart is automatically cleared. If you need to handle the return, read the order ID from the URL.
```javascript theme={"system"}
// Check URL for order confirmation
const urlParams = new URLSearchParams(window.location.search);
const orderId = urlParams.get('order');
if (orderId) {
// Customer returned from successful checkout
showOrderConfirmation(orderId);
}
```
## Reviews and invoices
This section documents two separate objects: shop reviews and invoice status.
### getShopReviews
Fetches all public reviews for the store.
```javascript theme={"system"}
const { data: reviews } = await shoppex.getShopReviews();
reviews.forEach(review => {
console.log(review.rating, review.comment);
});
```
**Response**
Review unique identifier
Star rating (1-5)
Review text
ISO timestamp
**Example: reviews section**
```javascript theme={"system"}
async function renderReviews() {
const { data: reviews } = await shoppex.getShopReviews();
const container = document.getElementById('reviews');
// Calculate average
const avgRating = reviews.reduce((sum, r) => sum + r.rating, 0) / reviews.length;
container.innerHTML = `
Customer Reviews
${'★'.repeat(Math.round(avgRating))}${'☆'.repeat(5 - Math.round(avgRating))}
${avgRating.toFixed(1)} / 5
(${reviews.length} reviews)
${reviews.map(review => `
${'★'.repeat(review.rating)}${'☆'.repeat(5 - review.rating)}
${review.comment || ''}
${new Date(review.created_at).toLocaleDateString()}
`).join('')}
`;
}
```
### getInvoice
Fetches full invoice details.
```javascript theme={"system"}
const { data: invoice } = await shoppex.getInvoice('inv_abc123');
console.log(invoice.status); // "COMPLETED"
console.log(invoice.total); // 29.99
console.log(invoice.products); // [{ title, quantity, price }]
```
**Response**
Invoice unique identifier
Invoice status (PENDING, COMPLETED, CANCELLED, and more)
Total amount
Currency code
Purchased products
### getInvoiceStatus
Lightweight endpoint for status polling. Use this instead of `getInvoice` for real-time updates.
```javascript theme={"system"}
const { data } = await shoppex.getInvoiceStatus('inv_abc123');
console.log(data.status); // "PENDING" | "COMPLETED" | "CANCELLED"
```
**Example: order status page**
```javascript theme={"system"}
async function pollOrderStatus(invoiceId) {
const statusEl = document.getElementById('order-status');
const checkStatus = async () => {
const { data } = await shoppex.getInvoiceStatus(invoiceId);
switch (data.status) {
case 'PENDING':
statusEl.innerHTML = 'Waiting for payment...';
break;
case 'PROCESSING':
statusEl.innerHTML = 'Processing payment...';
break;
case 'COMPLETED':
statusEl.innerHTML = 'Order complete! Check your email.';
clearInterval(pollInterval);
break;
case 'CANCELLED':
statusEl.innerHTML = 'Order cancelled';
clearInterval(pollInterval);
break;
}
};
// Poll every 5 seconds
const pollInterval = setInterval(checkStatus, 5000);
checkStatus(); // Initial check
}
// Get invoice ID from URL
const invoiceId = new URLSearchParams(window.location.search).get('invoice');
if (invoiceId) {
pollOrderStatus(invoiceId);
}
```
### Formatting utilities
**formatPrice**
Formats a price with a currency symbol.
```javascript theme={"system"}
shoppex.formatPrice(29.99, 'USD'); // "$29.99"
shoppex.formatPrice(29.99, 'EUR'); // "€29.99"
shoppex.formatPrice(29.99, 'EUR', 'de'); // "29,99 €"
```
**Parameters**
Price amount
ISO 4217 currency code
Locale for formatting
**createFormatter**
Creates a reusable `Intl.NumberFormat` instance.
```javascript theme={"system"}
const formatter = shoppex.createFormatter('EUR', 'de');
formatter.format(29.99); // "29,99 €"
formatter.format(100); // "100,00 €"
```
## Customer account
Calls for a signed-in customer: sign-in, order history, licenses, subscriptions, support and profile. They work only on a storefront served on the merchant's own domain by Shoppex, because that is where the session lives.
The session is an HttpOnly cookie set by the Shoppex edge, and the shop is derived from the host. So none of these calls take or return a session token, and none of them take a shop. Do not send either.
| Call | Endpoint | Purpose |
| ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- | --------------------------------------------------------- |
| `requestOtp(email)` | `POST /api/customer/auth/otp/request` | Email a single-use sign-in code |
| `verifyOtp(email, otp)` | `POST /api/customer/auth/otp/verify` | Complete sign-in. The cookie arrives with the response |
| `logout()` | `POST /api/customer/auth/logout` | End the session |
| `me()` | `GET /api/customer/me` | Who is signed in, if anyone |
| `dashboard()` | `GET /api/customer/dashboard` | Overview: customer, counters, store credit, recent orders |
| `orders({ page, limit })` | `GET /api/customer/invoices` | Order history, one page at a time |
| `order(uniqid)` | `GET /api/customer/invoice/` | One order with line items, delivery and payment |
| `resetLicenseHwid(uniqid)` | `POST /api/customer/licenses//reset-hwid` | Unbind a licence from its device |
| `subscriptionBillingHistory(uniqid)` | `GET /api/customer/subscriptions//billing-history` | Past charges for one subscription |
| `cancelSubscription(uniqid, options)`, `pauseSubscription(uniqid)`, `resumeSubscription(uniqid)` | `POST /api/customer/subscriptions//…` | Change a subscription's standing |
| `favorites()`, `addFavorite(productUniqid)`, `removeFavorite(productUniqid)` | `GET`, `PUT` and `DELETE /api/customer/favorites` | Saved products. Adding is a `PUT`, not a `POST` |
| `affiliate()` | `GET /api/customer/affiliate` | Referral summary |
| `createTicket(payload)`, `ticket(uniqid)`, `replyToTicket(uniqid, message)` | `POST` and `GET /api/customer/tickets…` | Support conversations |
| `updateProfile({ name })` | `POST /api/customer/profile` | Change the display name |
| `updateAvatar(file)`, `removeAvatar()` | `POST` and `DELETE /api/customer/profile/avatar` | Profile photo |
| `emailPreferences()`, `updateEmailPreferences(patch)` | `GET` and `PATCH /api/customer/email-marketing/preferences` | Marketing opt-in and per-list subscriptions |
| `sessions()`, `revokeSession(id)`, `revokeAllSessions()` | `GET` and `DELETE /api/customer/sessions` | Signed-in devices |
**Licences, subscriptions and tickets have no list call.** Those three
collections arrive inside `dashboard()`; the endpoints above act on one item
you already have an id for. A `GET /api/customer/licenses` does not exist and
answers `404` at the edge.
```javascript theme={"system"}
await shoppex.requestOtp('buyer@example.com');
const signedIn = await shoppex.verifyOtp('buyer@example.com', '123456');
if (signedIn.success) {
const { data } = await shoppex.dashboard();
console.log(data.customer.email, data.stats.invoices_count);
}
```
Order history is page based. `has_more` says whether a next page exists; there is no cursor.
```javascript theme={"system"}
const { data } = await shoppex.orders({ page: 1, limit: 10 });
data.invoices.forEach((order) => console.log(order.uniqid, order.status));
console.log(data.pagination.has_more);
```
The endpoint list above is complete. Endpoints outside it, including license renewal, affiliate payouts, the subscription payment-method portal, reseller surfaces and wallet transfers, answer `404` at the edge. Link customers to the hosted flow for those.
Building the account pages into a code storefront, including routing and the states to handle: [Customer accounts](/storefront/code-storefront-accounts).
## Types
The SDK is written in TypeScript and exports all type definitions. Install with npm to get full IntelliSense support.
### Configuration types
```typescript theme={"system"}
interface ShoppexConfig {
storeSlug: string;
locale?: string;
currency?: string;
apiBaseUrl?: string;
}
interface ShoppexInitOptions {
locale?: string;
currency?: string;
apiBaseUrl?: string;
}
```
### Response types
```typescript theme={"system"}
interface SDKResponse {
success: boolean;
data?: T;
message?: string;
}
```
### Store types
```typescript theme={"system"}
interface Shop {
id: string;
name: string;
slug: string;
domain?: string;
description?: string;
currency: string;
logo?: string;
banner?: string;
rating?: number;
tos_enabled?: boolean;
}
```
### Product types
```typescript theme={"system"}
interface ProductCategory {
uniqid: string;
title: string;
}
interface Product {
uniqid: string;
title: string;
slug?: string;
description?: string;
price: string; // String for precision
price_display?: string; // Formatted display price
currency: string;
stock?: number;
cdn_image_url?: string | null; // Card/listing/search image
detail_image_url?: string | null; // PDP/gallery/zoom image
images: ProductImage[];
variants?: ProductVariant[];
addons?: ProductAddon[];
price_variants?: PriceVariant[];
custom_fields?: string | unknown[] | null;
categories?: ProductCategory[];
}
interface ProductImage {
id: string;
url: string;
cloudflare_image_id?: string;
alt?: string;
}
interface ProductVariant {
id: string;
title: string;
price?: number;
stock?: number;
is_featured?: boolean;
}
interface ProductAddon {
id: string;
name: string;
price: number;
required?: boolean;
}
interface PriceVariant {
id: string;
label: string;
price: number;
is_featured?: boolean;
}
interface CustomFieldDefinition {
id: string;
name: string;
type: 'text' | 'textarea' | 'select' | 'checkbox';
required?: boolean;
options?: string[];
}
```
`is_featured` on `ProductVariant` and `PriceVariant` marks the one variant the merchant wants to present as “Most Popular.” At most one variant per product carries it. It does not change the selected variant, price, stock, or checkout behavior.
Image fields have different jobs:
* `cdn_image_url` is the optimized storefront cover for cards and lists
* `detail_image_url` is the higher-resolution primary image for product detail pages
* `images[]` contains the gallery
If you run a headless storefront, keep cards on `cdn_image_url` and switch your PDP hero and gallery to `detail_image_url`.
### Cart types
```typescript theme={"system"}
interface CartItem {
line_id: string;
product_id: string;
variant_id: string;
quantity: number;
addons?: CartAddon[];
custom_fields?: Record;
price_variant_id?: string;
}
interface CartAddon {
id: string;
quantity?: number;
}
interface CartAddOptions {
addons?: CartAddon[];
custom_fields?: Record;
price_variant_id?: string;
}
interface CartUpdateOptions {
quantity?: number;
addons?: CartAddon[];
custom_fields?: Record;
price_variant_id?: string;
}
```
### Checkout types
```typescript theme={"system"}
interface CheckoutOptions {
autoRedirect?: boolean;
locale?: string;
email?: string;
coupon?: string;
currency?: string;
redirectUrl?: string;
affiliateCode?: string;
referralCode?: string;
customerCheckoutPath?: '/dashboard/api/checkout';
expectedCart?: string;
}
interface CheckoutResult {
success: boolean;
redirectUrl?: string;
invoiceId?: string;
message?: string;
code?: string;
}
interface CouponValidation {
valid: boolean;
discount?: number;
discount_type?: 'percentage' | 'fixed';
message?: string;
}
```
### Invoice types
```typescript theme={"system"}
interface Invoice {
uniqid: string;
status: string;
total: number;
currency: string;
gateway?: string;
products: InvoiceProduct[];
created_at: string;
}
interface InvoiceProduct {
product_id: string;
title: string;
quantity: number;
price: number;
}
```
### Review types
```typescript theme={"system"}
interface Feedback {
id: string;
rating: number;
comment?: string;
created_at: string;
}
```
### Error types
```typescript theme={"system"}
class ShoppexError extends Error {
readonly code: string;
readonly statusCode?: number;
}
class CheckoutCreateError extends Error {
readonly code?: string;
readonly status?: number;
}
class NotInitializedError extends ShoppexError {
// Thrown when SDK methods are called before init()
// code: 'NOT_INITIALIZED'
}
class NetworkError extends ShoppexError {
// Thrown on HTTP/network failures
// code: 'NETWORK_ERROR'
}
class ValidationError extends ShoppexError {
// Thrown on input validation failures
// code: 'VALIDATION_ERROR'
readonly invalidFields?: string[];
}
class CartError extends ShoppexError {
// Thrown on cart operation errors
// code: 'BASKET_ERROR'
}
```
### Usage with TypeScript
```typescript theme={"system"}
import shoppex, {
type Product,
type ProductVariant,
type CartItem,
type Invoice,
type SDKResponse
} from '@shoppexio/storefront';
// Initialize
shoppex.init('my-store');
// Typed responses
async function loadProducts(): Promise {
const response: SDKResponse = await shoppex.getProducts();
if (!response.success || !response.data) {
throw new Error(response.message || 'Failed to load products');
}
return response.data;
}
// Type-safe cart operations
function addProductToCart(product: Product, variant?: ProductVariant): void {
shoppex.addToCart(
product.uniqid,
variant?.id ?? '',
1
);
}
// Typed invoice handling
async function checkOrderStatus(invoiceId: string): Promise {
const { data } = await shoppex.getInvoiceStatus(invoiceId);
return data.status;
}
```