*Download API specification

API Overview

The Shopper Configurations API provides cacheable configuration data to shopper-facing applications, enabling them to make decisions based on merchant settings without requiring server-side logic.

This highly cacheable data encompasses toggles, preferences, and configuration information that allows the application to be reactive to changes performed by the merchant, admin, or support engineer.

Configuration types include:

• siteConfiguration: Site-specific settings such as name, status, currencies, and locales
• globalConfiguration: Instance-wide settings such as feature flags

Authentication & Authorization

The Shopper Configuration API requires a shopper access token from the Shopper Login and API Access Service (SLAS).

You must include sfcc.shopper-configuations in the client ID used to generate the SLAS token. For a full list of required permissions, see the Authorization Scopes Catalog.

For details on how to request a shopper access token from SLAS, see the guest user flows for public clients and private clients in the SLAS guides.

Use Cases

Use Hooks

You can extend the Shopper Configurations response with custom data using the dw.shop.shopper_configuration.modifyGETResponse hook. This is useful for adding custom site preferences to the response.

Example Hook Implementation

exports.modifyGETResponse = function (configResp) {
var customPreference = dw.system.Site.getCurrent().getCustomPreferenceValue(
"customerServiceEmail"
);
configResp.c_customPrefs = {
customerServiceEmail: customPreference || "noreply@example.com"
};
};

For details on hook registration, see Hook Method Details.

Site Identification and Availability

Retrieve the site's display name and current operational status to determine if the storefront is online, offline, or in a maintenance state for shoppers.

Currency Configuration

Identify the default currency for the site and the list of all supported currencies to ensure correct price rendering and multi-currency support.

Locale and Language Settings

Access the default locale and the full set of supported locales to localize content, formatting, and language for the shopper's specific region.

Feature Enablement

View the status of various storefront features and toggles to dynamically enable or disable application logic based on the merchant's active configuration.

Caching

Caching capabilities are available for the Shopper Configuration APIs. For details, see Server-Side Web-Tier Caching.*

For instructions on how to retrieve access token for admin APIs: https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html

Example with admin auth

import { ShopperConfigurations, ClientConfig } from "commerce-sdk";
// or
const { ShopperConfigurations, ClientConfig } = require("commerce-sdk");

const clientConfig: ClientConfig = {
  parameters: {
    clientId: "XXXXXX",
    organizationId: "XXXX",
    shortCode: "XXX",
    siteId: "XX"
  }
};

token = { access_token: 'INSERT_ACCESS_TOKEN_HERE' };

clientConfig.headers['authorization'] = `Bearer ${token.access_token}`;
const shopperConfigurationsClient = new ShopperConfigurations(clientConfig);

API Version: 1.4.4
Last Updated: