Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 28 ยท APIs and Headless

OCAPI and SCAPI

Understand the HTTP APIs of Salesforce B2C Commerce: OCAPI Shop and Data APIs, SCAPI, SLAS tokens, client IDs and permissions, rate limits and a working token-flow model.

Everything a storefront does can also be done over HTTP. A mobile app adds to a basket, a back-office tool updates prices, a headless site renders product pages from JSON. Commerce Cloud exposes two families of APIs for this: the older OCAPI (Open Commerce API) and the newer SCAPI (Salesforce Commerce API). Both are still in use, and a real project often has both side by side.

This lesson explains what each family offers, how authentication works (especially SLAS, the shopper login service), how permissions are granted to a client, and how to behave under rate limits. The concrete requests below are read-only because they need a real instance; the stand-ins at the end model the token lifecycle you must handle in any client.

URLs, versions and endpoint lists change over time. Treat the shapes below as illustrations and take exact paths, versions and limits from the current official documentation and from your instance's configuration.

Two audiences, two APIs

Both families separate APIs by who is calling:

Kind Caller Examples
Shop / Shopper A customer (or an app acting for one) Search products, read a product, manage a basket, check out, log in
Data / Admin A trusted back-office system Import prices, read and update orders, manage catalog data, jobs

Shopper APIs are public-facing and typically cacheable. Data (OCAPI) and Admin (SCAPI) APIs are protected, run with a technical client, and must never be called from a browser.

OCAPI at a glance

OCAPI lives on the instance's own hostname, per site, with a version in the path:

HTTP
GET https://dev01-example.demandware.net/s/RefArch/dw/shop/v24_5/products/25686544?client_id=1234abcd-0000-0000-0000-abcdef012345
  • /s/RefArch/ selects the site. The Shop API works within a site; the Data API (/dw/data/v.../) works at organization or site level.
  • client_id identifies your application. For Shop calls it is enough for public data; shopper-specific calls add an Authorization: Bearer <JWT> header.
  • Customers get a token from the Shop API's customer auth resource, and the Data API uses an OAuth token that an API client requests from Account Manager.

Who may call what: OCAPI settings

OCAPI does not let any client call any resource. A JSON document in Business Manager (Administration > Site Development > Open Commerce API Settings) lists, per client ID, the allowed resources and methods:

JSON
{
  "_v": "24.5",
  "clients": [
    {
      "client_id": "1234abcd-0000-0000-0000-abcdef012345",
      "resources": [
        { "resource_id": "/products/*", "methods": ["get"], "read_attributes": "(**)" },
        { "resource_id": "/baskets", "methods": ["post"], "read_attributes": "(**)", "write_attributes": "(**)" }
      ]
    }
  ]
}

A call to a resource that is not listed is rejected. Grant the minimum: only the resources and methods the app really needs, and narrow read_attributes/write_attributes where you can. There are separate settings documents for the Shop and Data APIs, and for the whole organization or a single site.

SCAPI at a glance

SCAPI is served from a shared, scalable API gateway rather than the instance itself, which is part of why it handles traffic spikes better and why Salesforce is steering new work toward it. Its URL carries your short code and your organization ID, and the site becomes a query parameter:

HTTP
GET https://kv7kzm78.api.commercecloud.salesforce.com/product/shopper-products/v1/organizations/f_ecom_zzxx_001/products/25686544?siteId=RefArch
Authorization: Bearer <SLAS access token>
  • The first label (kv7kzm78) is the tenant's short code.
  • f_ecom_zzxx_001 is the organization ID: f_ecom_ followed by the realm and instance.
  • The path names the API family (product/shopper-products) and its version (v1).
  • Shopper APIs include products, search, baskets, orders, customers, promotions, gift certificates and more; Admin APIs cover back-office tasks.

Because SCAPI is a different system, some things differ from OCAPI: the authorization model is built around SLAS tokens, endpoint names are grouped by API, and customization uses SCAPI Custom APIs and hooks (see Hooks and Extension Mechanisms) rather than just the old OCAPI hook list. Not every OCAPI feature exists in SCAPI and vice versa, so check coverage before planning a migration.

OCAPI or SCAPI?

  • New headless storefront (PWA Kit or your own): SCAPI Shopper APIs. This is the path the platform's headless tools use; see Headless Storefronts with PWA Kit.
  • SFRA storefront: server-side code uses the Script API directly and does not call OCAPI at all.
  • Existing integrations on OCAPI: keep them working, and migrate endpoint by endpoint when SCAPI has an equivalent.
  • Back-office automation: whichever Data or Admin API covers the task; many new capabilities appear only in the Admin APIs.
flowchart TD
    A["Who is calling?"] --> B{"A shopper's app<br/>or storefront?"}
    B -->|"yes"| C["Shopper APIs<br/>(SCAPI, or OCAPI Shop)"]
    B -->|"no"| D["Back-office system"]
    D --> E["Data API (OCAPI)<br/>or Admin APIs (SCAPI)"]
    C --> F["Token from SLAS<br/>(guest or registered)"]
    E --> G["Token from Account Manager<br/>(client credentials)"]

Shoppers authenticate through SLAS, trusted systems through Account Manager.

SLAS: shopper tokens

SLAS (Shopper Login and API Access Service) issues the tokens that SCAPI Shopper APIs require. It supports guests and registered shoppers, and it can also connect to external identity providers. Two kinds of client exist:

  • Public client: runs where its code is visible (a browser app, a mobile app). It has no secret and uses the Authorization Code flow with PKCE to prove that the app which started the login is the one finishing it.
  • Private client: runs on a server and keeps a client secret. It can use the secret directly, for example to get guest tokens.

The tokens you receive:

  • an access token (a short-lived JWT, on the order of half an hour) sent as Authorization: Bearer ...;
  • a refresh token (long-lived, longer for registered shoppers than for guests) used to get a new access token without logging in again.

A sketch of the public-client guest flow, read-only because it needs a real tenant:

HTTP
GET /shopper/auth/v1/organizations/f_ecom_zzxx_001/oauth2/authorize
    ?client_id=...&channel_id=RefArch&redirect_uri=...
    &response_type=code&hint=guest
    &code_challenge=<S256 hash of a random verifier>

โ†’ 303 redirect to redirect_uri?code=<authorization code>&usid=<id>

POST /shopper/auth/v1/organizations/f_ecom_zzxx_001/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code_pkce&code=...&code_verifier=<the random verifier>
&client_id=...&redirect_uri=...&channel_id=RefArch&usid=<id>

โ†’ { "access_token": "...", "refresh_token": "...", "expires_in": 1800, ... }

Remember the rules that follow from this:

  1. Never put a client secret in front-end code. Only private clients on a server may hold one.
  2. Store tokens carefully. Browsers should keep them in memory or in cookies you control, not in places scripts of third parties can read freely.
  3. Refresh before you fail. Check expiry and refresh early, and treat a 401 as "get a new token once, then retry once".

For the surrounding concepts of sessions and registered versus guest shoppers, see Customers, Sessions and Profiles.

API clients and permissions

Two registries decide what a caller may do:

  • Account Manager holds API clients for back-office and Data/Admin access (client ID, secret, and the roles/scopes granted for the organization and tenants). Create separate clients per integration, never share one, and rotate secrets.
  • SLAS clients are created for shopper-facing apps with a list of allowed redirect URIs and scopes. Keep them per application and per environment.

Always give each client the least privilege it needs: a product-feed integration should not be able to touch customers or orders.

Rate limits and good behaviour

Both API families protect the platform with limits and quotas, and responses can include 429 Too Many Requests or 503-class errors under pressure. A well-behaved client:

  • Caches shopper reads (product and category data change rarely) instead of asking for the same thing on every page.
  • Batches where an endpoint accepts several IDs.
  • Backs off on 429 and 503: wait, then retry with growing delays, and add random jitter so many clients do not retry in sync. If a Retry-After header is present, honour it.
  • Retries only safe requests automatically. A POST that creates an order needs an idempotency design first; see Idempotency.

Live stand-ins

First, a mock token service and API client. The token lifetime is short on purpose; the clock is a number we advance. Watch the client reuse the token, refresh it when it is about to expire, and recover from a surprise 401.

JS A client that caches and refreshes its token

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Second, a rate-limit-aware request helper with exponential backoff. The server here is simulated, so the retries and delays shown are exactly reproducible.

JS Backing off on 429 responses

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. An SFRA storefront wants the product title on a page. How does its server-side code normally get it?

    SFRA code runs on the platform and uses the Script API directly. OCAPI and SCAPI are for external callers.
  2. 2. Which client type may keep a secret and use it to get tokens?

    Secrets must stay on servers. Public clients, whose code users can read, use PKCE instead of a secret.
  3. 3. What should a client do when an API answers 429?

    Backing off reduces pressure on the platform and avoids synchronized retries from many clients.
  4. 4. Which statement about OCAPI settings is correct?

    A resource that is not allowed for a client ID is rejected, so grant the minimum needed.

Summary

  • OCAPI (instance hostname, /dw/shop and /dw/data) and SCAPI (shared gateway, short code and organization ID) both expose shopper and back-office APIs; SCAPI is the direction for new headless work.
  • OCAPI access is controlled by client IDs plus OCAPI settings JSON; SCAPI Shopper APIs need SLAS tokens, back-office APIs need Account Manager clients.
  • Public clients use PKCE and no secret; private clients keep secrets on servers; refresh tokens before the access token expires.
  • Grant least privilege, cache shopper reads, and back off on 429 and 503.

Next, the headless storefront that is built on these APIs: Headless Storefronts with PWA Kit.