SDK Reference
Every public method available on shoppex after importing the SDK.
import shoppex from '@shoppex/sdk';
Most storefront API methods return Promise<SDKResponse<T>> where SDKResponse is { success: boolean; data?: T; message?: string }. Exceptions include checkout() which returns Promise<CheckoutResult>, trackPageView() which returns Promise<void>, and helper methods like getStoreLogoUrl() which return Promise<string | null>. Cart methods are synchronous and operate on local state.
Init
| Method | Returns | Description |
|---|
init(storeSlug: string, options?: ShoppexInitOptions) | void | Initialize the SDK with a store slug. Must be called before any API method. |
init(options: ShoppexInitOptions & { storeId: string }) | void | Alternative init overload. Internally, storeId is used as the SDK’s storeSlug. |
isInitialized() | boolean | Check whether init() has been called. |
getConfig() | ShoppexConfig | Return the current SDK configuration (slug, API base URL, etc.). |
shoppex.init('my-shop', { apiBaseUrl: 'https://api.shoppex.io' });
console.log(shoppex.isInitialized()); // true
// Alternative overload
shoppex.init({ storeId: 'my-shop', apiBaseUrl: 'https://api.shoppex.io' });
Store
| Method | Returns | Description |
|---|
getStore() | Promise<SDKResponse<Shop>> | Fetch the shop object only. |
getStorefront() | Promise<SDKResponse<StorefrontData>> | Fetch shop, products, groups, and categories in a single API call. |
resolveStoreByDomain(domain?, apiBaseUrl?) | Promise<SDKResponse<Shop>> | Look up a shop by custom domain. |
getStoreLogoUrl() | Promise<string | null> | Get the shop logo URL. |
getStoreBannerUrl() | Promise<string | null> | Get the shop banner URL. |
getStore() vs getStorefront() — getStore() returns just the Shop object. getStorefront() returns { shop, products, groups, categories } in one API call. Use getStorefront() when you need everything at once.
// Single call for all storefront data
const res = await shoppex.getStorefront();
if (res.success && res.data) {
const { shop, products, groups, categories } = res.data;
}
// Shop only
const shopRes = await shoppex.getStore();
Products
| Method | Returns | Description |
|---|
getProducts() | Promise<SDKResponse<Product[]>> | Fetch all products for the store. |
getProduct(idOrSlug: string) | Promise<SDKResponse<Product>> | Fetch a single product by ID or slug. |
getCategories() | Promise<SDKResponse<string[]>> | Fetch all product category names. |
searchProducts(query: string, options?: SearchOptions) | Promise<SDKResponse<Product[]>> | Search products by text. |
SearchOptions:
| Field | Type | Default | Description |
|---|
hideOutOfStock | boolean | undefined | Exclude out-of-stock products from results. |
const results = await shoppex.searchProducts('hoodie', { hideOutOfStock: true });
Cart
Cart methods are synchronous and operate on local state (persisted to localStorage).
| Method | Returns | Description |
|---|
getCart() | CartItem[] | Return all items currently in the cart. |
getCartItemCount() | number | Return total number of items (sum of quantities). |
addToCart(productId, variantId, quantity?, options?) | void | Add a product variant to the cart. Defaults to quantity 1. |
updateCartItem(productId, variantId, updates) | void | Partially update a cart item (e.g. change quantity). |
removeFromCart(productId, variantId) | void | Remove a specific product variant from the cart. |
clearCart() | void | Remove all items from the cart. |
getCartStats() | CartStats | Return cart summary (total, item count, etc.). |
validateCartIntegrity() | boolean | Check that all cart items are structurally valid. |
createCartBackup() | void | Snapshot the current cart to a backup slot. |
restoreCartFromBackup() | boolean | Restore the cart from the last backup. Returns true if successful. |
mergeBaskets(items: CartItem[]) | CartItem[] | Merge external items into the current cart and return the result. |
moveBasketItem(fromProductId, fromVariantId, toProductId, toVariantId) | void | Move a line item from one variant to another. |
shoppex.addToCart('prod_123', 'var_456', 2);
console.log(shoppex.getCartItemCount()); // 2
shoppex.updateCartItem('prod_123', 'var_456', { quantity: 5 });
shoppex.removeFromCart('prod_123', 'var_456');
Checkout
| Method | Returns | Description |
|---|
checkout(couponOrOptions?, options?) | Promise<CheckoutResult> | Submit the cart and redirect to the hosted checkout page. |
buildCheckoutUrl(couponOrOptions?, options?) | Promise<string> | Build the checkout URL without redirecting. |
buildCheckoutUrlSync() | never | Deprecated. Throws immediately. Use buildCheckoutUrl instead. |
CheckoutOptions object:
// With coupon code
await shoppex.checkout('SAVE10');
// With options
await shoppex.checkout({ email: '[email protected]' });
// Build URL only
const url = await shoppex.buildCheckoutUrl('SAVE10');
Invoices
| Method | Returns | Description |
|---|
getInvoice(invoiceId: string) | Promise<SDKResponse<Invoice>> | Fetch full invoice details. |
getInvoiceStatus(invoiceId: string) | Promise<SDKResponse<{ status: string }>> | Fetch the current status of an invoice. |
Coupons
| Method | Returns | Description |
|---|
validateCoupon(code: string, productId?: string) | Promise<SDKResponse<CouponValidation>> | Check whether a coupon code is valid. Optionally scope to a product. |
const coupon = await shoppex.validateCoupon('SAVE10', 'prod_123');
if (coupon.success && coupon.data) {
console.log(coupon.data); // { valid: true, discount: 10, discount_type: 'percentage' }
}
Reviews
Shoppex has shop-level feedback (not product-level reviews).
| Method | Returns | Description |
|---|
getShopReviews() | Promise<SDKResponse<Feedback[]>> | Fetch public shop feedback entries. |
const res = await shoppex.getShopReviews();
if (res.success) {
console.log(res.data);
}
Theme Settings
| Method | Returns | Description |
|---|
fetchPublishedThemeSettings(shopSlug: string) | Promise<ResolvedThemeSettings | null> | Fetch the published theme settings from the API. |
resolveDefaults(config: ThemeConfig) | ResolvedThemeSettings | Compute default values from a theme config. |
mergeSettings(defaults, overrides) | ResolvedThemeSettings | Merge default settings with merchant overrides. |
const published = await shoppex.fetchPublishedThemeSettings('my-shop');
const defaults = shoppex.resolveDefaults(themeConfig);
const settings = shoppex.mergeSettings(defaults, published ?? {});
| Method | Returns | Description |
|---|
formatPrice(amount: number | string, currency?, locale?) | string | Format a price for display (e.g. "€12.99"). |
createFormatter(currency?, locale?) | Intl.NumberFormat | Create a reusable number formatter. |
shoppex.formatPrice(12.99, 'EUR', 'de-DE'); // "12,99 €"
const fmt = shoppex.createFormatter('USD', 'en-US');
fmt.format(9.99); // "$9.99"
Pages & Navigation
| Method | Returns | Description |
|---|
getPages() | Promise<SDKResponse<Page[]>> | Fetch all custom pages. |
getPage(slug: string) | Promise<SDKResponse<Page>> | Fetch a single page by slug. |
getMenus() | Promise<SDKResponse<Menu[]>> | Fetch all navigation menus. |
getMenu(title: string) | Promise<SDKResponse<Menu>> | Fetch a single menu by title. |
Analytics
| Method | Returns | Description |
|---|
trackPageView(cartValue?, itemCount?) | Promise<void> | Track a page view. Optionally include cart value and item count. |
Cache
The SDK caches API responses in memory. Use these methods to manage the cache manually.
| Method | Returns | Description |
|---|
clearCache() | void | Clear all cached responses. |
invalidateCache(prefixOrKey: string) | void | Invalidate a specific cache entry or all entries matching a prefix. |
getCacheStats() | CacheStats | Return { hits, misses, pendingRequests, entries }. |
console.log(shoppex.getCacheStats());
// { hits: 12, misses: 3, pendingRequests: 0, entries: 5 }
shoppex.invalidateCache('storefront');
shoppex.clearCache();
Next Steps
