🎉 Check out DevCenter, our new documentation site for v2.0! (Or keep using this site for earlier versions.)

Switch to DevCenter

Menu Sheet Overlay

Integrating Salesforce Commerce Cloud

Important: Projects generated after 2019 do not use the Integration Manager because it has been replaced with our Commerce Integrations technology.

For anyone working on projects that were generated before 2019, we've left the Integration Manager documentation here in case you still need to refer to it.

Mobify provides an Salesforce Commerce Cloud (SFCC) cartridge and connector that simplifies integration:

  • The cartridge installs the Mobify Tag and Mobify Serivce worker.
  • The connector uses the Open Commerce API (OCAPI) to communicate with SFCC.

Before you begin

Before following these instructions you should:


To complete integration with SFCC you must:

  1. Install the cartridge
  2. Create an OCAPI client
  3. Update OCAPI settings
  4. Set up the connector in your project

Install the cartridge

The cartridge adds the Mobify Tag and Mobify Service Worker to your SFCC site.

Download the cartridge from the LINK Marketplace. Follow the installation instructions included with it.

You must login with your SFCC account to view and download the cartridge!

Once you've installed it, verify the Mobify Tag and service worker are present on your site.

Create an OCAPI client

The client allows the connector to communicate with SFCC using OCAPI.

Create a new OCAPI client. Note its client ID. It is need to configure OCAPI settings and the connector.

Update OCAPI settings

Settings control which OCAPI resources can be used by the connector.

  1. Login to the SFCC Business Manager.
  2. Select Administration > Site Development > Open Commerce API Settings.
  3. Select Shop and the relevant Site ID. Record the Site ID. It is needed to set up the connector!
  4. Open the settings in an editor. Update the client_id.
  5. Copy the contents of your settings into the field and Save.

If you are using extensions with the connector, you may need additional settings.

Set up the connector

Configuring the connector tells it how to talk to your SFCC site.

In the Web SDK, the connector is configured and registered with Integration Manager in web/app/init-sfcc-connector.js. Update it with your siteID and clientID from earlier.

Open web/app/main.jsx and remove the other connectors. Import the one we set up:

- import initConnector from './init-merlins-connector'
- import initConnector from './init-stub-connector'
+ import initConnector from './init-sfcc-connector'


You're done! Great job! 🙌

Your PWA should now be integrated with SFCC.

Verifying it worked

To verify, load the PWA and confirm it gets data from SFCC.

  1. Start the development server by running npm start in the web folder.
  2. Open a web browser and activate mobile emulation.
  3. Copy Preview URL from your console and open it in your web browser.
  4. Ensure the Site URL is set to your SFCC site's homepage over HTTPS.
  5. Hit Preview!

If everything worked correctly, you should see the PWA load your site:


npm start doesn't work!

  • Check your JavaScript for syntax errors.
  • Check your are running the command from inside the web folder of your project.
  • Check that your packages are up to date by running npm install from the root of your project.

After previewing, the PWA doesn't load!

  • Check for HTTPS errors.
  • Verify the Mobify Tag is present on the page
  • Open DevTools and confirm requests to SFCC are succeeding.


We use JSON Web Tokens (JWT) for authentication with Salesforce Commerce Cloud. The details of how JWT authentication works in SFCC are documented in the Salesforce documentation.

The Connector for SFCC automatically manages requesting a JWT token when a sessions starts and then submits and renews the token as needed.

Authentication using JWT does not work correctly in Safari for sites that require Basic HTTP authentication. Safari uses the Basic authentication header instead of the JSON Web Token, which causes requests to the API to fail. To fix this issue, disable basic HTTP authentication for the site.

Utility Functions

There are a number of utility functions that you may find useful if you need to extend the Connector for SFCC. They simplify interacting with SFCC OC APIs by taking care of things like authentication tokens (JWT) and cart management automatically.

If you are extending the Connector for SFCC we strongly recommend using these functions instead of implementing similar functionality from scratch.

The functions are organized into a set of broad categories below.


getAuthToken(): string

Retrieves the auth token from browser storage.

You almost never need to use this function directly because the Request Functions manage the authorization token automatically.

storeAuthToken(authToken: string)

Stores the auth token to browser storage. This function stores the auth token using the best available method (currently it tries session storage first and falls back to using a cookie).

You almost never need to use this function directly because the Request Functions manage the authorization token automatically.


Deletes the auth token from browser storage.

You almost never need to use this function directly because the Request Functions manage the authorization token automatically.

getAuthTokenPayload(authToken: string): object

Returns an object built using the given serialized auth token. The SFCC documentation provided in the Authentication/JWT section details the various pieces of data that the auth token contains.


Returns the customer data portion of the currently-stored authorization token. SFCC packs some extra customer data into the authorization token (such as a Customer ID) and this function returns that data unchanged.

SFCC documentation does not specify what this object contains in all scenarios. The best way to discover what it contains is to call this function after setting up a session and authenticating and then execute console.log(getCustomerData()) and inspect it in the Javascript console.

isUserLoggedIn(authorization) -> boolean

Returns true if the given authToken represents a logged in user, false otherwise.

initSfccSession(authToken: string): Promise<Array<string>>

Initializes an SFCC session using the provided authToken. This function returns a Promise that resolves to an array of headers to use in subsequent API requests (session headers).


Initializes an SFCC session and authorization token (re-using an existing authorization token if a valid one was previously created). This function will also refresh a saved authorization token if it has expired.


makeApiRequest(path: string, options: object): Promise<object>

Executes an API request to the specified path and returns Promise that resolves with the server's results. The resolved object is the Response object returned by the fetch API and is documented here.

Note that this method only takes a path instead of a full URL because the connector manages building the full URL based on the configured Site ID.

makeApiJsonRequest(path: string, body: object, options: object): Promise<object>

Makes a request to the SFCC API and serializing the body as JSON and deserializing the result from JSON. This function delegates to makeApiRequest and then deserializes the response as JSON.

checkForResponseFault(responseJSON: string): string

Checks the given response JSON object and throws if it contains a fault (error). If the response does not contain a fault, the response is returned unchanged. This is useful for using this method in a Promise chain without any extra work when the response is not a fault.

For example:

// Returns a Promise that resolves with current cart data, or throws if an error occurs
return makeApiJsonRequest('/cart', {}, {method: 'GET'})
    .then((cart) => {
        // update cart in the UI

makeUnAuthenticatedApiRequest(path: string, options: object): Promise<object>

Exactly the same as makeApiRequest but explicitly doesn't set any authorization headers. This is useful if you need to make an API call outside of the current session/user.

Basket/Cart Management


Deletes the currently-saved basket ID from browser storage.

getBasketID(): string

Retrieves the currently-saved basket ID from browser storage

storeBaskedID(basketID: string)

Stores the given basket ID to browser storage

createBasket(basketContents: object)

Creates a new basket on the SFCC server with the given contents. This function will take care of using an existing Basket ID, if one has been previously created and saved, or create a new one, if needed.

createNewBasket() => (dispatch)

[Thunk Action] Deletes and creates a new basket carrying over existing cart contents to the newly created basket.

fetchCartItemImages() => (dispatch)

[Thunk Action] Fetches product images for items that are in the cart and don't already have them.

requestCartData(noRetry: boolean): Promise<object>

Fetches cart data from SFCC for the current cart. When noRetry is set to false the process will retry if the server returns an HTTP 404 Not Found error.

handleCartData(basket: object): Promise

Processes the provided cart data and dispatches it to the Redux store. This will also dispatch fetchCartItemImages at the end to ensure that all items in the cart have an associated image. The returned Promise resolves when all work is completed. The resolved value is undefined.

isCartExpired(basket: object): boolean

Checks if the given cart contents contains a fault that signals an expired cart. Returns true if the given cart (basket) is expired, false otherwise.

updateExpiredCart(basket: object)

Check if the users cart has expired, if it has create a new one and throw an error otherwise return the cart object


  • OCAPI - the Open Commerce API provides access to most SFCC resources through a REST API. The OCAPI is divided into different APIs:
    • Shop API - allows a client to interact with the system as a shop customer or as an agent shopping on behalf of a customer.
    • Data API - gives create/read/update/delete access to system resources.
  • JWT - JSON Web Token - an authentication mechanism required by several Shop API resources. You can find out more about the SFCC usage of JWT above and at the JWT homepage.
  • Basket/Cart - Typically known as "cart" in the e-commerce industry, most of the SFCC documentation and OCAPI refer to the cart as "Basket". The terms are interchangable in this document. Typically when you see "basket" it is due to influence from the SFCC OCAPI.



Was this page helpful?