Sfcc Ocapi Scapi

SFCC OCAPI and Shopper APIs

Overview

Salesforce B2C Commerce provides two API families: the legacy Open Commerce API (OCAPI) using Basic Auth or OAuth and the modern Commerce API (SCAPI/Shopper APIs) using SLAS (Shopper Login and API Access Service) tokens. SCAPI is the recommended approach for headless storefronts, PWA Kit, and third-party integrations. OCAPI remains the primary Data API for server-side admin operations (product import, order management, promotion management). The Composable Storefront (formerly PWA Kit) is built entirely on SCAPI.

When to Use This Skill

• When building a headless B2C storefront using SFCC as the commerce backend
• When implementing the Salesforce PWA Kit (Composable Storefront) with custom API calls
• When integrating a mobile app with SFCC product catalog, cart, and checkout
• When building server-side order management integrations using OCAPI Data API
• When migrating an existing OCAPI integration to the newer SCAPI endpoints
• When implementing SLAS token management for customer authentication flows

Core Instructions

1. Understand the API landscape

Base URL pattern: https://{shortCode}.api.commercecloud.salesforce.com/

2. Authenticate with SLAS (Shopper Login and API Access Service)

   // lib/sfcc-auth.ts
   const SLAS_BASE = `https://${process.env.SFCC_SHORT_CODE}.api.commercecloud.salesforce.com/shopper/auth/v1`;
   const ORG_ID = process.env.SFCC_ORG_ID!; // f_ecom_xxx format
   const CLIENT_ID = process.env.SFCC_SLAS_CLIENT_ID!;

   // Step 1: Get PKCE code challenge for guest token
   function generateCodeChallenge(): { verifier: string; challenge: string } {
     const nodeCrypto = require("crypto");
     const verifier = nodeCrypto.randomBytes(32).toString("hex");
     const hash = nodeCrypto.createHash("sha256").update(verifier).digest("base64url");
     return { verifier, challenge: hash };
   }

   // Get a guest access token
   export async function getGuestToken(): Promise<{ access_token: string; refresh_token: string }> {
     const { verifier, challenge } = generateCodeChallenge();

     // Step 1: Authorize (get auth code)
     const authorizeUrl = new URL(`${SLAS_BASE}/organizations/${ORG_ID}/oauth2/authorize`);
     authorizeUrl.searchParams.set("client_id", CLIENT_ID);
     authorizeUrl.searchParams.set("channel_id", process.env.SFCC_SITE_ID!);
     authorizeUrl.searchParams.set("redirect_uri", process.env.SFCC_SLAS_REDIRECT_URI!);
     authorizeUrl.searchParams.set("response_type", "code");
     authorizeUrl.searchParams.set("code_challenge", challenge);
     authorizeUrl.searchParams.set("hint", "guest");

     // SFCC returns a redirect — extract the code from the Location header
     const authResponse = await fetch(authorizeUrl.toString(), { redirect: "manual" });
     const location = authResponse.headers.get("location") ?? "";
     const code = new URL(location).searchParams.get("code") ?? "";

     // Step 2: Exchange code for token
     const tokenResponse = await fetch(
       `${SLAS_BASE}/organizations/${ORG_ID}/oauth2/token`,
       {
         method: "POST",
         headers: { "Content-Type": "application/x-www-form-urlencoded" },
         body: new URLSearchParams({
           grant_type: "authorization_code_pkce",
           code,
           code_verifier: verifier,
           client_id: CLIENT_ID,
           redirect_uri: process.env.SFCC_SLAS_REDIRECT_URI!,
           channel_id: process.env.SFCC_SITE_ID!,
         }),
       }
     );

     return tokenResponse.json();
   }

   // Refresh an access token
   export async function refreshToken(refreshToken: string) {
     const response = await fetch(`${SLAS_BASE}/organizations/${ORG_ID}/oauth2/token`, {
       method: "POST",
       headers: { "Content-Type": "application/x-www-form-urlencoded" },
       body: new URLSearchParams({
         grant_type: "refresh_token",
         refresh_token: refreshToken,
         client_id: CLIENT_ID,
       }),
     });
     return response.json();
   }

3. Query the product catalog with Shopper Products API

   // lib/sfcc-products.ts
   const API_BASE = `https://${process.env.SFCC_SHORT_CODE}.api.commercecloud.salesforce.com`;
   const ORG_ID = process.env.SFCC_ORG_ID!;
   const SITE_ID = process.env.SFCC_SITE_ID!;

   // Search products
   export async function searchProducts(params: {
     q?: string;
     categoryId?: string;
     start?: number;
     count?: number;
     sortKey?: string;
   }, accessToken: string) {
     const url = new URL(`${API_BASE}/search/shopper-search/v1/organizations/${ORG_ID}/product-search`);
     url.searchParams.set("siteId", SITE_ID);
     if (params.q) url.searchParams.set("q", params.q);
     if (params.categoryId) url.searchParams.set("refine", `cgid=${params.categoryId}`);
     url.searchParams.set("start", (params.start ?? 0).toString());
     url.searchParams.set("count", (params.count ?? 20).toString());
     if (params.sortKey) url.searchParams.set("sort", params.sortKey);
     url.searchParams.set("expand", "images,prices,availability,variations");

     const response = await fetch(url.toString(), {
       headers: { Authorization: `Bearer ${accessToken}` },
     });
     return response.json();
   }

   // Get product by ID
   export async function getProduct(productId: string, accessToken: string) {
     const url = `${API_BASE}/product/shopper-products/v1/organizations/${ORG_ID}/products/${productId}?siteId=${SITE_ID}&expand=images,prices,availability,variations,promotions`;
     const response = await fetch(url, {
       headers: { Authorization: `Bearer ${accessToken}` },
     });
     return response.json();
   }

4. Manage cart and checkout with Shopper Baskets API

   // lib/sfcc-basket.ts

   // Create a basket
   export async function createBasket(accessToken: string) {
     const response = await fetch(
       `${API_BASE}/checkout/shopper-baskets/v1/organizations/${ORG_ID}/baskets?siteId=${SITE_ID}`,
       {
         method: "POST",
         headers: {
           Authorization: `Bearer ${accessToken}`,
           "Content-Type": "application/json",
         },
         body: JSON.stringify({ customerInfo: { email: null } }),
       }
     );
     return response.json(); // { basketId: "xxx", ... }
   }

   // Add item to basket
   export async function addItemToBasket(
     basketId: string,
     productId: string,
     quantity: number,
     accessToken: string
   ) {
     const response = await fetch(
       `${API_BASE}/checkout/shopper-baskets/v1/organizations/${ORG_ID}/baskets/${basketId}/items?siteId=${SITE_ID}`,
       {
         method: "POST",
         headers: {
           Authorization: `Bearer ${accessToken}`,
           "Content-Type": "application/json",
         },
         body: JSON.stringify([{ productId, quantity }]),
       }
     );
     return response.json();
   }

   // Set shipping address
   export async function setShipmentAddress(
     basketId: string,
     shipmentId = "me",
     address: Record<string, string>,
     accessToken: string
   ) {
     const response = await fetch(
       `${API_BASE}/checkout/shopper-baskets/v1/organizations/${ORG_ID}/baskets/${basketId}/shipments/${shipmentId}/shipping-address?siteId=${SITE_ID}`,
       {
         method: "PUT",
         headers: {
           Authorization: `Bearer ${accessToken}`,
           "Content-Type": "application/json",
         },
         body: JSON.stringify(address),
       }
     );
     return response.json();
   }

   // Submit order
   export async function submitOrder(basketId: string, accessToken: string) {
     const response = await fetch(
       `${API_BASE}/checkout/shopper-orders/v1/organizations/${ORG_ID}/orders?siteId=${SITE_ID}`,
       {
         method: "POST",
         headers: {
           Authorization: `Bearer ${accessToken}`,
           "Content-Type": "application/json",
         },
         body: JSON.stringify({ basketId }),
       }
     );
     return response.json(); // { orderNo: "00001234", status: "created" }
   }

5. Use OCAPI Data API for server-side admin operations

OCAPI Data API uses a client credentials OAuth2 token:

   // lib/sfcc-ocapi.ts

   // Get admin token via client credentials
   async function getAdminToken(): Promise<string> {
     const response = await fetch("https://account.demandware.com/dwsso/oauth2/access_token", {
       method: "POST",
       headers: {
         "Content-Type": "application/x-www-form-urlencoded",
         Authorization: `Basic ${Buffer.from(
           `${process.env.SFCC_OCAPI_CLIENT_ID}:${process.env.SFCC_OCAPI_CLIENT_SECRET}`
         ).toString("base64")}`,
       },
       body: new URLSearchParams({ grant_type: "client_credentials" }),
     });
     const { access_token } = await response.json();
     return access_token;
   }

   // Get order via OCAPI Data API
   export async function getOrder(orderNo: string): Promise<Record<string, unknown>> {
     const token = await getAdminToken();
     const instanceUrl = process.env.SFCC_INSTANCE_URL!; // https://xxxx.dx.commercecloud.salesforce.com

     const response = await fetch(
       `${instanceUrl}/s/${process.env.SFCC_SITE_ID}/dw/data/v23_2/orders/${orderNo}`,
       {
         headers: {
           Authorization: `Bearer ${token}`,
           "Content-Type": "application/json",
         },
       }
     );
     return response.json();
   }

   // Update order status
   export async function updateOrderStatus(orderNo: string, status: string): Promise<void> {
     const token = await getAdminToken();
     const instanceUrl = process.env.SFCC_INSTANCE_URL!;

     await fetch(
       `${instanceUrl}/s/${process.env.SFCC_SITE_ID}/dw/data/v23_2/orders/${orderNo}`,
       {
         method: "PATCH",
         headers: {
           Authorization: `Bearer ${token}`,
           "Content-Type": "application/json",
         },
         body: JSON.stringify({ status }),
       }
     );
   }

Examples

Customer login and cart merge (SCAPI)

export async function loginCustomer(
  email: string,
  password: string,
  guestToken: string
): Promise<{ access_token: string; customer_id: string }> {
  // Step 1: Get login token via Trusted Agent SLAS flow
  const response = await fetch(
    `${SLAS_BASE}/organizations/${ORG_ID}/oauth2/login`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
        Authorization: `Bearer ${guestToken}`,
      },
      body: new URLSearchParams({
        type: "credentials",
        username: email,
        password,
        client_id: CLIENT_ID,
      }),
    }
  );

  const { access_token, customer_id } = await response.json();

  // Step 2: Merge guest basket into customer basket
  if (guestBasketId) {
    await fetch(
      `${API_BASE}/checkout/shopper-baskets/v1/organizations/${ORG_ID}/baskets?siteId=${SITE_ID}`,
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${access_token}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ guestBasketId }), // Triggers merge
      }
    );
  }

  return { access_token, customer_id };
}

OCAPI product import via Data API

// Import/update products via OCAPI Data API
export async function upsertProduct(product: {
  id: string;
  name: string;
  longDescription?: string;
  price: number;
}) {
  const token = await getAdminToken();
  const instanceUrl = process.env.SFCC_INSTANCE_URL!;

  const ocapiProduct = {
    id: product.id,
    name: { default: product.name },
    long_description: { default: product.longDescription ?? "" },
    price: product.price,
    classification_category: { id: "electronics" },
  };

  const response = await fetch(
    `${instanceUrl}/s/-/dw/data/v23_2/products/${product.id}`,
    {
      method: "PUT",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(ocapiProduct),
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`OCAPI product upsert failed: ${error.message}`);
  }

  return response.json();
}

Best Practices

• Use SCAPI/Shopper APIs for all new headless projects — OCAPI is in maintenance mode; SCAPI has better rate limits, JWT-based auth, and Salesforce's active investment
• Implement token refresh proactively — SLAS access tokens expire in 30 minutes; refresh in the background before expiry rather than waiting for 401 errors
• Store tokens in `httpOnly` cookies — client-side JavaScript should never access SLAS tokens directly; set cookies server-side and use a server-side proxy for API calls
• Use the Salesforce Commerce SDK (@salesforce/commerce-sdk-react for React, commerce-sdk-isomorphic for Node.js) to get type-safe API clients with automatic token management
• Never expose OCAPI client credentials — Data API credentials have admin-level access; use environment variables and server-side-only code paths
• Use `select` parameter to limit fields — SFCC API responses are large; ?select=(id,name,price_min) dramatically reduces response sizes for list endpoints
• Implement request idempotency for order submission — SFCC baskets can have race conditions; use the Idempotency-Key header when submitting orders

Common Pitfalls

Related Skills

• @sfcc-cartridge-development
• @sfcc-business-manager
• @headless-commerce-architecture
• @oauth-implementation
• @shopify-storefront-api

Order Fulfillment Integration

Problem/Feature Description

A home goods retailer uses Salesforce B2C Commerce Cloud as their commerce platform and has recently contracted a third-party fulfilment warehouse to handle physical order processing. The warehouse system needs to pull new orders from SFCC every few minutes and update order statuses (e.g. "shipped", "cancelled") as fulfilment progresses. This is a server-to-server integration with no customer-facing UI — it runs as a Node.js background service on the retailer's internal infrastructure.

The engineering team has had two problems in production: duplicate orders were created during a brief network outage when the submission script retried without safeguards, and the integration was briefly broken after a security audit forced credential rotation because the client secret had been committed to source control. They want the new implementation to be production-safe from day one.

Write a TypeScript integration module that the fulfillment service can use to interact with SFCC orders. Also include a FULFILLMENT_SETUP.md that describes what permissions the SFCC OCAPI client ID needs and what environment variables must be configured.

Output Specification

Produce the following files:

• lib/fulfillment.ts — Integration module with at minimum:
• getPendingOrders() — retrieve orders in "new" or "open" status ready for fulfilment
• updateOrderStatus(orderNo, status) — update the fulfilment status of an order
• submitOrder(basketId) — submit a basket as an order, protected against duplicate submission
• lib/sfcc-admin-auth.ts — Admin authentication helper for obtaining and caching the admin access token
• FULFILLMENT_SETUP.md — Setup guide covering required OCAPI client permissions, environment variable names, and any configuration notes

Use TypeScript. Assume the following environment variables will be configured in the deployment environment (do not hardcode their values):

• SFCC_OCAPI_CLIENT_ID
• SFCC_OCAPI_CLIENT_SECRET
• SFCC_INSTANCE_URL — the SFCC instance hostname (e.g. https://xxxx.dx.commercecloud.salesforce.com)
• SFCC_SITE_ID

Mobile Commerce Catalog API Layer

Problem/Feature Description

A sporting goods retailer is building a React Native mobile app backed by Salesforce B2C Commerce Cloud. The app's catalog browsing feature needs to support hundreds of concurrent users during peak sale events without hitting API rate limits or degrading response times. The previous integration built by an external agency made direct calls to legacy SFCC APIs and suffered from slow response times due to large payloads and repeated identical requests from different users. The team has been told to modernize the integration.

The new implementation should serve product search results and individual product detail pages to the mobile app via a Node.js BFF (Backend for Frontend) service. The team wants the implementation to be type-safe, handle traffic spikes gracefully, and keep API response payloads small to improve mobile performance.

Write a Node.js/TypeScript BFF service module with the catalog functions needed for the mobile app. Also produce a short CATALOG_DESIGN.md that describes the resilience and performance strategies you chose and why.

Output Specification

Produce the following files:

• lib/catalog.ts — BFF catalog module with at minimum:
• searchProducts(query, options) — search products by keyword and/or category
• getProductDetail(productId) — fetch full product details

Both functions should handle authentication internally (the caller does not need to manage tokens).

• lib/sfcc-auth.ts — SLAS authentication helper (guest token acquisition and refresh)
• CATALOG_DESIGN.md — A short document describing the resilience patterns and payload optimisation strategy used

Use TypeScript. Assume the following environment variables are available at runtime (do not hardcode their values):

• SFCC_SHORT_CODE
• SFCC_ORG_ID
• SFCC_SITE_ID
• SFCC_SLAS_CLIENT_ID
• SFCC_SLAS_REDIRECT_URI

Headless Storefront Authentication Service

Problem/Feature Description

A fashion retailer is launching a new headless storefront built on Salesforce B2C Commerce Cloud. The team has an existing Salesforce Commerce Cloud org and needs a backend authentication service that handles the full customer journey: anonymous browsing, customer login, and persistent shopping carts.

The current prototype allows customers to browse products and add items to a cart, but loses the cart contents when a guest user logs in. The product team wants a seamless "login and keep my cart" experience. Additionally, the security team has flagged that the current prototype stores session tokens in localStorage, which is a vulnerability — they want tokens stored securely so they are not accessible to third-party JavaScript on the page. The engineering team also noticed that customers are intermittently logged out mid-session and suspects the authentication tokens are expiring without being refreshed.

Your task is to implement a TypeScript authentication module (lib/sfcc-auth.ts) and a Next.js API route (pages/api/auth/) that implements the complete authentication layer described above. Include a brief AUTH_DESIGN.md documenting the security choices made.

Output Specification

Produce the following files:

• lib/sfcc-auth.ts — Core authentication functions covering:
• Guest session initiation
• Token refresh
• Customer login with cart continuity
• pages/api/auth/session.ts — Next.js API route that handles session management and authenticated commerce requests on behalf of the client
• AUTH_DESIGN.md — A short document (bullet points are fine) explaining the token storage strategy and token lifecycle management approach

Use TypeScript. Assume the following environment variables are available at runtime (do not hardcode their values):

• SFCC_SHORT_CODE — the Commerce Cloud short code
• SFCC_ORG_ID — the org ID
• SFCC_SITE_ID — the site/channel ID
• SFCC_SLAS_CLIENT_ID — the SLAS public client ID
• SFCC_SLAS_REDIRECT_URI — the registered redirect URI