orcaqubits/sf-b2c-scapi

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.