Skip to main content

​
Function Signature

function createStorefrontClient(
  storeId: string,
  customerToken?: string,
  options?: CreateAxiosDefaults,
): StorefrontClient

​
Description

Creates and configures a client for interacting with the PayNow Storefront API. The Storefront API is used for customer-facing operations like browsing products, managing carts, and processing checkouts.

​
Parameters

​
storeId
string
required
Your PayNow store identifier. This is used to scope all API requests to your specific store.
​
customerToken
string
Optional customer authentication token. Include this when making authenticated requests on behalf of a specific customer. The token is automatically formatted with the Customer prefix in the Authorization header.When to use:
  • Accessing customer-specific cart data
  • Retrieving customer order history
  • Managing customer profiles
When to omit:
  • Browsing public product catalogs
  • Viewing store information
  • Anonymous cart operations
​
options
CreateAxiosDefaults
Additional Axios configuration options to customize the HTTP client behavior.Common options:
  • timeout: Request timeout in milliseconds
  • headers: Additional HTTP headers to include in all requests
  • baseURL: Override the default API base URL (defaults to https://api.paynow.gg)
  • validateStatus: Custom function to determine if a status code should resolve or reject
See Axios documentation for all available options.

​
Returns

​
StorefrontClient
object
A typed client instance with grouped API operations. Operations are organized by resource type (e.g., cart, checkout, products, store) and accessed using dot notation.Example structure:
{
  cart: {
    get: (config?) => Promise<AxiosResponse<Cart>>,
    update: (config) => Promise<AxiosResponse<Cart>>,
    // ... other cart operations
  },
  checkout: {
    create: (config) => Promise<AxiosResponse<Checkout>>,
    // ... other checkout operations
  },
  products: {
    list: (config?) => Promise<AxiosResponse<Product[]>>,
    // ... other product operations
  },
  store: {
    get: (config?) => Promise<AxiosResponse<Store>>,
    // ... other store operations
  }
}
Each operation returns an Axios response with the typed data in the data property.

​
Usage Examples

​
Basic Client (Unauthenticated)

import { createStorefrontClient } from '@paynow/sdk';

// Create a client for browsing products and public store information
const client = createStorefrontClient('your-store-id');

// Browse products
const products = await client.products.list();
console.log(products.data);

// Get store information
const store = await client.store.get();
console.log(store.data);

​
Authenticated Client

import { createStorefrontClient } from '@paynow/sdk';

// Create a client with customer authentication
const client = createStorefrontClient(
  'your-store-id',
  'customer-auth-token'
);

// Access customer's cart
const cart = await client.cart.get();
console.log(cart.data);

// Add item to cart
const updatedCart = await client.cart.update({
  data: {
    items: [
      { productId: 'prod_123', quantity: 1 }
    ]
  }
});

​
With Custom Options

import { createStorefrontClient } from '@paynow/sdk';

// Create a client with custom configuration
const client = createStorefrontClient(
  'your-store-id',
  'customer-auth-token',
  {
    timeout: 5000, // 5 second timeout
    headers: {
      'X-Custom-Header': 'value'
    }
  }
);

// All requests will use the custom configuration
const products = await client.products.list();

​
Error Handling

import { createStorefrontClient } from '@paynow/sdk';
import { AxiosError } from 'axios';

const client = createStorefrontClient('your-store-id');

try {
  const checkout = await client.checkout.create({
    data: {
      cartId: 'cart_123'
    }
  });
  console.log('Checkout created:', checkout.data);
} catch (error) {
  if (error instanceof AxiosError) {
    console.error('API Error:', error.response?.status);
    console.error('Error details:', error.response?.data);
  } else {
    console.error('Unexpected error:', error);
  }
}

​
Authentication Notes

  • The customerToken parameter is optional for public operations
  • When provided, the token is automatically formatted as Customer <token> in the Authorization header
  • Customer tokens are typically obtained through your authentication flow
  • Unauthenticated requests can still access public resources like products and store information
  • Some operations require authentication and will return a 401 error if the token is missing or invalid

Storefront API Overview

Explore all available Storefront API operations

Authentication Guide

Learn about authentication patterns

Error Handling

Handle errors effectively in your application

Management Client

Create a client for management operations

Build docs developers (and LLMs) love

Get started for freeTalk to us