Retail Cloud API Developer Guide for Hyperforce Users
Accessing Retail Cloud's APIs externally from Hyperforce involves a secure, token-based authentication process. This guide outlines the steps required to generate a JSON Web Token (JWT) and invoke the Retail Cloud API.
For a comprehensive list of APIs and SPIs, see Retail Cloud API Specifications.
Create an external client app with OAuth and JWT enabled. See Create a Local External Client App in Salesforce Help.
JWT generation requires the domain, consumer key, and consumer secret, all sourced from the Salesforce Org where the merchant is configured.
The API token must come from the same Salesforce Org as the merchant. Tokens from a different Org fail authentication.
- Log into the Organization or Sandbox Organization where the merchant was created.
- From Setup, in the Quick Find box, enter "External Client Apps", and then select External Client Apps Manager.
- Select the merchant's app, and click the Settings tab.
- Expand the OAuth Settings section.
- Click the Consumer Key and Secret button, and copy the key and secret. Save these values in a secure location.
- From Setup, in the Quick Find box, enter "My Domain", and then select My Domain.
- Copy the value shown in the Current My Domain URL field. Save this value in a secure location.
Request a JWT from Salesforce. Use this example POST request as a starting point. Replace the domain, client ID, and client Secret with the values you copied from Step 1.
Sample Token Request
Sample Response
Extract the access token value from the response. This token is used for the Authorization header in the API requests.
Sample Authorization Header
API requests require the headers in this list. The x-locale and x-region headers are merchant-specific, not Org-specific. A single Org (or Sandbox Org) can contain multiple merchants. These headers help route the request to the correct merchant within the Org.
- x-salesforce-region
- Content-Type
- x-locale
- x-region
- Authorization
Ensure Content-Type is set to application/json in all requests.
The base URL and x-salesforce-region header value depend on the merchant's environment. Use the correct values to ensure successful API requests. Make sure that the region and locale values match the region and locale for the merchant.
| Environment | Production Endpoint (Non-Sandbox) | Sandbox Endpoint | Required x-salesforce-region Value |
|---|---|---|---|
| Production | https://api.salesforce.com/commerce/retailcloud/v1-alpha.1 | https://api.salesforce.com/commerce/retailcloud/v1-alpha.1/sandbox | us-east-2 |
| Staging | https://stage.api.salesforce.com/commerce/retailcloud/v1-alpha.1 | https://stage.api.salesforce.com/commerce/retailcloud/v1-alpha.1/sandbox | us-east-2 |
| Test | https://test.api.salesforce.com/commerce/retailcloud/v1-alpha.1 | https://test.api.salesforce.com/commerce/retailcloud/v1-alpha.1/sandbox | us-west-2 |
| Dev | https://dev.api.salesforce.com/commerce/retailcloud/v1-alpha.1 | https://dev.api.salesforce.com/commerce/retailcloud/v1-alpha.1/sandbox | us-west-2 |
Example Request
This example targets a Production Sandbox environment.