Client Overview - Commerce Engine Docs

The Commerce Engine TypeScript SDK uses a public/session split architecture. Every API domain has a dedicated, type-safe client with automatic token management.

Public vs Session

import { createStorefront } from "@commercengine/storefront";

const storefront = createStorefront({ /* config */ });

// Public accessor — API-key-backed, no session needed
const publicSdk = storefront.public();
publicSdk.catalog.*   // Products, categories, search
publicSdk.store.*     // Store configuration

// Session accessor — live user session (anonymous or logged-in)
const sdk = storefront.session();
sdk.auth.*            // Authentication & user management
sdk.catalog.*         // Products + reviews (write)
sdk.cart.*            // Cart, wishlist, fulfillment, coupons
sdk.customer.*        // Addresses, loyalty, saved payments
sdk.order.*           // Order creation, tracking, history
sdk.payments.*        // Payment operations
sdk.helpers.*         // Countries, currencies, utilities

Use storefront.public() for anything that doesn’t require a user session (browsing products, fetching store config). Use storefront.session() for user-scoped operations (auth, cart, orders).

Available Clients

CatalogClient

Available on both accessors. The public accessor covers read operations; the session accessor adds write operations like submitting reviews. Implements: Catalog API endpoints
Storefront Guide: Catalog Management

const { data, error } = await storefront.public().catalog.listProducts({
  limit: 20,
  category_id: "cat_123"
});

if (data) {
  data.products.forEach(product => {
    console.log(product.name, product.selling_price);
  });
}

AuthClient

Accessor: Session only
Implements: Authentication API endpoints
Storefront Guide: Authentication Best Practices

const sdk = storefront.session();
const { data, error } = await sdk.auth.loginWithEmail({
  email: "user@example.com",
  register_if_not_exists: true
});

if (data) {
  console.log("OTP Token:", data.otp_token);
}

CartClient

Accessor: Session only
Implements: Cart API endpoints
Storefront Guide: Cart Management

const sdk = storefront.session();
const { data, error } = await sdk.cart.createCart({
  items: [{ product_id: "prod_123", variant_id: null, quantity: 1 }]
});

if (data) {
  console.log("Total:", data.cart.grand_total);
}

CustomerClient

Accessor: Session only
Implements: Customer API endpoints
Storefront Guide: Account Management

OrderClient

Accessor: Session only
Implements: Order API endpoints

HelpersClient

Accessor: Session only
Implements: Common API endpoints

StoreClient

Accessor: Public only
Implements: Store configuration endpoints

SDK vs Direct API Calls

With SDK
Direct API Calls

// Automatic token management, type safety, error handling
const { data, error } = await storefront.public().catalog.listProducts({
  limit: 20,
  category_id: "electronics"
});

if (data) {
  data.products.forEach(product => {
    console.log(product.name); // ✅ Type-safe
  });
} else if (error) {
  console.error(error.message);
}

// Manual token management, no type safety
const response = await fetch('/catalog/products?limit=20&category_id=electronics', {
  headers: {
    'Authorization': `Bearer ${await getValidToken()}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json(); // ❌ No type safety
if (response.ok) {
  data.forEach((product: any) => { // ❌ Any type
    console.log(product.name);
  });
}

Cross-References

Complete API Documentation: API Reference with live playground
Business Logic & Patterns: Storefront Guides for e-commerce workflows
Error Handling: Error Handling Guide for error codes and recovery patterns
Type Safety: Type Safety Guide for IntelliSense and generated types

​Public vs Session

​Available Clients

​CatalogClient

​AuthClient

​CartClient

​CustomerClient

​OrderClient

​HelpersClient

​StoreClient

​SDK vs Direct API Calls

​Cross-References