SFCC OCAPI vs. SCAPI: Choosing the Right API for Each Integration

A team planning a new Salesforce B2C Commerce storefront or integration will encounter both OCAPI and SCAPI. The decision is not settled by replacing one name with the other everywhere. Start with what the application needs to do, which realm it will run on, and what existing custom behavior each call invokes.

Salesforce's OCAPI settings guidance states that settings are no longer available by default for realms provisioned for new customers starting September 1, 2026. It directs new customers to SCAPI for custom REST implementations. Existing customers provisioning a new realm can request OCAPI settings through support if they need access. This is a planning constraint, not an announcement that every existing OCAPI integration has stopped functioning.

Map the calls before choosing a migration path

For each storefront or back-office use case, record the operation, its caller, authentication, permissions, response fields, custom hooks, and downstream dependencies. Separate shopper-facing requests, such as basket changes, from administrative data work. Verify an actual supported endpoint and permission model for each operation rather than assuming similarly named APIs have identical coverage.

A practical inventory might include catalog reads, product search, customer sessions, basket mutations, checkout and orders, plus catalog-management jobs. Give every operation one of three statuses: supported and tested on the intended SCAPI path; retained on an existing OCAPI path with a named owner; or unresolved pending documentation and sandbox validation. That is a better migration plan than a date-based blanket rewrite.

Pay special attention to authentication and extensions

Do not carry token handling, scopes, or client permissions from one API configuration into another by analogy. Confirm the intended shopper or system identity flow against the specific endpoint and environment, and keep secrets out of browser code and logs.

Custom hooks can cross the apparent API boundary. Salesforce documents that related SCAPI and OCAPI calls can invoke the same historically named hooks, but also identifies differences that matter to hook implementations. Inventory the hooks triggered by each operation and test their returned basket or order effects through the same API path the new client will use.

Consider a promotion dependency: adding or removing a qualifying item can change a discount and final total. Our SCAPI promotion walkthrough explains one implementation-specific basket calculation pattern. The API-choice question here is narrower: which requests invoke that rule, and do they preserve the expected result during coexistence or migration?

A worked choice: a new headless checkout beside a legacy integration

Suppose an established B2C Commerce site has an OCAPI-backed integration while a new React storefront will handle shopping and checkout. Do not write "migrate OCAPI to SCAPI" as one backlog item. Build an operation ledger first:

• Shopper catalog and product search: list the current calls, localization and pricing context, response fields, and which frontend views depend on them. Verify the corresponding candidate SCAPI operations and their cache behavior in the target realm.
• Guest and registered sessions: identify where each client obtains and refreshes shopper tokens, which site the token belongs to, and where those credentials are stored. Salesforce's SLAS guidance describes access tokens scoped to a B2C Commerce instance and site; a shopper token issued for one site must not be reused for another.
• Basket and checkout: list create, add, remove, coupon, shipping, payment, and order operations. For each, compare response shape, errors, and calculation-hook behavior using the same fixture and storefront path.
• Back-office updates: separate operational catalog or order work from shopper calls. Verify an appropriate Admin API or other supported mechanism for the exact operation; do not send a shopper token to an administrative endpoint. Salesforce's Custom API guidance explicitly distinguishes shopper and admin security schemes.

Record the ledger as `operation | current caller | candidate path | identity and scopes | hook | expected response | evidence | owner`. A blank candidate path is a research task, not proof that the operation is unsupported. A passed GET response is not evidence that basket writes, tax, or errors are equivalent.

When standard endpoints do not express the requirement

First decide whether the missing behavior belongs in an existing supported operation or a custom one. Salesforce supports SCAPI Custom APIs defined with an OpenAPI contract, a cartridge implementation, registration, and an explicit security scheme. That can be a better boundary for business-specific behavior than asking a client to chain several calls and infer the result. It also creates code and an API contract the team must own; it is not a reason to create a custom endpoint for every inconvenient response field.

Do not confuse a Custom API with a response hook. The former declares a new endpoint; the latter extends behavior around supported calls. In either case, test the actual operation, errors, authorization, and site configuration before assuming the implementation is portable across realms.

Cache behavior belongs in the migration test

A catalog response can pass in a clean sandbox and still serve the wrong shopper context under load. Salesforce's SCAPI caching guidance says the cache key is computed before hook customization. Conditional hook logic that changes a response without changing the cache key can therefore create a stale or incorrectly shared result. Test two shopper contexts that must produce different results, inspect the responses and cache behavior, and make the personalization inputs available before key construction where the platform requires it. Keep personal data out of cacheable responses.

This is one reason to compare behavior by operation rather than declaring SCAPI and OCAPI equivalent because both calls return `200` in a happy-path test.

A staged acceptance decision

For one representative journey, capture a baseline on the old path: identity and site, product and basket inputs, expected adjustments and total, an error case, and the owner of each custom rule. Exercise the candidate path in a non-production realm. Require matching business outcomes, not necessarily byte-for-byte JSON. Check logs and timeouts as well as customer-visible output.

Then classify each call: move now with verified parity; retain on OCAPI with a named owner and review date; replace with a defined Custom API; or hold for an unresolved capability or realm-access question. This gives leadership a real migration scope and gives engineers a finite test list. It does not imply an existing API will be shut off by an arbitrary project deadline.

A decision worksheet for the team

Before approving the integration, ask: Which realm will host it? Which exact operations are needed? How will each caller authenticate? Which hooks and Business Manager settings affect the response? What sandbox evidence proves basket, customer, and order behavior? Who will own any remaining OCAPI dependency?

The output should be an endpoint inventory and a tested migration decision, not an architecture slide that says "use the new API." If you need help mapping that boundary, Tevpro works across SFCC storefronts, commerce rules, and integrations.