Get Started with the B2C Commerce API
This section describes the B2C Commerce APIs and how to get started using them. To browse the endpoints, see the API Reference.
The B2C Commerce API 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.
SCAPI enables developers to build a wide range of applications: from full storefronts to custom merchant tools to augment Business Manager. To learn how SCAPI fits into the B2C Commerce stack, see Composable Storefront and SCAPI. For all B2C Commerce customers, the API is available at no extra cost.
If you do not have a B2C Commerce instance, try out the APIs with a demo sandbox and sample data using the instructions in Quick Start.
To set up your own instance to use SCAPI:
- Determine the environment in which you will 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 Admin APIs, and the APIs you use depends on your application. The Shopper API group is designed for customer-facing functions such as product browsing, shopping cart management and checkout. The Admin API group is aimed 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:
| Shopper APIs | 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, Shopper Products and 7 more | Includes: Assignments, Catalogs, Customers, Inventory Availability, Orders, Products, and 8 more |
A key part of the B2C Commerce API is the Shopper Login and API Access Service (SLAS). The SLAS authorization endpoints provide the tokens that secure access to the Shopper APIs. Tokens are provided using a variety of grant types defined by the OAuth 2.1 standard.
Besides securing access to the Shopper API, SLAS can also enable the following features in your application: third-party identify providers, single sign-on, and personalization.
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 developers 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 used server-side and in web browsers. | Docs | Source |
@salesforce/commerce-sdk-react | React.js SDK. | Docs | Source |
For other languages, check out the Salesforce Commerce API Postman collection or the API specifications included in commerce-sdk.
For developers that want build a storefront using B2C Commerce API we offer the the Composable Storefront solution. To learn more see the Composable Storefront documentation.
The B2C Commerce API 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.
For complete details, see Why Use SCAPI Instead of OCAPI.
With SCAPI, you can customize and extend functionality:
- The behavior of Shopper APIs can be customized using hooks included in cartridges deployed on your B2C Commerce instance. For more information, see Extensibility via Hooks.
- If you need additional functionality that is not possible to implement using hooks, see Custom APIs.
You can use correlation IDs to match a particular request to a particular response, making it easier to troubleshoot unexpected issues, such as internal server errors.
If a correlation-id header is provided in a request to a B2C Commerce API 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.
To learn more about correlating API requests and responses, see Identifying Requests and Responses.
- To use the B2C Commerce API 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, requests to some B2C Commerce API are rate limited. For details on how each family of APIs is limited, see Rate Limits.
- 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.
- B2C Commerce API does not support cross origin requests. To use it with web browsers, use a reverse proxy.
Make sure that your code can handle nonbreaking changes to the API.
B2C Commerce API is regularly updated with new features, performance optimizations, bug fixes, security updates, and other improvements. These updates are announced in Salesforce Status and the B2C Commerce API Release Notes.
While we avoid making breaking changes without prior notification, updates might 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.
New features might only be available with specific B2C Commerce versions, and this information is included in the B2C Commerce Release Notes and the API specification where applicable.
B2C Commerce uses a rolling release strategy when deploying new features. Make sure your production instance group is running the required B2C Commerce version before attempting 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 B2C Commerce API 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.