SDK Reference Every public method available on shoppex after importing the SDK.
import shoppex from '@shoppexio/storefront' ;
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.
Method Returns Description init(storeSlug: string, options?: ShoppexInitOptions)voidInitialize the SDK with a store slug. Must be called before any API method. init(options: ShoppexInitOptions & { storeId: string })voidAlternative init overload. Internally, storeId is used as the SDK’s storeSlug. isInitialized()booleanCheck whether init() has been called. getConfig()ShoppexConfigReturn 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' });
Method Returns Description getStore()Promise<SDKResponse<Shop>>Fetch the shop object only. getStorefront()Promise<SDKResponse<StorefrontData>>Fetch shop, products, groups, mixed items, 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, items, categories } in one API call. Use items when you need the merchant’s manual storefront order across groups and products.
// Single call for all storefront data const res = await shoppex . getStorefront (); if ( res . success && res . data ) { const { shop , products , groups , items , 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 hideOutOfStockbooleanundefinedExclude out-of-stock products from results.
const results = await shoppex . searchProducts ( 'hoodie' , { hideOutOfStock: true });
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()numberReturn total number of items (sum of quantities). addToCart(productId, variantId, quantity?, options?)voidAdd a product variant to the cart. Defaults to quantity 1. updateCartItem(productId, variantId, updates)voidPartially update a cart item (e.g. change quantity). removeFromCart(productId, variantId)voidRemove a specific product variant from the cart. clearCart()voidRemove all items from the cart. getCartStats()CartStatsReturn cart summary (total, item count, etc.). validateCartIntegrity()booleanCheck that all cart items are structurally valid. createCartBackup()voidSnapshot the current cart to a backup slot. restoreCartFromBackup()booleanRestore 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)voidMove 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()neverDeprecated. Throws immediately. Use buildCheckoutUrl instead.
The first argument can be a coupon code string or a 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)ResolvedThemeSettingsCompute default values from a theme config. mergeSettings(defaults, overrides)ResolvedThemeSettingsMerge 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?)stringFormat a price for display (e.g. "€12.99"). createFormatter(currency?, locale?)Intl.NumberFormatCreate 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.
The SDK caches API responses in memory. Use these methods to manage the cache manually.
Method Returns Description clearCache()voidClear all cached responses. invalidateCache(prefixOrKey: string)voidInvalidate a specific cache entry or all entries matching a prefix. getCacheStats()CacheStatsReturn { hits, misses, pendingRequests, entries }.
console . log ( shoppex . getCacheStats ()); // { hits: 12, misses: 3, pendingRequests: 0, entries: 5 } shoppex . invalidateCache ( 'storefront' ); shoppex . clearCache ();
Next Steps
Cart & Checkout Add-to-cart flows, coupon validation, and checkout integration.
MSW Mocking Use mock data for local development without a real backend.
