--- schema_version: "1" id: a4db115d01f92ca15316c2dd887faa2fc8b4003802401538573229b2e1abec16 title: Shopper Configurations collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-configurations.md canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-configurations source_site: developer.salesforce.com content_type: documentation content_hash: 2c05ec38d19cec242d12a84e7be3cddd9563abaa9e7791dba3e2f9f05c64a2c8 products: - B2C Commerce API - Salesforce APIs --- Shopper Configurations # Shopper Configurations [Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-configurations/shopper-configurations-oas-v1-public.yaml) ## 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.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html) For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html) 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. ```javascript 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](https://developer.salesforce.com/docs/commerce/commerce-api/guide/hook-method-details.html). For general information on hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html) ### 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.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html) #### 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.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html) #### Error Handling Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) 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.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html) ### Use Cases #### Get Site Configuration Retrieve site and global configuration settings (name, status, currencies, locales, feature flags). ```sh 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. **Version:** 1.4.2 ## Servers * `https://{shortCode}.api.commercecloud.salesforce.com/configuration/shopper-configurations/v1` * `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)` ## Security * `ShopperToken` (oauth2) Shopper token flow. * OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token) * Scope sfcc.shopper-configurations: Shopper Configurations READONLY * OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token) * Scope sfcc.shopper-configurations: Shopper Configurations READONLY * `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only. * OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context) * Scope sfcc.shopper-configurations: Shopper Configurations READONLY ## Operations ### GET Retrieves configurations `GET /organizations/{organizationId}/configurations` Operation ID: `getConfigurations`. Security: ShopperToken (sfcc.shopper-configurations, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-configurations, sfcc.shopper-standard). Retrieves configurations for the specified organization and site. #### Parameters * `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). _Example_ ``` f_ecom_zzxy_prd ``` * `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites. _Example: SiteId_ ``` RefArch ``` * `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken. Example: `550e8400-e29b-41d4-a716-446655440000`. * `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response. Allowed values: `none`. Example: `none`. * `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application. #### Responses * **200** Retrieved configurations successfully. Media type: `application/json`. Schema: `SiteConfiguration`. _Example: ConfigurationsExample_ ``` { "configurations": [ { "id": "id", "value": "RefArch", "configurationType": "siteConfiguration" }, { "id": "name", "value": "Ref Arch", "configurationType": "siteConfiguration" }, { "id": "status", "value": "online", "configurationType": "siteConfiguration" }, { "id": "timezone", "value": "Etc/UTC", "configurationType": "siteConfiguration" }, { "id": "timezoneOffset", "value": 0, "configurationType": "siteConfiguration" }, { "id": "defaultCurrency", "value": "USD", "configurationType": "siteConfiguration" }, { "id": "allowedCurrencies", "value": [ "USD", "EUR" ], "configurationType": "siteConfiguration" }, { "id": "defaultLocale", "value": "en-US", "configurationType": "siteConfiguration" }, { "id": "allowedLocales", "value": [ { "id": "en-US", "country": "US", "default": true, "displayCountry": "United States", "displayLanguage": "English", "displayName": "English (United States)", "iso3Country": "USA", "iso3Language": "eng", "language": "en", "name": "English (United States)" }, { "id": "en-CA", "country": "CA", "default": false, "displayCountry": "Canada", "displayLanguage": "English", "displayName": "English (Canada)", "iso3Country": "CAN", "iso3Language": "eng", "language": "en", "name": "English (Canada)" } ], "configurationType": "siteConfiguration" }, { "id": "SalesforcePaymentsAllowed", "value": true, "configurationType": "globalConfiguration" }, { "id": "gcp", "value": "abc123", "configurationType": "globalConfiguration" } ] } ``` * **400** Bad request - invalid parameters provided. Media type: `application/json`. Schema: `ErrorResponse`. _Example: getShopperConfigurations400_ Bad Request Error Example of a 400 Bad Request error response ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request", "title": "Bad Request", "detail": "The request could not be processed due to invalid parameters.", "correlationId": "12345678-1234-1234-1234-123456789012" } ``` * **401** Your shopper JWT is invalid and cannot be used to identify the API client. Media type: `application/json`. Schema: `ErrorResponse`. _Example: getShopperConfigurations401_ Unauthorized Error Example of a 401 Unauthorized error response ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "title": "Unauthorized", "detail": "Your shopper JWT is invalid and cannot be used to identify the API client.", "correlationId": "12345678-1234-1234-1234-123456789012" } ``` * **404** Application context not found for the specified organization and site. Media type: `application/json`. Schema: `ErrorResponse`. _Example: getShopperConfigurations404_ Not Found Error Example of a 404 Not Found error response ``` { "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-found", "title": "Not Found", "detail": "Configuration not found for the specified organization and site.", "correlationId": "12345678-1234-1234-1234-123456789012" } ``` ## Schemas ### OrganizationId An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id). Type: `string`. Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`. ### SiteId The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites Type: `string`. Minimum length: 1. Maximum length: 32. Example: `RefArch`. ### SiteConfiguration Site Configuration object * `configurations` (_array of Configuration_, required) List configurations for the instance and site Maximum items: 100. ### ErrorResponse * `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization Maximum length: 256. Example: `You do not have enough credit`. * `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `NotEnoughMoney`. * `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem. Example: `Your current balance is 30, but that costs 50`. * `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5. Maximum length: 2048. Example: `/account/12345/msgs/abc`. ### Configuration Configuration object * `id` (_string_, required) identifier Maximum length: 255. Example: `SalesforcePaymentsAllowed`. * `value` (_any_, required) value for identifier Maximum length: 255. Example: `true`. * `configurationType` (_string_) type of configuration value Maximum length: 255. Example: `globalConfiguration`.