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 with all 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 to help you identify your B2C Commerce instance and direct 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 according to your instance and API family:

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

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 next section.

For each B2C Commerce instance that uses the B2C Commerce API, 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:

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.

to 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. Copy and paste it in a location that is easy to refer to later.

A realm describes a set of B2C Commerce instances, including both primary and secondary instances. The realm ID is part of the organization ID. It’s a four-character string that comes after the second underscore (_) in the organization ID. For example, if the organization ID is f_ecom_zzte_053, then the realm ID is zzte. To learn more about realms, see Concepts and Terminology in the B2C Commerce documentation.

The instance ID identifies an instance within a realm. It’s a three-character string that comes after the third underscore in the organization ID. For example, if the organization ID is f_ecom_zzte_053, then the instance ID is 053.

Different types of instances follow different ID patterns:

• 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's associated with a supporting system, such as the Shopper Login and API Access Service (SLAS). To associate an instance with a system like SLAS, 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. See Salesforce Omnichannel Inventory Implementation Guide for B2C Commerce.

THese are example tenant IDs for various types of instances:

The short code is an eight-character string that's assigned to a realm for routing purposes. It’s concatenated with api.commercecloud.salesforce.com to create the API host name for your API calls, for example: u8ak193h.api.commercecloud.salesforce.com.

The short code applies to the entire realm, across all instances.

To look up the short code for your realm:

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.
4. If you’ve never used the B2C Commerce API in your realm, click Request Short Code. 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 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.

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.

To get product information for product ID 25695327M on the RefArchGlobal site, combine the base URL with the getProduct endpoint.

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 isn't 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 specification to learn the exact requirements of each endpoint.

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

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

See also:

• SLAS
• Security
• Performance