> ## 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.
# Storefront SDK reference
> Complete method and type reference for the Shoppex Storefront SDK
This page lists every method and type in `@shoppexio/storefront`, grouped by object: Store, Products, Cart, Checkout, Reviews and invoices, and Types.
All async SDK methods return `SDKResponse`, a wrapper containing `data`, `error`, and `status` fields. See [Response types](#response-types) for the full definition.
## Store
The Store object gives access to your shop's public information, including name, branding, and settings.
For simple cases such as displaying the store logo, use `getStoreLogoUrl()` or `getStoreBannerUrl()`. They are lightweight wrappers that avoid fetching the full store metadata.
### getStore
Fetches the store's public metadata.
```javascript theme={"system"}
const { data: store } = await shoppex.getStore();
console.log(store.name); // "My Awesome Store"
console.log(store.currency); // "USD"
```
**Response**
Unique store identifier
Store display name
URL-friendly store identifier
Custom domain if configured
Store description
Default currency (ISO 4217)
Logo image URL
Banner image URL
Average store rating (1-5)
Whether terms of service are enabled
Social media links
Discord URLTwitter URLInstagram URLFacebook URLTelegram URLYouTube URLReddit URLTikTok URL
**Example: display store header**
```javascript theme={"system"}
async function renderStoreHeader() {
const { data: store } = await shoppex.getStore();
document.getElementById('store-header').innerHTML = `
${store.name}
${store.rating ? `${store.rating.toFixed(1)} / 5` : ''}
`;
}
```
### getStoreLogoUrl
Returns the store's logo URL directly.
```javascript theme={"system"}
const logoUrl = await shoppex.getStoreLogoUrl();
if (logoUrl) {
document.getElementById('logo').src = logoUrl;
}
```
**Response**
Logo URL or `null` if no logo is set
### getStoreBannerUrl
Returns the store's banner URL directly.
```javascript theme={"system"}
const bannerUrl = await shoppex.getStoreBannerUrl();
if (bannerUrl) {
document.getElementById('hero').style.backgroundImage = `url(${bannerUrl})`;
}
```
**Response**
Banner URL or `null` if no banner is set
### Store error handling
```javascript theme={"system"}
try {
const { data, success, message } = await shoppex.getStore();
if (!success) {
console.error('Failed to load store:', message);
return;
}
// Use store data
} catch (error) {
if (error.name === 'NotInitializedError') {
console.error('SDK not initialized. Call shoppex.init() first.');
} else if (error.name === 'NetworkError') {
console.error('Network error. Check your connection.');
}
}
```
## Products
Fetch products from your store, including variants, addons, and custom fields.
### getProducts
Fetches all products from the store.
```javascript theme={"system"}
const { data: products } = await shoppex.getProducts();
products.forEach(product => {
console.log(product.title, product.price);
});
```
**Response**
Array of products
Unique product identifier
Product name
Base price as string (for precision). Use `shoppex.formatPrice()` to display.
Currency code (ISO 4217)
URL-friendly product identifier
Full product description (HTML)
Merchant-defined extra description tabs (for example, Features, Specifications). `content` is HTML. Empty array when the product has no extra tabs.
Array of product images
Optimized cover image for cards, listings, search results, and other non-zoomed UI.
High-resolution primary image for product detail pages, galleries, and zoom views.
Optional product video URL (YouTube, Streamable, or Vimeo). `null` when no video is configured.
Available variants (for example, size, color)
Optional add-ons
Price-based variants (for example, subscription tiers)
Custom input fields for checkout
Available stock quantity
Product categories as objects with `uniqid` and `title`
Product prices are returned as `string` types to preserve decimal precision. Always use `shoppex.formatPrice()` for display. Do not calculate directly with price strings.
Use product images by surface:
* `cdn_image_url` for product cards, category grids, cart rows, and search results
* `detail_image_url` for product detail pages, image galleries, and zoom
* `images[]` for the full gallery
Simple example: if your custom storefront currently renders the PDP hero from `cdn_image_url`, switch that hero to `detail_image_url` to get the higher-resolution image.
**Example: product grid**
```javascript theme={"system"}
async function renderProducts() {
const { data: products } = await shoppex.getProducts();
const container = document.getElementById('products');
container.innerHTML = products.map(product => `
`;
}
```
### getCategories
Fetches all unique product category IDs from your store.
```javascript theme={"system"}
const { data: categories } = await shoppex.getCategories();
// Returns array of category uniqids (strings)
// ["cat_abc123", "cat_def456", "cat_ghi789"]
```
**Example: category filter**
```javascript theme={"system"}
async function renderCategoryFilter() {
const { data: categories } = await shoppex.getCategories();
document.getElementById('category-filter').innerHTML = `
`;
}
async function filterByCategory(category) {
const { data: products } = await shoppex.getProducts();
const filtered = category
? products.filter(p => p.categories?.includes(category))
: products;
renderProducts(filtered);
}
```
### Product groups
Stores can organize products into groups (for example, "Server Boosts", "Tokens"). Groups come from `getStorefront()`.
```javascript theme={"system"}
const { data: storefront } = await shoppex.getStorefront();
storefront.groups.forEach(group => {
console.log(group.title, group.products_count);
});
```
Breaking change in `@shoppexio/storefront` 1.0.0 (and the underlying storefront API): groups no longer embed full product objects in `products_bound`. Each group now carries `product_uniqids`, an array of product references, and every public product, standalone and group-bound, appears exactly once in the flat products list. If your integration reads `group.products_bound`, it sees `undefined` and must migrate to the lookup pattern below.
**Group object**
Unique group identifier
Group name
References to the group's products. Resolve them against the flat products list. The full product objects are not embedded in the group.
Number of products in the group
Display order of the group
**Resolving group products**
Build a lookup from the flat products list and resolve each group's references.
```javascript theme={"system"}
const { data: storefront } = await shoppex.getStorefront();
const byUniqid = new Map(storefront.products.map(p => [p.uniqid, p]));
storefront.groups.forEach(group => {
const groupProducts = (group.product_uniqids ?? [])
.map(uniqid => byUniqid.get(uniqid))
.filter(Boolean);
console.log(group.title, groupProducts.map(p => p.title));
});
```
If you install the SDK from npm, the same resolution is available as a named import.
```javascript theme={"system"}
import { getStorefrontGroupProducts } from '@shoppexio/storefront';
const groupProducts = getStorefrontGroupProducts(group, storefront.products);
```
Migrating from 0.3.x? Replace every `group.products_bound` read with the lookup above. `getProducts()` now returns the complete flat catalog, group-bound products included, so you no longer need to merge group products into your listing yourself. If you call the REST API directly, `/v1/storefront/products/public/:slug` groups carry `product_uniqids`. The `/v1/storefront/products/shop/:name` endpoint no longer returns groups at all. Read groups from the public catalog or bootstrap payload instead.
### Working with variants
Products can have multiple variant types.
**Standard variants**
Variants such as size or color that do not change the price.
```javascript theme={"system"}
const product = await shoppex.getProduct('prod_abc');
product.variants.forEach(variant => {
console.log(variant.id, variant.title);
// "var_1", "Small"
// "var_2", "Medium"
// "var_3", "Large"
});
```
**Price variants**
Variants that have different prices.
```javascript theme={"system"}
product.price_variants.forEach(pv => {
console.log(pv.id, pv.label, pv.price);
// "pv_1", "Basic", 9.99
// "pv_2", "Pro", 29.99
// "pv_3", "Enterprise", 99.99
});
```
**Addons**
Optional extras the customer can add.
```javascript theme={"system"}
product.addons.forEach(addon => {
console.log(addon.id, addon.name, addon.price, addon.required);
// "addon_1", "Priority Support", 5.00, false
// "addon_2", "Extended Warranty", 10.00, false
});
```
### Products error handling
```javascript theme={"system"}
const { data, success, message } = await shoppex.getProduct('invalid-id');
if (!success) {
console.error('Product not found:', message);
// Show 404 page or redirect
}
```
## Cart
The Cart object manages shopping cart state in the browser's localStorage. Cart data stays saved across page refreshes and browser sessions.
Cart data is stored in the browser's `localStorage`. If the user clears browser storage, the cart is lost.
### getCart
Returns all items currently in the cart.
```javascript theme={"system"}
const cartItems = shoppex.getCart();
cartItems.forEach(item => {
console.log(item.product_id, item.quantity);
});
```
**Response**
Product unique identifier
Selected variant ID (empty string if no variant)
Item quantity
Selected add-ons
Custom field values
Selected price variant ID
### getCartItemCount
Returns the total number of items in the cart.
```javascript theme={"system"}
const count = shoppex.getCartItemCount();
document.getElementById('cart-badge').textContent = count;
```
### addToCart
Adds an item to the cart, or increments quantity if it already exists.
```javascript theme={"system"}
// Basic usage
shoppex.addToCart('prod_abc123', 'var_001', 1);
// With options
shoppex.addToCart('prod_abc123', 'var_001', 2, {
addons: [{ id: 'addon_1', quantity: 1 }],
custom_fields: { 'License Name': 'John Doe' },
price_variant_id: 'pv_pro'
});
```
**Parameters**
Product unique identifier
Variant ID. Use empty string `''` for products without variants.
Number of items to add
Add-ons to include
Custom field values
Selected price variant
**Example: add to cart button**
```javascript theme={"system"}
function handleAddToCart(productId, variantId) {
const quantity = parseInt(document.getElementById('quantity').value) || 1;
// Collect selected addons
const addons = [];
document.querySelectorAll('.addon-checkbox:checked').forEach(cb => {
addons.push({ id: cb.value, quantity: 1 });
});
shoppex.addToCart(productId, variantId, quantity, { addons });
// Update UI
updateCartBadge();
showNotification('Added to cart!');
}
```
### updateCartItem
Updates an existing cart item.
```javascript theme={"system"}
shoppex.updateCartItem('prod_abc123', 'var_001', {
quantity: 5,
addons: [{ id: 'addon_2', quantity: 1 }]
});
```
**Parameters**
Product unique identifier
Variant ID
New quantity
Updated add-ons
Updated custom fields
### removeFromCart
Removes an item from the cart.
```javascript theme={"system"}
shoppex.removeFromCart('prod_abc123', 'var_001');
```
**Parameters**
Product unique identifier
Variant ID
### clearCart
Removes all items from the cart.
```javascript theme={"system"}
shoppex.clearCart();
```
### Cart backup
The SDK can back up the cart before checkout, to restore it if checkout is cancelled.
**createCartBackup**
```javascript theme={"system"}
// Called automatically before checkout
shoppex.createCartBackup();
```
**restoreCartFromBackup**
```javascript theme={"system"}
// Restore cart after cancelled checkout
const restored = shoppex.restoreCartFromBackup();
if (restored) {
console.log('Cart restored');
} else {
console.log('No backup available');
}
```
### Complete cart UI example
```html theme={"system"}
Shopping Cart
```
## Checkout
The Checkout object redirects customers to Shoppex hosted checkout. Checkout is fully hosted by Shoppex for PCI compliance.
### checkout
Redirects the customer to the checkout page with their cart contents.
```javascript theme={"system"}
await shoppex.checkout();
```
**Parameters**
Pre-applied coupon code
Automatically redirect to checkout page
Override checkout language
**Example: checkout with coupon**
```javascript theme={"system"}
const couponCode = document.getElementById('coupon-input').value;
if (couponCode) {
// Validate coupon first
const { data } = await shoppex.validateCoupon(couponCode);
if (!data.valid) {
alert('Invalid coupon code');
return;
}
}
// Proceed to checkout
await shoppex.checkout(couponCode);
```
### buildCheckoutUrl
Builds the checkout URL without redirecting. Use this to open checkout in a new tab or iframe.
```javascript theme={"system"}
const checkoutUrl = await shoppex.buildCheckoutUrl('SAVE10', { locale: 'de' });
console.log(checkoutUrl);
// https://yourstore.shoppex.io/checkout?coupon=SAVE10&locale=de&cart=...
```
**Parameters**
Coupon code to pre-apply
Checkout language (for example, 'en', 'de', 'fr')
**Example: open checkout in new tab**
```javascript theme={"system"}
async function openCheckoutInNewTab() {
const url = await shoppex.buildCheckoutUrl();
window.open(url, '_blank');
}
```
### buildCheckoutUrlSync (deprecated)
`buildCheckoutUrlSync` is deprecated and throws immediately. Use `buildCheckoutUrl()` instead. It handles both default and custom domains.
### Coupons
**validateCoupon**
Validates a coupon code before checkout. Affiliate and referral codes are separate from coupons. Use `validateAffiliateCode` or `applyAffiliateCode` for those instead.
```javascript theme={"system"}
const { data } = await shoppex.validateCoupon('SAVE10', {
productId: 'prod_abc123',
variantId: 'variant_lifetime',
});
if (data.valid) {
console.log('Discount:', data.discount, data.discount_type);
// 10, "percentage" → 10% off
// 5.00, "fixed" → $5 off
} else {
console.log('Invalid or expired coupon');
}
```
**Parameters**
Coupon code to validate
Product ID to check product-specific coupons
Selected variant ID to check variant-specific coupons. Requires `options.productId`.
**Response**
Whether the coupon is valid
Discount amount
Either "percentage" or "fixed"
Whether the coupon is restricted to selected products
Whether the coupon is restricted to selected variants
One of "all", "products", "variants", or "products\_and\_variants"
Public product IDs the coupon can apply to
Variant IDs the coupon can apply to
### Affiliate codes
**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,
});
```
**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 = `