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.

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.

Create API clients that use createCommerceApiClients.

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.

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.

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.

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

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

The client provides access to all SCAPI endpoints.

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

API errors throw an ApiError with detailed information:

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

Add custom behavior to requests and responses:

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 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:

1. 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.
2. A typed client built with createOpenApiFetchClient and wrapped with the runtime’s createClient helper to expose operation-name methods.
3. 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.

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.

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.

• B2C Commerce API (SCAPI) - Official SCAPI documentation
• Custom APIs - Define your own SCAPI endpoints
• openapi-fetch - The underlying fetch client library
• openapi-typescript - Generate TypeScript types from an OpenAPI schema