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 been 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 REST API is right for you? Salesforce guidance is to use SCAPI:

• All new customers and existing customers with new projects should use SCAPI.
• If you're doing major refactoring work on an existing project, Salesforce recommends moving to SCAPI.

Why do we recommend SCAPI over OCAPI? The primary reason is that our efforts for feature development and innovation are focused on SCAPI. OCAPI updates are now in a maintenance-only mode. As we enhance SCAPI, its performance, capabilities, and user-friendliness for developers continuously improves.

New SCAPI endpoints and features are being added regularly. 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.

This topic describes additional advantages of using SCAPI.

SCAPI provides additional APIs that provide a variety of capabilities, such as Shopper Login and API Access Service, Shopper Content, and Custom APIs.

Shopper APIs rely on our SLAS service which is an OAuth2 standards-based authentication service. SLAS 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

You can also use SLAS to shopper authenticate to OCAPI, so you can use both API sets simultaneously during a transition period. (Note that SLAS with OCAPI still has the Account Manager requirement.)

The Shopper Context API brings personalization to your storefront experiences. With Shopper Context, you can set context information for a shopper (device type, store ID, source code, and so on) 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). Then, it's used to activate the experiences that are associated with a particular segment, such as promotions.

This use case is supported natively in SCAPI, in which many of the endpoints accept a context and respond with personalized responses. In OCAPI, this use case is handled manually. Context information is often stored inside the HTTP session, and evaluated with custom hook code on the backend to affect the API responses. With SCAPI, you can eliminate that type of code, 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 in which you can write custom script code, such as controllers, and expose this functionality as a custom REST API under the SCAPI framework, so you can close gaps you sometimes see in the APIs with your own code.

The B2C Commerce Script API provides access to the B2C Commerce platform objects and features on the server. Developers often create custom code that uses the cartridge structure to expose makeshift APIs but in a very unstructured format. By leveraging Custom APIs, you 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. Custom API calls also have a smaller resource footprint on the Salesforce B2C Commerce Cloud back end than the controller-based alternative, so you can enjoy the same functionality with less overhead. As we continue to add more SCAPI functionality, performance, and scale, Custom APIs can access that as well.

Our default implementation of a headless storefront, the Composable Storefront, uses SCAPI exclusively. The behaviors of the open source PWA Kit are guided by what SCAPI can do, because they were made to work together. The result is that we're 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.

We built SCAPI with high capacity in mind, so that it can handle requests even when your storefront is under a high load.

SCAPI responses contain header information with the capacity of the server (from 0-100) so that 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 load shedding and rate limits techniques to maximize the availability of the B2C Commerce instance. Rate limits were removed for most SCAPI endpoints, but they 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. After the server exceeds 90% load, requests to the server are 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 approach provides 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. With this approach, developers can take necessary action for their experiences when these situations arise.

SCAPI provides capabilities that simplify adoption and use.

We designed SCAPI 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, so the APIs can be consistent across families, making it easier for new developers to adopt. Everything conforms to the specifications, and all the APIs use the same naming conventions and structures.

Creating SDKs has been an important part of SCAPI since we created it and made it the primary way that our own Composable Storefront interacts with the APIs. We also provide MuleSoft Connectors for the APIs 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) provides easy interactions with the B2C Commerce platform’s Shopper APIs on the Node.js runtime and works both in browsers and in 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, because the SCAPI cache relies on the same server layer that SFRA uses for its cache. The cache is controlled by an endpoint, and unlike OCAPI caching, SCAPI handles personalized responses in the cache because the most frequently called endpoints are often for products, many of which contain personalized information.

Product caching also takes into account the expansion of product requests: retrieving variations, prices, images, availability, and so on. Product caching also takes differently configured TTL for the expansions into consideration. SCAPI performs caching at the object level, instead of the entire response level. 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 retrieves those 8 from the cache and fetches the other 16.

This level of caching yields overall improvement in response times. We plan to make more improvements to the SCAPI caching structure and features.

• 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 listed on the Develop resources page.
• 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.