Skip to main content

Quick Start

Why you need this guide ⚡​

Every storefront request to Elastic Path Commerce Cloud must carry an access-token in the Authorization header. For browser code you nearly always use an implicit shopper token – a scoped, read-mostly token that keeps your client_secret out of the client bundle. This guide shows the shortest path: configure the TypeScript Shopper SDK and let it handle authentication for you.

note

Account tokens are also available for authenticated user scenarios, but are not covered in this quickstart. See the Token Management guide for detailed information about account tokens and other authentication methods.

Prerequisites​

WhatValue
API base URLhttps://useast.api.elasticpath.com
Application client-ID<YOUR_CLIENT_ID>
Packagenpm i @epcc-sdk/sdks-shopper

1 · Configure the SDK with built-in authentication​

The new SDK handles authentication automatically. Choose one of these approaches:

import { configureClient } from "@epcc-sdk/sdks-shopper";

// Configure once in your app initialization
export const client = configureClient(
  { 
    baseUrl: "https://useast.api.elasticpath.com" 
  },
  {
    clientId: process.env.CLIENT_ID,
    storage: "localStorage" // or "cookie" or custom adapter
  }
);

Option B: Standalone client instance​

import { createShopperClient } from "@epcc-sdk/sdks-shopper";

// Create a client instance
const { client, auth } = createShopperClient(
  { 
    baseUrl: "https://useast.api.elasticpath.com" 
  },
  {
    clientId: process.env.CLIENT_ID,
    storage: "localStorage"
  }
);

// Export for use in your app
export { client };
info

The SDK automatically:

  • Fetches an implicit token on first API call
  • Stores the token in your chosen storage (default key: _store_ep_credentials)
  • Refreshes tokens 60 seconds before expiry
  • Adds the Authorization header to all requests

2 · Use the SDK - authentication happens automatically​

import { getByContextAllProducts } from "@epcc-sdk/sdks-shopper";

// No need to manually handle tokens!
const response = await getByContextAllProducts({
  query: {
    "page[limit]": 10
  }
});

console.log(`Found ${response.data?.data?.length} products`);

3 · Storage options​

The SDK supports different storage mechanisms:

// localStorage (default for SPAs)
configureClient(apiConfig, {
  clientId: process.env.CLIENT_ID,
  storage: "localStorage"
});

// Cookies (better for SSR)
configureClient(apiConfig, {
  clientId: process.env.CLIENT_ID,
  storage: "cookie",
  cookieOptions: {
    domain: ".yourdomain.com",
    secure: true,
    sameSite: "lax"
  }
});

// Custom storage adapter
configureClient(apiConfig, {
  clientId: process.env.CLIENT_ID,
  storage: {
    get: async (key) => {
      // Your custom storage logic
      return await customStore.get(key);
    },
    set: async (key, value) => {
      await customStore.set(key, value);
    },
    remove: async (key) => {
      await customStore.delete(key);
    }
  }
});

4 · Manual token handling (if needed)​

If you need direct control over authentication:

import { createShopperClient } from "@epcc-sdk/sdks-shopper";

const { client, auth } = createShopperClient(
  { baseUrl: "https://useast.api.elasticpath.com" },
  { clientId: process.env.CLIENT_ID }
);

// Get token manually
const token = await auth.getValidAccessToken();
console.log("Token:", token);

// Get current token without triggering refresh
const snapshot = await auth.getSnapshot();
console.log("Current token:", snapshot?.access_token);

// Force token refresh
const newToken = await auth.refresh();
console.log("Refreshed token:", newToken);

// Clear authentication
await auth.clear();
tip

For complete working implementations, check our Composable Frontend examples repository which includes ready-to-use patterns for:

Next steps​