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.
1---2name: sf-b2c-scapi3description: Build with Salesforce Commerce API (SCAPI) — Shopper APIs (Products, Search, Baskets, Orders, Customers), SLAS authentication, Commerce SDK for Node.js, rate limiting, pagination, and headless commerce patterns. This is the primary B2C API. Use when building headless storefronts or API integrations.4---56# sf-b2c-scapi78Build headless commerce experiences and API integrations with Salesforce Commerce API (SCAPI).910## Before Writing Code1112**Fetch live documentation FIRST:**13- Search: "Salesforce Commerce API SCAPI reference 2026"14- Search: "Commerce SDK Node.js documentation"15- WebFetch: `developer.salesforce.com/docs/commerce/commerce-api/references` (SCAPI API reference)16- WebFetch: `developer.salesforce.com/docs/commerce/commerce-api/guide/slas.html` (SLAS auth guide)17- WebFetch: `github.com/SalesforceCommerceCloud/commerce-sdk` (Commerce SDK repo)1819**Why:** SCAPI is the modern API replacing OCAPI. Endpoints, authentication flows, rate limits, and SDK versions change frequently. Always verify current specs before implementing.2021## Conceptual Architecture2223### API Families2425| Family | Scope | Examples |26|--------|-------|---------|27| **Shopper Products** | Product data for storefront | Product details, images, prices, variations |28| **Shopper Search** | Product discovery | Keyword search, refinements, facets, suggestions |29| **Shopper Baskets** | Cart operations | Create basket, add/remove items, shipping, payment |30| **Shopper Orders** | Order lifecycle | Create order from basket, order history, status |31| **Shopper Customers** | Customer identity | Registration, profile, addresses, payment methods |32| **Shopper Promotions** | Pricing incentives | Active promotions, promotion details |33| **Shopper Gift Certificates** | Gift cards | Balance check, redemption |34| **Einstein** | AI recommendations | Product and search recommendations |35| **Pricing / Inventory** | Admin data | Price books, multi-location inventory |3637### SLAS Authentication Overview3839SCAPI uses SLAS (Shopper Login and API Access Service) for OAuth 2.0 authentication. Two primary flows exist:4041| Flow | Client Type | Use Case |42|------|------------|----------|43| **Authorization Code + PKCE** | Public (browser/mobile) | Guest and registered shoppers in frontend apps |44| **Client Credentials** | Private/confidential (server) | Server-to-server integrations, back-office tools |4546- Guest shoppers use PKCE with `hint=guest` -- this is NOT client_credentials47- Registered users use PKCE with username/password login48- Tokens expire (typically 30 min); implement refresh before expiry49- Configure SLAS in Account Manager: redirect URIs, allowed origins, token lifetime5051### Session Bridging5253When 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.5455### Rate Limiting5657| Aspect | Detail |58|--------|--------|59| Scope | Per client ID, per endpoint |60| Typical range | 1,000 -- 10,000 requests/min (varies by API) |61| Burst | Short burst allowances above sustained rate |62| Headers | `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` |63| On 429 | Exponential backoff; respect `Retry-After` header |6465### Pagination6667SCAPI 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.6869### Commerce SDK7071Two SDK packages exist:7273| Package | Environment | Notes |74|---------|------------|-------|75| `commerce-sdk` | Node.js only | Server-side integrations |76| `commerce-sdk-isomorphic` | Browser + Node.js | PWA Kit and universal apps |7778```javascript79// Pattern: SDK initialization80// Fetch live docs for current config shape81import { ShopperProducts } from 'commerce-sdk-isomorphic';82const client = new ShopperProducts(config);83```8485```javascript86// Pattern: Search with refinements87// Fetch live docs for refinement syntax88const results = await searchClient.productSearch({89 parameters: { q, limit, offset, refine, sort }90});91```9293### Search Refinement Syntax9495| Syntax | Meaning |96|--------|---------|97| `attribute=value` | Exact match |98| `attribute=(min..max)` | Range filter |99| `attribute=val1\|val2` | OR condition |100| `cgid=category-id` | Category refinement |101102## Best Practices103104### Authentication105- Use SLAS for all auth; never use OCAPI credentials with SCAPI106- Implement token refresh before expiry107- Use PKCE for all public (browser/mobile) clients108- Store client credentials in environment variables, never in code109110### SDK and Performance111- Always use the Commerce SDK rather than raw HTTP calls112- Cache product/category responses with appropriate TTLs113- Use ETags for conditional requests (`If-None-Match`)114- Implement debouncing for search-as-you-type115116### Error Handling117- Parse structured SCAPI error responses for field-specific messages118- Implement fallbacks for API failures (graceful degradation)119- Log errors with request ID and parameters for debugging120121Fetch the SCAPI API reference, Commerce SDK README, and SLAS guide for exact endpoint paths, request/response shapes, and SDK configuration before implementing.
OrcaQubits