Salesforce B2C Commerce API (SCAPI) Client

Storefront Next includes a type-safe API client for calling Salesforce B2C Commerce Shopper APIs, including custom APIs, from your storefront. This client provides full TypeScript support with autocomplete, type checking, and semantic operation names.

What Is SCAPI?

The B2C Commerce API (SCAPI) is a collection of RESTful APIs for interacting with B2C Commerce instances. Also known as Salesforce Commerce API or simply Commerce API, it provides endpoints for products, search, baskets, customers, orders, and so on. Create custom APIs to modify the built-in SCAPI endpoints. For example, add filters or modify responses before they get sent back to the calling application. See B2C Commerce API (SCAPI) and Custom APIs.

The SCAPI client in @salesforce/storefront-next-runtime/scapi wraps these APIs with:

Minimal bundle size: Built on openapi-fetch, a lightweight fetch client with near-zero runtime overhead.
Type-safe operations: Full TypeScript inference from OpenAPI specifications.
Semantic method names: Call getProduct() instead of GET /products/{id}.
Automatic parameter injection: Common parameters like organizationId and siteId are handled for you.
Built-in authentication helpers: Guest login, registered login, social login, passwordless login, token refresh, and password reset.

Creating API Clients

Create API clients that use createCommerceApiClients.

1import { createCommerceApiClients } from "@salesforce/storefront-next-runtime/scapi";
2
3const clients = createCommerceApiClients({
4  baseUrl: "https://shortcode.api.commercecloud.salesforce.com",
5  organizationId: "f_ecom_xxx",
6  siteId: "RefArch",
7  clientId: "your-slas-client-id",
8  redirectUri: "https://yoursite.com/callback",
9  locale: "en-US", // Optional
10  clientSecret: process.env.COMMERCE_API_SLAS_SECRET, // Optional, for private SLAS
11});

Configuration Options

Parameter	Required	Description
`baseUrl`	Yes	Commerce API base URL
`organizationId`	Yes	Your organization ID (automatically added to path parameters)
`siteId`	Yes	Your site ID (automatically added to query parameters)
`clientId`	Yes	Shopper Login and Session API (SLAS) client ID
`redirectUri`	Yes	OAuth redirect URI
`locale`	No	Locale for requests (for example, `en-US`)
`clientSecret`	No	SLAS client secret. See Public vs Private SLAS Client.

Public vs Private SLAS Client

The clientSecret parameter determines which SLAS authentication flow the client uses.

Public client (no secret): When clientSecret is omitted, the auth helpers use the public client flow with Proof Key for Code Exchange (PKCE). This behavior is suitable for client-side apps where the secret can’t be kept secure.
Private client (with secret): When clientSecret is provided, the auth helpers use the private client flow. This behavior enables extra features, such as passwordless login, and is suitable for server-side apps where the secret can be kept secure.

Authentication

Before making API calls, you must get an access token. The client includes an auth namespace with helper functions for SLAS shopper login and session API operations.

These authentication helpers are intentionally stateless—they don’t store tokens, session data, or any intermediate state internally. Each function call is independent, giving you full control over how and where you store credentials. This design ensures compatibility with server-side rendering, avoids shared state issues across requests, and lets you choose your preferred storage strategy, such as cookies, session storage, database, and so on.

Guest Login

1const tokens = await clients.auth.loginAsGuest();
2// Returns: { access_token, refresh_token, usid, ... }

Registered User Login

1const tokens = await clients.auth.loginWithCredentials({
2  username: "user@example.com",
3  password: "password123",
4});

Token Refresh

1const newTokens = await clients.auth.refreshToken({
2  refreshToken: storedRefreshToken,
3});

Logout

1await clients.auth.logout({
2  accessToken: currentAccessToken,
3  refreshToken: currentRefreshToken,
4});

Social Login

1// Step 1: Get authorization URL
2const { url, codeVerifier } = await clients.auth.social.getAuthorizationUrl({
3  hint: "google", // or 'facebook', 'apple', etc.
4});
5
6// Store codeVerifier securely, then redirect user to url
7
8// Step 2: Exchange code (after user returns)
9const tokens = await clients.auth.social.exchangeCode({
10  code: authorizationCode,
11  codeVerifier: storedCodeVerifier,
12  redirectUri: "https://yoursite.com/callback",
13});

Adding the Access Token to Requests

After you have an access token, add it to API requests by using middleware. Note that SLAS authentication endpoints handle their own authorization and must be skipped.

1import { SLAS_AUTH_ENDPOINTS } from "@salesforce/storefront-next-runtime/scapi";
2
3clients.use({
4  onRequest({ request }) {
5    // Skip auth header for SLAS endpoints (they handle their own auth)
6    const url = new URL(request.url);
7    const isSlasAuthEndpoint = SLAS_AUTH_ENDPOINTS.some((path) => url.pathname.includes(path));
8    if (isSlasAuthEndpoint) {
9      return request;
10    }
11
12    request.headers.set("Authorization", `Bearer ${accessToken}`);
13    return request;
14  },
15});

Fetching Data

The client automatically includes organizationId and siteId in all requests, so you only provide operation-specific parameters.

Fetching a Product

1const { data: product } = await clients.shopperProducts.getProduct({
2  params: {
3    path: { id: "product-123" },
4    query: {
5      expand: ["availability", "prices", "variations", "images"],
6      allImages: true,
7    },
8  },
9});

Search Products

1const { data: searchResults } = await clients.shopperSearch.productSearch({
2  params: {
3    query: {
4      q: "shoes",
5      limit: 24,
6      offset: 0,
7      sort: "best-matches",
8      expand: ["prices", "images", "variations"],
9    },
10  },
11});

Fetching Categories

1const { data: category } = await clients.shopperProducts.getCategory({
2  params: {
3    path: { id: "mens-clothing" },
4    query: { levels: 2 },
5  },
6});

Mutations

Use the appropriate client method to perform mutations like adding items to a basket or updating customer information.

Adding an Item to Basket

1const { data: updatedBasket } = await clients.shopperBasketsV2.addItemToBasket({
2  params: {
3    path: { basketId: "basket-123" },
4  },
5  body: [
6    {
7      productId: "product-456",
8      quantity: 2,
9    },
10  ],
11});

Updating a Basket Item

1const { data: updatedBasket } = await clients.shopperBasketsV2.updateItemInBasket({
2  params: {
3    path: {
4      basketId: "basket-123",
5      itemId: "item-789",
6    },
7  },
8  body: {
9    quantity: 3,
10  },
11});

Available API Clients

The client provides access to all SCAPI endpoints.

Client	Description
`shopperAvailability`	Product availability and inventory
`shopperProducts`	Products, categories, and catalog data
`shopperSearch`	Product search and suggestions
`shopperBasketsV1`	Basket operations (legacy)
`shopperBasketsV2`	Basket operations (current)
`shopperCustomers`	Customer accounts and profiles
`shopperOrders`	Order history and details
`shopperLogin`	SLAS authentication
`shopperPromotions`	Promotions and campaigns
`shopperContext`	Shopper session context
`shopperStores`	Store locator
`shopperExperience`	Page Designer content
`shopperGiftCertificates`	Gift certificate operations
`shopperSeo`	SEO metadata
`shopperConsents`	Customer consent management
`auth`	Authentication helpers. See Authentication.

TypeScript Types

The client exports TypeScript types for all API schemas and operations.

1import type { ShopperProducts, ShopperSearch } from "@salesforce/storefront-next-runtime/scapi";
2
3// Use schema types for data
4type Product = ShopperProducts.schemas["Product"];
5type Category = ShopperProducts.schemas["Category"];
6type SearchResult = ShopperSearch.schemas["ProductSearchResult"];
7
8// Use operation types for parameters
9type SearchParams = ShopperSearch.operations["productSearch"]["parameters"]["query"];

Error Handling

API errors throw an ApiError with detailed information:

1import { ApiError } from "@salesforce/storefront-next-runtime/scapi";
2
3try {
4  const { data } = await clients.shopperProducts.getProduct(options);
5} catch (error) {
6  if (error instanceof ApiError) {
7    console.error("Status:", error.status); // 404
8    console.error("Message:", error.body.detail); // "Product not found"
9    console.error("URL:", error.url); // Request URL
10    console.error("Method:", error.method); // "GET"
11  }
12}

ApiError Properties

Property	Type	Description
`status`	`number`	HTTP status code
`statusText`	`string`	HTTP status message
`body`	`ErrorDetail`	Parsed error response
`rawBody`	`string`	Raw response text
`headers`	`Headers`	Response headers
`url`	`string`	Request URL
`method`	`string`	HTTP method

Response Format

All operations return both the parsed data and the raw response.

1const { data, response } = await clients.shopperProducts.getProduct(options);
2
3// Typed data from the API
4console.log(data.name);
5console.log(data.price);
6
7// Raw response for headers, status, etc.
8console.log(response.headers.get("etag"));
9console.log(response.status);

Middleware

Add custom behavior to requests and responses:

1import type { Middleware } from "@salesforce/storefront-next-runtime/scapi";
2
3const loggingMiddleware: Middleware = {
4  onRequest({ request }) {
5    console.log(`[API] ${request.method} ${request.url}`);
6    return request;
7  },
8  onResponse({ response }) {
9    console.log(`[API] ${response.status}`);
10    return response;
11  },
12};
13
14// Add to all clients
15clients.use(loggingMiddleware);
16
17// Or add to a specific client
18clients.shopperProducts.use(loggingMiddleware);

Custom APIs

Custom APIs let you extend SCAPI with your own endpoints. Storefront Next supports two ways to call a custom API from your storefront, and both reuse the same authentication and middleware patterns as the built-in shopper clients.

Generate a Typed Client (Recommended)

Generate a fully typed client from your custom API’s OpenAPI schema. You get autocomplete, parameter validation, and operation-name calls like loyaltyClient.getLoyaltyInfo() instead of hand-rolled paths.

Storefront Next’s template app ships a sfnext scapi CLI that takes an OpenAPI 3 schema and generates the type definitions and operation map for you, then registers the client alongside the built-in shopper clients. See the template’s SCAPI guide for the project-level workflow.

An external project follows the same pattern with three components:

Types and operation map generated from the OpenAPI schema. The types are produced with openapi-typescript; the operation map records each operation’s HTTP method and path so the client can dispatch by operationId.
A typed client built with createOpenApiFetchClient and wrapped with the runtime’s createClient helper to expose operation-name methods.
Auth middleware registered with .use() — the same registration pattern shown in Adding the Access Token to Requests earlier in this guide.

Declare the operation map as const so its m / b / s values stay literal — the proxy uses those literals to type each operation method’s parameters and return value.

1// ./generated/loyalty-info.operations.ts (generated alongside the types)
2export const BASE_PATH = "/organizations/{organizationId}" as const;
3export const operations = {
4  getLoyaltyInfo: { m: "GET" as const, b: BASE_PATH, s: "/customers" },
5} as const;

1// loyalty-client.ts
2import {
3  createOpenApiFetchClient,
4  createClient,
5} from "@salesforce/storefront-next-runtime/scapi";
6import type { paths } from "./generated/loyalty-info";
7import { operations } from "./generated/loyalty-info.operations";
8
9const base = createOpenApiFetchClient<paths>({
10  // Stop before /organizations — createClient appends the operation map's
11  // base path, which already includes /organizations/{organizationId}.
12  baseUrl: "https://shortcode.api.commercecloud.salesforce.com/custom/loyalty-info/v1",
13});
14
15const loyaltyClient = createClient(base, operations, {
16  organizationId: "f_ecom_xxx",
17  siteId: "RefArch",
18});
19
20// Register an auth middleware the same way the built-in clients do — see
21// [Adding the Access Token to Requests](#adding-the-access-token-to-requests).
22loyaltyClient.use(authMiddleware);
23
24const { data } = await loyaltyClient.getLoyaltyInfo({
25  params: { query: { c_customer_id: "customer1" } },
26});
27// GET https://shortcode.api.commercecloud.salesforce.com/custom/loyalty-info/v1
28//     /organizations/f_ecom_xxx/customers?siteId=RefArch&c_customer_id=customer1

Call with fetch Directly

For one-off calls, or projects without a codegen step, call the endpoint directly with fetch. Pull accessToken, organizationId, siteId, and any other dynamic values from the same auth/session context the typed clients use, and let the URL API encode user-supplied query values for you.

1const url = new URL(
2  `https://shortcode.api.commercecloud.salesforce.com/custom/loyalty-info/v1/organizations/${organizationId}/customers`,
3);
4url.searchParams.set("c_customer_id", customerId);
5url.searchParams.set("siteId", siteId);
6
7const response = await fetch(url, {
8  headers: { Authorization: `Bearer ${accessToken}` },
9});
10const data = await response.json();

The native-fetch path skips the typed-client features above (TypeScript types, automatic organizationId/siteId injection, ApiError wrapping) — prefer the generated client for any custom API you call from more than one place.