Base URL and Request Formation

Before you start working with B2C Commerce APIs, you must understand the configuration of the base URL and the specific parameters for your instance.

This guide covers how to construct well-formed requests to the B2C Commerce API that include all the required parameters. To identify your specific configuration information needed in your URLs, refer to the Configuration Values section.

The base URL for all requests to the B2C Commerce API follows a pattern for identifying your B2C Commerce instance and directing your request to the correct API family. To understand the pattern, let’s look at the base URL with placeholders (enclosed in double curly braces) for the parts of the URL that vary depending on your instance and API family:

Make sure to specify v1 for the version, unless you are working with Shopper Baskets. For Shopper Baskets, specify v1 or v2, as applicable.

Now let’s replace the placeholders with the following example values:

PlaceholderValue
{{shortCode}}kv7kzm78
{{apiFamily}}product
{{apiName}}shopper-products
{{organizationId}}f_ecom_zzte_053

With example values, the base URL looks like this:

The short code and organization ID in our examples belong to the demo sandbox. How to look up these values for your own B2C Commerce instance is discussed in the following section.

For each B2C Commerce instance that uses the B2C Commerce API, you must gather a set of configuration values related to that instance. These configuration values are required to complete the setup process and to formulate API requests.

A typical set of configuration values looks like this:

Configuration ValueExample
Organization IDf_ecom_zzte_053
Short codekv7kzm78
Site IDRefArch

This guide provides more details on each configuration value and shows you where to find them.

The organization ID is a short string that identifies a B2C Commerce instance. Each instance gets its own unique organization ID, such as f_ecom_zzte_053.

You can look up the organization ID for an instance through Business Manager. You must have the Business Manager Administrator role in Account Manager and know the Business Manager URL for the instance.

A Business Manager URL looks like this:

To look up the organization ID:

  1. Go to the Business Manager URL for your instance.
  2. Log in using your Account Manager credentials.
  3. Go to Administration > Site Development > Salesforce Commerce API Settings.

The organization ID is displayed on the page. Click Copy to Clipboard and paste it in a location that is easy to refer to later.

image.png

The part of the organization ID following the second underscore (_) character is a four-character string called the realm ID. If the organization ID is f_ecom_zzte_053, then the realm is zzte.

A realm describes a set of B2C Commerce instances, including both primary and secondary instances. To learn more about realms, see Concepts and Terminology in the B2C Commerce documentation.

The part of the organization ID following the third underscore (_) character is a three-character string called the instance ID. If the organization ID is f_ecom_zzte_053, then the instance ID is 053.

The instance ID is a three-character string for identifying an instance within a realm:

  • For production, staging, or development instances, the instance IDs are prd, stg, or dev, respectively.
  • For on-demand sandboxes, the instance ID is a three-digit number that increases as more sandboxes are created.
  • For POD sandboxes, the format of the instance ID is sXX, where XX is a number between from 01 to 99.

A B2C Commerce instance is considered a “tenant” when it is associated with a supporting system, such as the Shopper Login and API Access Service (SLAS). To associate an instance with a system like SLAS, you must identify the instance with a tenant ID. A tenant ID begins with a four-character realm ID, followed by an underscore (_) and an instance ID.

For Omnichannel Inventory (OCI) updates, retrieve the tenant ID from OCI. For details, see Salesforce Omnichannel Inventory Implementation Guide for B2C Commerce.

Example tenant IDs for various types of instances:

Instance TypeRealm IDInstance IDTenant ID
Stagingbcglstgbcgl_stg
On-demand sandboxzzte053zzte_053
POD sandboxzzrfs01zzrf_s01

The short code is an eight-character string that is assigned to a realm for routing purposes. The short code applies to your entire realm, across all instances.

The short code is in the same place as the organization ID. To look it up:

  1. Go to the Business Manager URL for your instance.
  2. Log in using your Account Manager credentials.
  3. Go to Administration > Site Development > Salesforce Commerce API Settings.

If you’ve never used the B2C Commerce API in your realm, click Request Short Code to request one.

image.png

It can take up to 24 hours for the short code to propagate through the CDN and all the routing systems in your configuration.

The short code is concatenated with api.commercecloud.salesforce.com to create the API host name for your API calls. For example: u8ak193h.api.commercecloud.salesforce.com

The site ID is the name of the site (sometimes called a “channel”) for which you want to access data. For example: RefArch or SiteGenesis.

To see a list of sites in Business Manager:

  1. Go to the Business Manager URL for your instance.
  2. Log in using your Account Manager credentials.
  3. Go to Administration > Sites > Manage Sites.

To learn more about site names, see Create a Site in Business Manager in the B2C Commerce documentation.

For Shopper Baskets, specify v1 or v2, as applicable.

For all other APIs, specify v1.

Now let’s combine the base URL with the getProduct endpoint to get product information for product ID 25695327M on the RefArchGlobal site:

Notice that the name of the endpoint, getProduct, doesn’t appear in the URL. The getProduct string is only used as an identifier for the endpoint in the documentation. The URL for that endpoint is formulated by adding products/{{productID}} to the base URL.

The full URL in our endpoint example also includes a required query parameter, siteId, to the query string.

Many endpoints have required query parameters. For the Shopper APIs, the siteId parameter is often required.

To make a valid request, a well-formed URL is not sufficient. Most endpoints have additional requirements for HTTP headers and the request body (usually in the form of a JSON object). Always check the API reference to learn the exact requirements of each endpoint.

After gathering all the configuration values for your B2C Commerce instances, refer to Authorization to set up an API client for API access. This setup differs for Shopper APIs and Admin APIs.

To learn about the B2C Commerce API in more detail, we recommend exploring the following topics:

To learn from other Commerce API users, see the Community guide.