Introduction The Storefront API provides all the functionality needed to build customer-facing shopping experiences. It handles cart management, product browsing, checkout sessions, and customer authentication.
Client Initialization Create a storefront client by providing your store ID and optionally a customer token:
import { createStorefrontClient } from '@paynow-gg/sdk' ; const storefront = createStorefrontClient ( 'your-store-id' , 'customer-token' // Optional: Required for cart and customer-specific operations );
Operation Groups The Storefront API organizes operations into logical groups:
Cart Operations Manage customer shopping carts, add products, and create checkout sessions from carts.
storefront . cart . getCart () storefront . cart . addLine () storefront . cart . clearCart () storefront . cart . createCartCheckout ()
View Cart API documentation → Checkout Operations Create checkout sessions directly without using a cart.
storefront . checkout . createCheckoutSession ()
View Checkout API documentation → Product Operations Browse and retrieve product information.
storefront . products . getStorefrontProducts () storefront . products . getStorefrontProductByIdOrSlug ()
View Products API documentation → Store Operations Retrieve store information, navigation links, and tags.
storefront . store . getStorefrontStore () storefront . navlinks . getStorefrontNavLinks () storefront . tags . getStorefrontTags ()
View Store API documentation → Customer Operations Authenticate customers and manage their data.
storefront . customer . authenticateStorefrontCustomer () storefront . customer . getStorefrontCustomer () storefront . customer . getStorefrontGiftCard ()
Delivery Operations Retrieve customer delivery items.
storefront . delivery . getStorefrontCustomerDeliveryItems ()
Operation Naming Pattern All operations follow a consistent naming pattern:
Operation ID : {Group}_{Method} (e.g., Cart_GetCart)Client Method : storefront.{group}.{method}() (e.g., storefront.cart.getCart())
The SDK automatically converts operation IDs to camelCase method names:
Cart_GetCart → storefront.cart.getCart()Products_GetStorefrontProducts → storefront.products.getStorefrontProducts()Checkout_CreateCheckoutSession → storefront.checkout.createCheckoutSession()
Authentication Storefront operations use customer tokens for authentication:
// Create client with customer token const storefront = createStorefrontClient ( 'store-id' , 'customer-token' ); // Or authenticate to get a customer token const { data } = await storefront . customer . authenticateStorefrontCustomer ({ data: { platform: 'steam' , id: '76561198152492642' } }); const customerToken = data . customer_token ;
IP and Country Headers Many storefront operations accept optional headers for IP address and country code. These are used for:
VAT rate calculation
Regional pricing
Currency conversion
Fraud prevention
await storefront . products . getStorefrontProducts ({ headers: { 'x-paynow-customer-ip' : '203.0.113.42' , 'x-paynow-customer-countrycode' : 'US' } });
If making requests from a customer’s browser, these headers are automatically inferred. They are required when making server-side requests on behalf of customers.
All operations return Axios responses with the following structure:
const response = await storefront . cart . getCart (); // Response object { data : { /* Response data */ }, status : 200 , statusText : 'OK' , headers : { /* Response headers */ }, config : { /* Request config */ } }
Access the response data via the data property:
const cart = response . data ; console . log ( cart . lines ); // Access cart line items
Error Handling Handle API errors using try-catch:
try { const { data } = await storefront . cart . getCart (); console . log ( data ); } catch ( error ) { if ( error . response ) { // API returned an error response const payNowError = error . response . data ; console . error ( payNowError . message ); console . error ( payNowError . code ); } else { // Network or other error console . error ( error . message ); } }
PayNow error responses follow this structure:
interface PayNowError { status : number ; // HTTP status code (e.g., 400) code : string ; // Error code (e.g., 'bad-request') message : string ; // Human-readable error message trace_id ?: string ; // Trace ID for debugging errors ?: ValidationError []; // Validation errors (if applicable) }
Next Steps
Cart API Manage shopping carts and cart checkout sessions
Checkout API Create direct checkout sessions
Products API Browse and retrieve product information
Store API Get store details, navigation, and tags