Why Use SCAPI Instead of OCAPI

B2C Commerce has two REST API products: the Open Commerce API (OCAPI) and the B2C Commerce API, also known as Salesforce Commerce API (SCAPI). OCAPI has existed in the platform since 2014 and is used by many customers on the B2C Commerce platform. SCAPI was introduced in 2020 as a new API infrastructure built for headless commerce.

So which one should you use? Salesforce guidance is to use SCAPI:

• If you are starting a new project, using SCAPI gets you started on the latest APIs.
• If you are performing major refactor work on an existing project, consider moving to SCAPI as part of your refactoring work.

Why do we advocate for the use of SCAPI over OCAPI? The primary reason is our efforts for feature development and innovation are focused on SCAPI , while OCAPI updates are slowly shifting towards a maintenance-only mode. As we enhance SCAPI, its performance, capabilities, and user-friendliness for developers will continuously improve.

New SCAPI endpoints and features are being added on a regular basis. There are several recent additions, including Shopper Experience APIs with support for Page Designer and Shopper Baskets APIs with merge basket functionality. Our emphasis on headless commerce and our Composable Storefront drives a need for superior APIs and channeling our efforts into SCAPI.

Additional advantages of using SCAPI are provided in the following sections.

Shopper APIs rely on our SLAS service which is an OAuth2 standards based authentication service. It provides many benefits, such as:

• JWT based tokens with public and private client use cases (registered and guest).
• Uses OAuth scopes to define permissions for API clients.
• Refresh tokens that can be easily renewed for extended periods of time.
• Support for multiple identity providers.
• Support for password-less login.
• No dependency on Account Manager.

SLAS can also be used to shopper authenticate to OCAPI, which allows use of both API sets simultaneously during a transition period. (Note: SLAS with OCAPI will still have the Account Manager requirement.)

The Shopper Context API is an easy way to bring personalization to your storefront experiences. Shopper Context allows developers to set context information for a shopper (device type, store ID, source code, etc.) and use it to retrieve personalized promotions, payment methods, and shipping methods. Context information is evaluated against the customer group definitions to determine a customer group (shopper segment) and then used to activate the experiences that are associated with a particular segment, such as promotions.

This is supported natively in SCAPI, in which many of the endpoints accept a context and respond with personalized responses. In OCAPI, this must be handled manually. Context information was often stored inside the HTTP session, and would then be evaluated with custom hook code on the backend to affect the API responses. With SCAPI, all of that type of code can be eliminated, improving response times (no custom code execution), and giving base personalization from the start.

Introduced in 2024, Custom APIs are a powerful way to extend the API surface area for your implementations. They provide a framework enabling developers to write custom script code, such as controllers, and expose this functionality as a custom REST API under the SCAPI framework — allowing you to close gaps you might see in the APIs with your own code.

The B2C Commerce Script API provides access to all of the B2C Commerce platform objects and features on the server. Developers have often created custom code using the cartridge structure to expose makeshift APIs, but in a very unstructured format. By leveraging Custom APIs, a developer can take full advantage of everything that SCAPI provides: authentication and authorization, OAS API contract validation at the eCDN layer, server-side caching, and circuit breaking. As we continue to add more SCAPI functionality, performance, and scale, all Custom APIs will have access to that as well.

Our default implementation of a headless storefront, the Composable Storefront, uses SCAPI exclusively. All of the behaviors of the open source PWA Kit are guided by what SCAPI can do. They were made to work together and the result is we are constantly using and improving the APIs to make them better for the Composable Storefront — resulting in a better overall API for anyone that uses it.

SCAPI is built with high capacity in mind, and can still handle requests even when your storefront is under high load.

SCAPI responses contain header information with the capacity of the server (from 0 - 100) so developers can implement their own capacity management. Having this information provides better control to developers on how their application reacts if the platform is reaching certain temporary capacity limits.

SCAPI uses different techniques to maximize the availability of the B2C Commerce instance via load shedding and rate limits. Rate limits were removed for most SCAPI endpoints, but they do still apply for Shopper Login and Omni-Channel Inventory. All other endpoints are protected by shedding the load on the server as the server approaches capacity. Once the server exceeds 90% load requests to the server begin to be rejected with HTTP 503 status codes until capacity comes back under control. Calls are rejected starting with lower priority items (product lookup and searches) and keeping the focus on transactional requests (basket operations). This gives the most flexibility for API usage and makes sure that storefronts can maximize the capacity of the platform.

SCAPI provides response information when the B2C Commerce platform is in maintenance mode, either from system maintenance or when a site is set for maintenance in Business Manager. This allows developers to take the necessary action for their experiences when these situations arise.

SCAPI was designed with a focus on standards across the entire API set, making it easier to adopt a REST framework. SCAPI is built on a unified, common API specification with RAML. This allows the APIs to be consistent across families, and makes it easier for new developers to adopt. Everything conforms to the specifications, and all APIs use the same naming conventions and structures.

Creating SDKs has been an important part of SCAPI since it was created and has become the primary way that our own Composable Storefront interacts with the APIs. In addition we provide MuleSoft Connectors for the APIs as well to make it easy to leverage the APIs inside of MuleSoft.

• The Salesforce Commerce SDK allows easy interaction with the Salesforce B2C Commerce platform APIs on the Node.js runtime.
• The Salesforce Commerce SDK (Isomorphic) allows easy interaction with the B2C Commerce platform’s Shopper APIs on the Node.js runtime and works both in browsers and Node applications.
• The Commerce SDK React is a collection of react-query hooks for fetching, caching, and mutating data from SCAPI.
• The Salesforce B2C Commerce Cloud Data Connector and Shop Connector provide easy access to SCAPI from within MuleSoft.

Because SCAPI is the primary API receiving the focus of B2C Commerce development efforts, its performance continues to improve with every release. Performance and scale are top of mind with everything that we do.

SCAPI leverages web-tier caching on the server to provide improved response times for cached items. This cache differs from the way OCAPI performs caching, and instead relies on the same server layer that SFRA uses for its cache. The cache is controlled by an endpoint, and unlike OCAPI caching, it handles personalized responses in the cache — as often the most frequently called endpoints are for products, which often contain personalized information.

Product caching also takes into account the expansion of product requests — retrieving variations, prices, images, availability, etc. Each is cached separately with varying TTL that can be configured. Cache is also performed at the object level, instead of the entire response level. This means that a request to get 24 products caches each of the products, and a subsequent request for another 24 products that happen to include 8 of the initial 24 products will retrieve those 8 from the cache and fetch the other 16.

This level of caching shows overall improvement in response times, and continued SCAPI caching structure and feature improvements are planned.

• Try out SCAPI with a demo sandbox and sample data using the instructions in Quick Start.
• For detailed use case information and examples for specific APIs, see the guides in Develop.
• To explore the full capabilities of each set of API endpoints, see the specifications in the Reference section.
• To learn from other Commerce API users, see the Community guide.