sf-b2c-scapi
Build headless commerce experiences and API integrations with Salesforce Commerce API (SCAPI).
Before Writing Code
Fetch live documentation FIRST:
- Search: "Salesforce Commerce API SCAPI reference 2026"
- Search: "Commerce SDK Node.js documentation"
- WebFetch:
developer.salesforce.com/docs/commerce/commerce-api/references(SCAPI API reference) - WebFetch:
developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html(SLAS auth guide) - WebFetch:
github.com/SalesforceCommerceCloud/commerce-sdk(Commerce SDK repo)
Why: SCAPI is the modern API replacing OCAPI. Endpoints, authentication flows, rate limits, and SDK versions change frequently. Always verify current specs before implementing.
Conceptual Architecture
API Families
| Family | Scope | Examples |
|---|---|---|
| Shopper Products | Product data for storefront | Product details, images, prices, variations |
| Shopper Search | Product discovery | Keyword search, refinements, facets, suggestions |
| Shopper Baskets | Cart operations | Create basket, add/remove items, shipping, payment |
| Shopper Orders | Order lifecycle | Create order from basket, order history, status |
| Shopper Customers | Customer identity | Registration, profile, addresses, payment methods |
| Shopper Promotions | Pricing incentives | Active promotions, promotion details |
| Shopper Gift Certificates | Gift cards | Balance check, redemption |
| Einstein | AI recommendations | Product and search recommendations |
| Pricing / Inventory | Admin data | Price books, multi-location inventory |
SLAS Authentication Overview
SCAPI uses SLAS (Shopper Login and API Access Service) for OAuth 2.0 authentication. Two primary flows exist:
| Flow | Client Type | Use Case |
|---|---|---|
| Authorization Code + PKCE | Public (browser/mobile) | Guest and registered shoppers in frontend apps |
| Client Credentials | Private/confidential (server) | Server-to-server integrations, back-office tools |
- Guest shoppers use PKCE with
hint=guest-- this is NOT client_credentials - Registered users use PKCE with username/password login
- Tokens expire (typically 30 min); implement refresh before expiry
- Configure SLAS in Account Manager: redirect URIs, allowed origins, token lifetime
Session Bridging
When transitioning a guest user to a registered session (login during checkout), SCAPI supports session bridging to preserve the guest basket. The guest token is exchanged for a registered token via the SLAS token endpoint, and the basket is merged server-side. Fetch live docs for the exact merge behavior and conflict resolution rules.
Rate Limiting
| Aspect | Detail |
|---|---|
| Scope | Per client ID, per endpoint |
| Typical range | 1,000 -- 10,000 requests/min (varies by API) |
| Burst | Short burst allowances above sustained rate |
| Headers | X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset |
| On 429 | Exponential backoff; respect Retry-After header |
Pagination
SCAPI uses offset-based pagination with limit and offset parameters. Responses include total count and a next link. Avoid deep pagination on large result sets -- use refinements to narrow results instead.
Commerce SDK
Two SDK packages exist:
| Package | Environment | Notes |
|---|---|---|
commerce-sdk | Node.js only | Server-side integrations |
commerce-sdk-isomorphic | Browser + Node.js | PWA Kit and universal apps |
// Pattern: SDK initialization
// Fetch live docs for current config shape
import { ShopperProducts } from 'commerce-sdk-isomorphic';
const client = new ShopperProducts(config);
// Pattern: Search with refinements
// Fetch live docs for refinement syntax
const results = await searchClient.productSearch({
parameters: { q, limit, offset, refine, sort }
});
Search Refinement Syntax
| Syntax | Meaning |
|---|---|
attribute=value | Exact match |
attribute=(min..max) | Range filter |
attribute=val1|val2 | OR condition |
cgid=category-id | Category refinement |
Best Practices
Authentication
- Use SLAS for all auth; never use OCAPI credentials with SCAPI
- Implement token refresh before expiry
- Use PKCE for all public (browser/mobile) clients
- Store client credentials in environment variables, never in code
SDK and Performance
- Always use the Commerce SDK rather than raw HTTP calls
- Cache product/category responses with appropriate TTLs
- Use ETags for conditional requests (
If-None-Match) - Implement debouncing for search-as-you-type
Error Handling
- Parse structured SCAPI error responses for field-specific messages
- Implement fallbacks for API failures (graceful degradation)
- Log errors with request ID and parameters for debugging
Fetch the SCAPI API reference, Commerce SDK README, and SLAS guide for exact endpoint paths, request/response shapes, and SDK configuration before implementing.