If you would like to get a raw Response object use the other getGlobalCustomPreferenceList function.
An object containing the options for this method.
A promise of type CustomPreferenceList.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type CustomPreferenceList otherwise.
For the specified instance, read the custom preferences in the preference group at the global (organization) level. Specify 'current' to retrieve the preferences for the instance on which this call is being made. The system will recognize its type.
Note:* If instance type sandbox is used, the preference values of development instance type will be returned as fallback.
If you would like to get a raw Response object use the other getGlobalPreferenceGroup function.
An object containing the options for this method.
A promise of type OrganizationPreferences.
For the specified instance, read the custom preferences in the preference group at the global (organization) level. Specify 'current' to retrieve the preferences for the instance on which this call is being made. The system will recognize its type.
Note:* If instance type sandbox is used, the preference values of development instance type will be returned as fallback.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type OrganizationPreferences otherwise.
If you would like to get a raw Response object use the other getSiteCustomPreferenceList function.
An object containing the options for this method.
A promise of type CustomPreferenceList.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type CustomPreferenceList otherwise.
Read a specific preference value identified by its ID within the given preference group and instance type. Returns the preference value for all sites.
If you would like to get a raw Response object use the other getSitePreference function.
An object containing the options for this method.
A promise of type PreferenceValue.
Read a specific preference value identified by its ID within the given preference group and instance type. Returns the preference value for all sites.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type PreferenceValue otherwise.
For the specified site and instance, read the custom preferences in the preference group. Specify 'current' to retrieve the preferences for the instance on which this call is being made. The system will recognize its type.
If you would like to get a raw Response object use the other getSitePreferenceGroup function.
An object containing the options for this method.
A promise of type SitePreferences.
For the specified site and instance, read the custom preferences in the preference group. Specify 'current' to retrieve the preferences for the instance on which this call is being made. The system will recognize its type.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type SitePreferences otherwise.
Search preferences across sites in the specified preference group and instance. The query attribute specifies a complex query that can be used to narrow down the search.
The following is a list of searchable fields:
| Field | Type |
|---|---|
| id | String |
| display_name | Localized String |
| description | Localized String |
| value_type | Enum (see below) |
Allowed value_type values: string, int, double, text, html, date, image, boolean, money, quantity, datetime, email, password, set_of_string, set_of_int, set_of_double, enum_of_string, enum_of_int.
Note:* value_type can only be joined with other attributes using a conjunction (AND). Only searchable attributes can be used in sorting.
Note:* If instance type sandbox is used, the preference values of development instance type will be returned as fallback.
If you would like to get a raw Response object use the other searchSitePreferences function.
An object containing the options for this method.
A promise of type PreferenceValueSearchResult.
Search preferences across sites in the specified preference group and instance. The query attribute specifies a complex query that can be used to narrow down the search.
The following is a list of searchable fields:
| Field | Type |
|---|---|
| id | String |
| display_name | Localized String |
| description | Localized String |
| value_type | Enum (see below) |
Allowed value_type values: string, int, double, text, html, date, image, boolean, money, quantity, datetime, email, password, set_of_string, set_of_int, set_of_double, enum_of_string, enum_of_int.
Note:* value_type can only be joined with other attributes using a conjunction (AND). Only searchable attributes can be used in sorting.
Note:* If instance type sandbox is used, the preference values of development instance type will be returned as fallback.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type PreferenceValueSearchResult otherwise.
For the specified instance, update one or more custom preferences in the preference group at the global (organization) level.
Note:* If instance type sandbox is used, the preference values of development instance type will be returned as fallback.
If you would like to get a raw Response object use the other updateGlobalPreferenceGroup function.
An object containing the options for this method.
A promise of type OrganizationPreferences.
For the specified instance, update one or more custom preferences in the preference group at the global (organization) level.
Note:* If instance type sandbox is used, the preference values of development instance type will be returned as fallback.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type OrganizationPreferences otherwise.
Update a specific preference value identified by its ID within the given preference group and instance type. The siteValues map specifies the new values per site.
If you would like to get a raw Response object use the other updateSitePreference function.
An object containing the options for this method.
A promise of type PreferenceValue.
Update a specific preference value identified by its ID within the given preference group and instance type. The siteValues map specifies the new values per site.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type PreferenceValue otherwise.
For the specified site and instance, update one or more custom preferences in the preference group. Preferences of type password cannot be set to "****" since it is a reserved value.
If you would like to get a raw Response object use the other updateSitePreferenceGroup function.
An object containing the options for this method.
A promise of type SitePreferences.
For the specified site and instance, update one or more custom preferences in the preference group. Preferences of type password cannot be set to "****" since it is a reserved value.
An object containing the options for this method.
Set to true to return entire Response object instead of DTO.
A promise of type Response if rawResponse is true, a promise of type SitePreferences otherwise.
Generated using TypeDoc
Preferences
*Download API specification
API Overview
B2C Commerce teams must regularly configure site and environment-specific settings to support changing business needs and technical integrations. In many instances, Storefront Reference Architecture (SFRA)/SiteGenesis implementations rely on declarative Custom Site Preferences to alter these settings without the need for deployment or significant engineering support. Site preferences allow teams to adapt their sites with minimal effort.
The following Preferences API endpoints retrieve preference-related information:
Global custom preferences: Retrieves all custom preferences at the organization level.
Site custom prefererences: Retrieves all custom preferences at the site level.
The Preferences API first checks to see if custom values have been set, and if so, returns the custom settings. Otherwise, the Preferences API returns the default values provided in Business Manager.
Note: The Preferences API sets custom preferences. For details on working with non-custom preferences, see Global Preferences for B2C Commerce and Site Preferences in B2C Commerce.
Authentication & Authorization
For resource access, you must use a client ID and client secret from Account Manager to request an access token. The access token is used as a bearer token and added to the Authorization header of your API request.
You must include
sfcc.preferencesin the client ID used to generate the token. For a full list of required permissions, see the Authorization Scopes Catalog.For detailed setup instructions, see the Authorization for Admin APIs guide.
Use Cases
Global Custom Preference:
A prominent private equity firm manages a diverse portfolio of brands, each operating its own site. Despite the individuality of these brands, they leverage shared third-party integrations for critical functionalities, such as payments and content management. Through a centralized approach, the firm establishes specifications for key components like the payments portal, ensuring consistency and efficiency across all sites. These specifications are meticulously crafted and undergo infrequent modifications to accommodate evolving needs while maintaining operational stability.
Site Custom Preference:
Site operators might have numerous tests or features tailored to their specific site. To facilitate streamlined control over these functionalities, they need a user-friendly mechanism for their merchant team to effortlessly toggle them on or off as needed. The site Preference API provides this mechanism.
Caching
Caching capabilities are available for the Preferences 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 { Preferences, ClientConfig } from "commerce-sdk"; // or const { Preferences, 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 preferencesClient = new Preferences(clientConfig);Last Updated: