Get Started with the B2C Commerce API
The B2C Commerce API (SCAPI) is a collection of RESTful APIs for interacting with B2C Commerce instances. It goes by a few different names: Salesforce Commerce API, the acronym SCAPI, or just Commerce API.
By using SCAPI, you can build a wide range of applications: from full storefronts to custom merchant tools to add to Business Manager. To learn how SCAPI fits into the B2C Commerce stack, see Composable Storefront and SCAPI. For B2C Commerce customers, the API is available at no extra cost.
This page describes SCAPI and how to get started using it. To browse the endpoints, see the API Reference. To view B2C Commerce Administrator documentation, see Get Started with B2C Commerce.
If you don't have a B2C Commerce instance, try out the APIs with a demo sandbox and sample data as described in Quick Start.
To set up your own instance to use SCAPI:
- Determine the environment in which you'll be working, for example, dev, prod, staging. You can also create your own on-demand sandbox.
- Familiarize yourself with the API groupings for SCAPI.
- Follow the instructions in Base URL and Request Formation and Authorization guides.
Review the remaining sections in this topic for additional SCAPI overview information.
SCAPI consists of two main groups of APIs: Shopper APIs and SCAPI Admin APIs. The API group you use depends on your application.
- We designed the Shopper API group for customer-facing functions such as product browsing, shopping cart management, and checkout.
- We aimed the SCAPI Admin API group at merchant-facing functionality such as product management, order management, inventory management, and customer management.
Let’s compare the two API groups side by side:
| SCAPI Shopper APIs | SCAPI Admin APIs |
|---|---|
| Used by shoppers or trusted systems acting on their behalf | Used by administrators or other privileged users |
| Access secured by the Shopper Login and API Access Service (SLAS) | Access secured by Account Manager |
| Supports anonymous users and multiple authentication methods | Authentication is handled exclusively by Account Manager |
| Read only (exceptions: Shopper Baskets and Shopper Orders) | Read and write |
| Designed for high-scale usage | Designed for moderate usage |
| API names start with "Shopper" | No naming convention |
| Includes: Shopper Baskets, Shopper Customers, Shopper Orders, and Shopper Products | Includes: Assignments, Catalogs, Customers, Inventory Availability, Orders, and Products |
A key part of SCAPI is the Shopper Login and API Access Service (SLAS). The SLAS authorization endpoints provide the tokens that secure access to the Shopper APIs. SLAS provides the tokens by using grant types defined by the OAuth 2.1 standard.
In addition to securing access to the Shopper API, SLAS can also turn on third-party identify providers, single sign-on, and personalization in your application.
To learn more about SLAS and how to use it in your application, see the SLAS guides.
Open-source JavaScript SDKs are available on npm to help you get started:
| Package | Description | Documentation | Source Code |
|---|---|---|---|
commerce-sdk | Node.js SDK used in server-side or command-line applications. | Docs | Source |
commerce-sdk-isomorphic | JavaScript SDK is used in server-side applications and in web browsers. | Docs | Source |
@salesforce/commerce-sdk-react | React.js SDK. | Docs | Source |
For other languages, check out the SCAPI Postman collection or the API specifications included in commerce-sdk.
If you want to build a storefront using SCAPI, we offer the Composable Storefront solution. See the Composable Storefront documentation.
SCAPI is separate from the Open Commerce API (OCAPI). Although you can accomplish many of the same tasks with either API, there isn’t complete feature parity between them.
See Why Use SCAPI Instead of OCAPI.
With SCAPI, you can customize and extend functionality:
- Customize the behavior of Shopper APIs using hooks included in cartridges deployed on your B2C Commerce instance. See Extensibility via Hooks.
- If you need additional functionality that you can't implement by using hooks, see Custom APIs.
Use correlation IDs to match a particular request to a particular response. This makes it easier to troubleshoot unexpected issues, such as internal server errors.
If a correlation-id header is provided in a request to a SCAPI endpoint, the response contains an x-correlation-id header that contains the value of correlation-id. The API also generates its own correlation ID for each response.
See Identifying Requests and Responses.
In combination with the correlation-id, you can use the sfdc_verbose header to generate and find a verbose log output in Log Center.
- To use SCAPI with staging environments set to use vanity domains, you must set up eCDN for Staging.
- To ensure availability and protect you from denial of service attacks, some SCAPI requests are rate limited. For details on how each family of APIs is limited, see Rate Limits.
- Shopper APIs and Custom APIs must respond within 10 seconds, and SCAPI Admin API requests and hooks must respond within 60 seconds. If a response to a SCAPI request exceeds the timeout threshold, the HTTP 504 status code is returned.
- To improve performance, Shopper API family requests are routed to B2C Commerce servers using the token's Unique Shopper ID (USID). To avoid overloading a single server, don't use the same USID to make requests on behalf of many guest shoppers.
- SCAPI does not support cross origin requests. To use it with web browsers, use a reverse proxy.
Some new features are available only with specific B2C Commerce versions. This information is included in the B2C Commerce Release Notes and the API specification where applicable.
Make sure that your code can handle nonbreaking changes to the API.
We regularly update SCAPI with new features, performance optimizations, bug fixes, security updates, and other improvements. These updates are announced in Salesforce Status and the SCAPI Release Notes.
Although we avoid making breaking changes without prior notification, updates sometimes include nonbreaking changes, such as:
- New endpoints
- New methods added to existing endpoints
- New body fields including:
- New response fields
- New optional request fields
- New required request fields with default values
- Changes to the order of fields in the response body
- New optional request and response headers or changes to the casing of existing header name
- New optional query parameters
- New required query parameters that have default values
- Changes to error responses. We don’t recommend parsing error messages to perform business logic. Use HTTP response codes and error types instead.
- New claims added to the SLAS JWT
- Reordering of claims in the SLAS JWT
- Fixes to HTTP response codes and error codes from incorrect code to correct code
- HTTP response header name casing changes.
B2C Commerce uses a rolling release strategy when deploying new features. Make sure that your production instance group is running the required B2C Commerce version before you attempt to use a new feature in production, and check the B2C Commerce Deployment Schedule to determine when to expect deployment to all your instances. :::
You can subscribe to updates regarding the availability of SCAPI on Salesforce Status.
During B2C Commerce system updates maintenance responses are returned by the API.
SCAPI provides load shedding and rate limiting so that your shoppers always have access to your storefront.