All async SDK methods return
SDKResponse<T> — a wrapper containing data, error, and status fields.
See the Response tab below for the full definition.- Config
- Response
- Store
- Product
- Cart
- Checkout
- Error
Configuration Types
interface ShoppexConfig {
storeSlug: string;
locale?: string;
currency?: string;
apiBaseUrl?: string;
}
interface ShoppexInitOptions {
locale?: string;
currency?: string;
apiBaseUrl?: string;
}
API Response Types
interface SDKResponse<T> {
success: boolean;
data?: T;
message?: string;
}
Store Types
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
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;
}
interface ProductAddon {
id: string;
name: string;
price: number;
required?: boolean;
}
interface PriceVariant {
id: string;
label: string;
price: number;
}
interface CustomFieldDefinition {
id: string;
name: string;
type: 'text' | 'textarea' | 'select' | 'checkbox';
required?: boolean;
options?: string[];
}
Image fields have different jobs:
cdn_image_urlis the optimized storefront cover for cards and listsdetail_image_urlis the higher-resolution primary image for product detail pagesimages[]contains the gallery
cdn_image_url and switch your PDP hero/gallery to detail_image_url.Cart Types
interface CartItem {
product_id: string;
variant_id: string;
quantity: number;
addons?: CartAddon[];
custom_fields?: Record<string, string>;
price_variant_id?: string;
}
interface CartAddon {
id: string;
quantity?: number;
}
interface CartAddOptions {
addons?: CartAddon[];
custom_fields?: Record<string, string>;
price_variant_id?: string;
}
interface CartUpdateOptions {
quantity?: number;
addons?: CartAddon[];
custom_fields?: Record<string, string>;
price_variant_id?: string;
}
Checkout Types
interface CheckoutOptions {
autoRedirect?: boolean;
locale?: string;
}
interface CheckoutResult {
success: boolean;
redirectUrl?: string;
message?: string;
}
interface CouponValidation {
valid: boolean;
discount?: number;
discount_type?: 'percentage' | 'fixed';
message?: string;
}
Invoice Types
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
interface Feedback {
id: string;
rating: number;
comment?: string;
created_at: string;
}
Error Types
class ShoppexError extends Error {
readonly code: string;
readonly statusCode?: 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
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<Product[]> {
const response: SDKResponse<Product[]> = 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<string> {
const { data } = await shoppex.getInvoiceStatus(invoiceId);
return data.status;
}