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, please refer to Retail Cloud SPI and API Spec.
Create an external client app with OAuth and JWT enabled. Use these instructions to get set up: Create a Local External Client App.
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 will fail authentication.
- Log in to the merchant's 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. It will be used for the Authorization header in the API requests.
Sample Authorization Header:
The below headers are required for making API requests. 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 the 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. The region and locale values should match the region and locale where the merchant is being accessed.
| 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:
The example targets a Production Sandbox environment.