*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-configurations 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.

Customization

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.

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. For general information on hooks, see Extensibility with Hooks.

Response Details

Personalization

Responses from this API are not personalized via the Shopper Context API.

Caching

Caching is provided for this API. For details, see Server-Side Web-Tier Caching.

Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see Timeouts and Limits.

Error Handling

Error responses follow the RFC 7807 problem detail format. To trace errors, include a correlation-id header in your request — the response returns it as x-correlation-id. For details, see HTTP Status Codes and Errors.

Use Cases

Get Site Configuration

Retrieve site and global configuration settings (name, status, currencies, locales, feature flags).

curl "https://{shortCode}.api.commercecloud.salesforce.com/configuration/shopper-configurations/v1/organizations/{organizationId}/configurations?siteId=RefArch" \
-H "Authorization: Bearer {access_token}"

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.*

Simple example:

  import { ShopperConfigurations } from "commerce-sdk-isomorphic";

  const clientConfig = {
    parameters: {
      clientId: "XXXXXX",
      organizationId: "XXXX",
      shortCode: "XXX",
      siteId: "XX"
    }
  };
  const shopperConfigurationsClient = new ShopperConfigurations(clientConfig);

API Version: 0.0.33
Last Updated: