Storefront SDK Methods Reference

Complete reference for the Commerce Engine Storefront SDK (@commercengine/storefront-sdk). This SDK provides comprehensive e-commerce functionality for building storefronts, customer portals, and shopping experiences.

SDK Setup

Installation

npm install @commercengine/storefront-sdk

Basic Configuration

import StorefrontSDK, { Environment } from "@commercengine/storefront-sdk";

const sdk = new StorefrontSDK({
  storeId: "your-store-id",
  environment: Environment.Staging, // or Environment.Production
  apiKey: "your-api-key", // Required for authentication
});

Recommended Configuration with Token Storage

import StorefrontSDK, { BrowserTokenStorage, Environment } from "@commercengine/storefront-sdk";

const sdk = new StorefrontSDK({
  storeId: "your-store-id",
  environment: Environment.Production,
  apiKey: "your-api-key",

  // Automatic token management (recommended)
  tokenStorage: new BrowserTokenStorage("myapp_"),
  
  // Optional: Default headers for all requests
  defaultHeaders: {
    customer_group_id: "01JHS28V83KDWTRBXXJQRTEKA0", // For pricing and promotions
  },
  
  // Optional: Debug mode for development
  debug: true,
  logger: console.log,
  
  // Optional: Token lifecycle callbacks
  onTokensUpdated: (accessToken, refreshToken) => {
    console.log("Tokens updated automatically!");
  },
  onTokensCleared: () => {
    console.log("User logged out");
  },
});

Available Token Storage Options

Choose the storage method that fits your environment:

// Browser localStorage (most common)
import { BrowserTokenStorage } from "@commercengine/storefront-sdk";
tokenStorage: new BrowserTokenStorage("myapp_")

// Cookies (for SSR or cross-tab sync)
import { CookieTokenStorage } from "@commercengine/storefront-sdk";
tokenStorage: new CookieTokenStorage({ prefix: "myapp_" })

// Memory (for server-side or temporary storage)
import { MemoryTokenStorage } from "@commercengine/storefront-sdk";
tokenStorage: new MemoryTokenStorage()

Total Storefront SDK Methods: 89

SDK Clients Overview

Client	SDK Usage	Description	Methods
AuthClient	sdk.auth.*	Login, registration, OTP, password management	25
CartClient	sdk.cart.*	Cart management, coupons, promotions	21
CatalogClient	sdk.catalog.*	Products, categories, search, variants	12
CustomerClient	sdk.customer.*	Customer profiles, addresses, preferences	12
HelpersClient	sdk.helpers.*	Countries, currencies, utilities	3
OrderClient	sdk.order.*	Order creation, tracking, history	9
PaymentsClient	sdk.payments.*	API operations	4
ShippingClient	sdk.shipping.*	Shipping methods, rates, tracking	2
StoreConfigClient	sdk.storeconfig.*	Store configuration and settings	1

AuthClient

SDK Instance: sdk.auth

Methods: 25

SDK Method	HTTP Method	API Path
getAnonymousToken	POST	/auth/anonymous
changePassword	POST	/auth/change-password
forgotPassword	POST	/auth/forgot-password
generateOtp	POST	/auth/generate-otp
loginWithEmail	POST	/auth/login/email
loginWithPassword	POST	/auth/login/password
loginWithPhone	POST	/auth/login/phone
loginWithWhatsApp	POST	/auth/login/whatsapp
logout	POST	/auth/logout
refreshToken	POST	/auth/refresh-token
registerWithEmail	POST	/auth/register/email
registerWithPhone	POST	/auth/register/phone
resetPassword	POST	/auth/reset-password
getUserDetails	GET	/auth/user/{id}
updateUserDetails	PUT	/auth/user/{id}
deactivateUserAccount	PUT	/auth/user/{id}/deactivate
getUserNotificationPreferences	GET	/auth/user/{id}/notification-preferences
updateUserNotificationPreferences	PUT	/auth/user/{id}/notification-preferences
createUserNotificationPreference	POST	/auth/user/{id}/notification-preferences
addProfileImage	POST	/auth/user/{id}/profile-image
updateProfileImage	PUT	/auth/user/{id}/profile-image
deleteProfileImage	DELETE	/auth/user/{id}/profile-image
getProfileImage	GET	/auth/user/{id}/profile-image
checkEmailOrPhoneIsVerified	POST	/auth/verified-email-phone
verifyOtp	POST	/auth/verify-otp

CartClient

SDK Instance: sdk.cart

Methods: 21

SDK Method	HTTP Method	API Path
createCart	POST	/carts
getAvailableCoupons	GET	/carts/available-coupons
getAvailablePromotions	GET	/carts/available-promotions
getUserCart	GET	/carts/users/{user_id}
deleteUserCart	DELETE	/carts/users/{user_id}
getCart	GET	/carts/{id}
deleteCart	DELETE	/carts/{id}
updateCartAddress	POST	/carts/{id}/address
applyCoupon	POST	/carts/{id}/coupon
removeCoupon	DELETE	/carts/{id}/coupon
redeemCreditBalance	POST	/carts/{id}/credit-balance
removeCreditBalance	DELETE	/carts/{id}/credit-balance
evaluateCoupons	GET	/carts/{id}/evaluate-coupons
evaluatePromotions	GET	/carts/{id}/evaluate-promotions
updateFulfillmentPreference	POST	/carts/{id}/fulfillment-preference
addDeleteCartItem	POST	/carts/{id}/items
redeemLoyaltyPoints	POST	/carts/{id}/loyalty-points
removeLoyaltyPoints	DELETE	/carts/{id}/loyalty-points
getWishlist	GET	/wishlist/{user_id}
addToWishlist	POST	/wishlist/{user_id}
removeFromWishlist	DELETE	/wishlist/{user_id}

CatalogClient

SDK Instance: sdk.catalog

Methods: 12

SDK Method	HTTP Method	API Path
listCategories	GET	/catalog/categories
listProducts	GET	/catalog/products
listCrossSellProducts	GET	/catalog/products/cross-sell
searchProducts	POST	/catalog/products/search
listSimilarProducts	GET	/catalog/products/similar
listUpSellProducts	GET	/catalog/products/up-sell
getProductDetail	GET	/catalog/products/{product_id_or_slug}
listProductReviews	GET	/catalog/products/{product_id}/reviews
createProductReview	POST	/catalog/products/{product_id}/reviews
listProductVariants	GET	/catalog/products/{product_id}/variants
getVariantDetail	GET	/catalog/products/{product_id}/variants/{variant_id}
listSkus	GET	/catalog/skus

CustomerClient

SDK Instance: sdk.customer

Methods: 12

SDK Method	HTTP Method	API Path
createCustomer	POST	/customers
listSavedPaymentMethods	GET	/customers/{customer_id}/payment-methods
getCustomer	GET	/customers/{id}
updateCustomer	PUT	/customers/{id}
listAddresses	GET	/customers/{user_id}/addresses
createAddress	POST	/customers/{user_id}/addresses
getAddress	GET	/customers/{user_id}/addresses/{address_id}
updateAddress	PUT	/customers/{user_id}/addresses/{address_id}
deleteAddress	DELETE	/customers/{user_id}/addresses/{address_id}
getLoyaltyDetails	GET	/customers/{user_id}/loyalty
listLoyaltyPointsActivity	GET	/customers/{user_id}/loyalty-points-activity
listCustomerReviews	GET	/customers/{user_id}/reviews

HelpersClient

SDK Instance: sdk.helpers

Methods: 3

SDK Method	HTTP Method	API Path
listCountries	GET	/common/countries
listCountryPincodes	GET	/common/countries/{country_iso_code}/pincodes
listCountryStates	GET	/common/countries/{country_iso_code}/states

OrderClient

SDK Instance: sdk.order

Methods: 9

SDK Method	HTTP Method	API Path
createOrder	POST	/orders
listOrders	GET	/orders
getOrderDetails	GET	/orders/{order_number}
cancelOrder	POST	/orders/{order_number}/cancel
getPaymentStatus	GET	/orders/{order_number}/payment-status
listOrderPayments	GET	/orders/{order_number}/payments
listOrderRefunds	GET	/orders/{order_number}/refunds
retryOrderPayment	POST	/orders/{order_number}/retry-payment
listOrderShipments	GET	/orders/{order_number}/shipments

PaymentsClient

SDK Instance: sdk.payments

Methods: 4

SDK Method	HTTP Method	API Path
authenticateDirectOtp	POST	/payments/authenticate-direct-otp
listPaymentMethods	GET	/payments/payment-methods
resendDirectOtp	POST	/payments/resend-direct-otp
verifyVpa	GET	/payments/verify-vpa

ShippingClient

SDK Instance: sdk.shipping

Methods: 2

SDK Method	HTTP Method	API Path
getFulfillmentOptions	POST	/shipping/fulfillment-options
checkPincodeDeliverability	GET	/shipping/serviceability/{pincode}

StoreConfigClient

SDK Instance: sdk.storeconfig

Methods: 1

SDK Method	HTTP Method	API Path
getStoreConfig	GET	/store/config

---

Auto-generated from SDK source code and OpenAPI specifications