---
schema_version: "1"
id: 11ddc3f8d2d8f988b9ffee796202b88a0287e64a020816822238da6f47432e23
title: Preferences
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/preferences.md
canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/preferences
source_site: developer.salesforce.com
content_type: documentation
content_hash: 192865b6f192a88b081cc39c4cee4995471054e7c24e6f2bc86abf45ee500ee0
products:
  - B2C Commerce API
  - Salesforce APIs
---
Preferences

# Preferences

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/preferences/preferences-oas-v1-public.yaml)

## 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](https://help.salesforce.com/s/articleView?id=cc.b2c_global_preferences.htm&type=5) and [Site Preferences in B2C Commerce](https://help.salesforce.com/s/articleView?id=cc.b2c_site_preferences.htm&type=5).

### 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.preferences` in the client ID used to generate the 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 detailed setup instructions, see the [Authorization for Admin APIs guide.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html)

### Response Details

#### Timeouts

Admin API requests must respond within 60 seconds. 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

#### 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.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/server-side-web-tier-caching.html)

**Version:** 1.2.3

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/configuration/preferences/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

*   `AmOAuth2` (oauth2) AccountManager OAuth 2.0 bearer token Authentication.
    *   OAuth flow clientCredentials (tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token)
    *   Scope sfcc.preferences: Preferences read scope
    *   Scope sfcc.preferences.rw: Preferences read/write scope
    *   OAuth flow authorizationCode (authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize, tokenUrl: https://account.demandware.com/dwsso/oauth2/access\_token, refreshUrl: https://account.demandware.com/dwsso/oauth2/access\_token)

## Operations

### GET Retrieves the Global Custom Preferences.

`GET /organizations/{organizationId}/global-custom-preferences`

Operation ID: `getGlobalCustomPreferenceList`. Security: AmOAuth2 (sfcc.preferences, sfcc.preferences.rw).

#### 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
    ```
    
*   `maskPassword` (query, boolean) Whether to mask password or not.  
    Default: `false`. Example: `true`.
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 200.  
    Default: `200`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Retrieved Global Custom Preferences successfully.
    
    Media type: `application/json`. Schema: `CustomPreferenceList`.
    
    _Example: GlobalCustomPreferenceExample_
    
    ```
    {
      "limit": 10,
      "data": [
        {
          "groupId": "PreferenceGroup1",
          "id": "booleanValue",
          "value": true
        },
        {
          "groupId": "PreferenceGroup1",
          "id": "htmlValue",
          "value": {
            "markup": "<h1>HTML Value</h1>",
            "source": "<h1>HTML Value</h1>"
          }
        },
        {
          "groupId": "PreferenceGroup1",
          "id": "dateValue",
          "value": "2007-06-20T00:00:00.000Z"
        },
        {
          "groupId": "PreferenceGroup2",
          "id": "integerValueValue",
          "value": 12345
        },
        {
          "groupId": "PreferenceGroup2",
          "id": "stringValueList",
          "value": "s1"
        },
        {
          "groupId": "PreferenceGroup2",
          "id": "imageValue",
          "value": {
            "abs_url": "https://localhost/on/demandware.static/-/Sites/default/v2d48bd5c705782218c66e02f6776751b2e227ac5/img/value.jpg",
            "dis_base_url": "https://image.demandware.com/dw/image/v2/zzzz_s02/on/demandware.static/-/Sites/default/v2d48bd5c705782218c66e02f6776751b2e227ac5/img/value.jpg",
            "path": "/img/value.jpg"
          }
        }
      ],
      "offset": 0,
      "total": 100
    }
    ```
    
*   **400** Returned if the query is ill-formed.
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: InvalidAccessToken_
    
    ```
    {
      "title": "Invalid Access Token",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/invalid-access-token",
      "detail": "The request is unauthorized, the access token is invalid.",
      "accessToken": "hbGciOiJIUzI1NiIsInR5cCI6Ikp"
    }
    ```
    

### GET Retrieves the Custom Preferences for a specified siteId.

`GET /organizations/{organizationId}/site-custom-preferences`

Operation ID: `getSiteCustomPreferenceList`. Security: AmOAuth2 (sfcc.preferences, sfcc.preferences.rw).

#### 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
    ```
    
*   `maskPassword` (query, boolean) Whether to mask password or not.  
    Default: `false`. Example: `true`.
*   `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
    ```
    
*   `limit` (query, integer (int32)) Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 200.  
    Default: `200`. Minimum: 1. Maximum: 200.
*   `offset` (query, integer (int32)) Used to retrieve the results based on a particular resource offset.  
    Default: `0`. Minimum: 0.

#### Responses

*   **200** Retrieved Site Custom Preferences successfully.
    
    Media type: `application/json`. Schema: `CustomPreferenceList`.
    
    _Example: SiteCustomPreferenceExample_
    
    ```
    {
      "limit": 10,
      "data": [
        {
          "groupId": "PreferenceGroup1",
          "id": "booleanValue",
          "value": true
        },
        {
          "groupId": "PreferenceGroup1",
          "id": "htmlValue",
          "value": {
            "markup": "<h1>HTML Value</h1>",
            "source": "<h1>HTML Value</h1>"
          }
        },
        {
          "groupId": "PreferenceGroup2",
          "id": "integerValueValue",
          "value": 12345
        },
        {
          "groupId": "PreferenceGroup2",
          "id": "imageValue",
          "value": {
            "abs_url": "https://localhost/on/demandware.static/-/Sites/default/v2d48bd5c705782218c66e02f6776751b2e227ac5/img/value.jpg",
            "dis_base_url": "https://image.demandware.com/dw/image/v2/zzzz_s02/on/demandware.static/-/Sites/default/v2d48bd5c705782218c66e02f6776751b2e227ac5/img/value.jpg",
            "path": "/img/value.jpg"
          }
        }
      ],
      "offset": 0,
      "total": 100
    }
    ```
    
*   **400** Returned if the query is ill-formed.
*   **401** Unauthorized. Your Client ID is invalid, or you are not allowed to access the content provided by the requested URL.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example InvalidAccessToken: same as GET /organizations/{organizationId}/global-custom-preferences 401 response._
    

### GET Read the custom preferences in a global preference group for a given instance type.

`GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType}`

Operation ID: `getGlobalPreferenceGroup`. Security: AmOAuth2 (sfcc.preferences, sfcc.preferences.rw).

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.

#### 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
    ```
    
*   `groupId` (path, string, required) The preference group ID.  
    Minimum length: 1. Maximum length: 256. Example: `WapiStringGroup`.
*   `instanceType` (path, string, required) The instance type for which to read or update preferences.  
    Allowed values: `staging`, `development`, `sandbox`, `production`. Example: `staging`.
    
    _Example_
    
    ```
    staging
    ```
    
*   `maskPasswords` (query, boolean) The preference values of type Password are masked when set.  
    Default: `false`. Example: `true`.
*   `expand` (query, array of string, style: form, explode: false) Expands the result document to include additional information. For global preference groups, the expansion "sites" retrieves the custom preferences for all the available sites.  
    Items: Allowed values: `sites`. Example: `sites`.

#### Responses

*   **200** Custom preferences retrieved successfully.
    
    Media type: `application/json`. Schema: `OrganizationPreferences`.
    
    _Example: GetGlobalPreferencesExample_ Global preferences with custom attributes.
    
    ```
    {
      "c_WapiStringAttr": "MyString",
      "c_WapiLocalizedStringAttr": "MyLocalizedString",
      "c_WapiSitespecificStringAttr": "MySiteSpecificString",
      "c_WapiSetOfStringAttr": [
        "value1",
        "value2"
      ],
      "c_WapiEnumOfStringAttr": "WapiEnumOfStringValue1",
      "c_WapiEnumOfStringMSAttr": [
        "WapiEnumOfStringMSValue1",
        "WapiEnumOfStringMSValue2"
      ]
    }
    ```
    
    _Example: GetGlobalPreferencesWithSitesExample_ Global preferences with site-specific expansions.
    
    ```
    {
      "c_WapiStringAttr": "MyString",
      "c_WapiLocalizedStringAttr": {
        "default": "MyLocalizedString",
        "de-DE": "MeineLokalisierteZeichenkette"
      },
      "c_WapiSitespecificStringAttr": "MySiteSpecificString",
      "c_WapiSetOfStringAttr": [
        "value1",
        "value2"
      ],
      "c_WapiEnumOfStringAttr": "WapiEnumOfStringValue1",
      "c_WapiEnumOfStringMSAttr": [
        "WapiEnumOfStringMSValue1",
        "WapiEnumOfStringMSValue2"
      ],
      "c_WapiBooleanAttr": true,
      "c_WapiIntAttr": 42,
      "sitePreferences": [
        {
          "site": {
            "id": "RefArch"
          },
          "c_WapiStringAttr": "SiteSpecificStringRefArch",
          "c_WapiLocalizedStringAttr": {
            "default": "SiteLocalizedString",
            "de-DE": "StandortLokalisierteZeichenkette"
          },
          "c_WapiSitespecificStringAttr": "SiteSpecificValue",
          "c_WapiSetOfStringAttr": [
            "siteValue1",
            "siteValue2"
          ],
          "c_WapiEnumOfStringAttr": "WapiEnumOfStringValue1",
          "c_WapiBooleanAttr": false,
          "c_WapiIntAttr": 10
        },
        {
          "site": {
            "id": "RefArchGlobal"
          },
          "c_WapiStringAttr": "AnotherSiteValue",
          "c_WapiLocalizedStringAttr": {
            "default": "AnotherSiteLocalizedString"
          },
          "c_WapiSitespecificStringAttr": "AnotherSiteSpecificValue",
          "c_WapiSetOfStringAttr": [
            "anotherValue1"
          ],
          "c_WapiBooleanAttr": true,
          "c_WapiIntAttr": 99
        }
      ]
    }
    ```
    
*   **400** Invalid instance type was provided.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: IllegalEnumerationValue_
    
    ```
    {
      "title": "Illegal Enumeration Value",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/illegal-enumeration-value",
      "detail": "The value 'bad' for type 'InstanceType' is invalid.",
      "value": "bad"
    }
    ```
    
*   **404** The preference group was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: CustomPreferenceGroupNotFound_
    
    ```
    {
      "title": "Custom Preference Group Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/custom-preference-group-not-found",
      "detail": "No preference group with ID 'Bad' could be found.",
      "preferenceGroupId": "Bad"
    }
    ```
    

### PATCH Update the custom preferences in a global preference group for a given instance type.

`PATCH /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType}`

Operation ID: `updateGlobalPreferenceGroup`. Security: AmOAuth2 (sfcc.preferences.rw).

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.

#### 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
    ```
    
*   `groupId` (path, string, required) The preference group ID.  
    Minimum length: 1. Maximum length: 256. Example: `WapiStringGroup`.
*   `instanceType` (path, string, required) The instance type for which to read or update preferences.  
    Allowed values: `staging`, `development`, `sandbox`, `production`. Example: `staging`.
    
    _Example_
    
    ```
    staging
    ```
    
*   `maskPasswords` (query, boolean) The preference values of type Password are masked when set.  
    Default: `false`. Example: `true`.

#### Request body (required)

The preferences to update. Custom preference attributes use the "c\_" prefix.

Media type: `application/json`. Schema: `OrganizationPreferences`.

_Example: UpdateGlobalPreferencesRequest_ Update global custom preferences.

```
{
  "c_WapiStringAttr": "UpdatedString",
  "c_WapiIntAttr": 42,
  "c_WapiBooleanAttr": true,
  "c_WapiSetOfStringAttr": [
    "newValue1",
    "newValue2"
  ]
}
```

#### Responses

*   **200** Custom preferences updated successfully.
    
    Media type: `application/json`. Schema: `OrganizationPreferences`.
    
    _Example: UpdateGlobalPreferencesExample_ Updated global preferences response.
    
    ```
    {
      "c_WapiStringAttr": "UpdatedString",
      "c_WapiLocalizedStringAttr": "UpdatedLocalizedString",
      "c_WapiSetOfStringAttr": [
        "newValue1",
        "newValue2"
      ]
    }
    ```
    
*   **400** Invalid instance type was provided.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example IllegalEnumerationValue: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 400 response._
    
*   **404** The preference group was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example CustomPreferenceGroupNotFound: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 404 response._
    

### GET Read the custom preferences in a site preference group for a given instance type.

`GET /organizations/{organizationId}/site-preference-groups/{groupId}/{instanceType}`

Operation ID: `getSitePreferenceGroup`. Security: AmOAuth2 (sfcc.preferences, sfcc.preferences.rw).

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.

#### 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
    ```
    
*   `groupId` (path, string, required) The preference group ID.  
    Minimum length: 1. Maximum length: 256. Example: `WapiStringGroup`.
*   `instanceType` (path, string, required) The instance type for which to read or update preferences.  
    Allowed values: `staging`, `development`, `sandbox`, `production`. Example: `staging`.
    
    _Example_
    
    ```
    staging
    ```
    
*   `maskPasswords` (query, boolean) The preference values of type Password are masked when set.  
    Default: `false`. Example: `true`.
*   `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
    ```
    

#### Responses

*   **200** Custom site preferences retrieved successfully.
    
    Media type: `application/json`. Schema: `SitePreferences`.
    
    _Example: GetSitePreferencesExample_ Site preferences with custom attributes.
    
    ```
    {
      "site": {
        "id": "RefArch"
      },
      "c_WapiStringAttr": "MyString",
      "c_WapiLocalizedStringAttr": "MyLocalizedString",
      "c_WapiPasswordAttr": "************"
    }
    ```
    
*   **400** Invalid instance type was provided.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example IllegalEnumerationValue: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 400 response._
    
*   **404** The preference group was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example CustomPreferenceGroupNotFound: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 404 response._
    

### PATCH Update the custom preferences in a site preference group for a given instance type.

`PATCH /organizations/{organizationId}/site-preference-groups/{groupId}/{instanceType}`

Operation ID: `updateSitePreferenceGroup`. Security: AmOAuth2 (sfcc.preferences.rw).

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.

#### 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
    ```
    
*   `groupId` (path, string, required) The preference group ID.  
    Minimum length: 1. Maximum length: 256. Example: `WapiStringGroup`.
*   `instanceType` (path, string, required) The instance type for which to read or update preferences.  
    Allowed values: `staging`, `development`, `sandbox`, `production`. Example: `staging`.
    
    _Example_
    
    ```
    staging
    ```
    
*   `maskPasswords` (query, boolean) The preference values of type Password are masked when set.  
    Default: `false`. Example: `true`.
*   `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
    ```
    

#### Request body (required)

The site preferences to update. Custom preference attributes use the "c\_" prefix.

Media type: `application/json`. Schema: `SitePreferences`.

_Example: UpdateSitePreferencesRequest_ Update site custom preferences.

```
{
  "c_WapiStringAttr": "UpdatedString",
  "c_WapiLocalizedStringAttr": {
    "default": "UpdatedLocalizedString",
    "de-DE": "AktualisierteLokalisierteZeichenkette"
  },
  "c_WapiIntAttr": 42,
  "c_WapiBooleanAttr": true,
  "c_WapiSetOfStringAttr": [
    "newValue1",
    "newValue2"
  ]
}
```

#### Responses

*   **200** Custom site preferences updated successfully.
    
    Media type: `application/json`. Schema: `SitePreferences`.
    
    _Example: UpdateSitePreferencesExample_ Updated site preferences response.
    
    ```
    {
      "site": {
        "id": "RefArch"
      },
      "c_WapiStringAttr": "UpdatedString",
      "c_WapiLocalizedStringAttr": "UpdatedLocalizedString"
    }
    ```
    
*   **400** Invalid instance type was provided.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example IllegalEnumerationValue: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 400 response._
    
*   **404** The preference group was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example CustomPreferenceGroupNotFound: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 404 response._
    

### POST Search preferences across sites in a preference group for a given instance type.

`POST /organizations/{organizationId}/site-preference-groups/{groupId}/{instanceType}/preference-search`

Operation ID: `searchSitePreferences`. Security: AmOAuth2 (sfcc.preferences, sfcc.preferences.rw).

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.

#### 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
    ```
    
*   `groupId` (path, string, required) The preference group ID.  
    Minimum length: 1. Maximum length: 256. Example: `WapiStringGroup`.
*   `instanceType` (path, string, required) The instance type for which to read or update preferences.  
    Allowed values: `staging`, `development`, `sandbox`, `production`. Example: `staging`.
    
    _Example_
    
    ```
    staging
    ```
    
*   `maskPasswords` (query, boolean) The preference values of type Password are masked when set.  
    Default: `false`. Example: `true`.
*   `expand` (query, array of string, style: form, explode: false) Expands the result document to include additional information. For preference search, the expansion "value" retrieves the value definitions of the attribute definition.  
    Items: Allowed values: `value`. Example: `value`.

#### Request body (required)

The search request document.

Media type: `application/json`. Schema: `SearchRequest`.

_Example: SearchSitePreferencesRequest_ Search preferences by ID and value type.

```
{
  "query": {
    "boolQuery": {
      "must": [
        {
          "textQuery": {
            "fields": [
              "id"
            ],
            "searchPhrase": "WapiString"
          }
        },
        {
          "termQuery": {
            "fields": [
              "valueType"
            ],
            "operator": "is",
            "values": [
              "string"
            ]
          }
        }
      ]
    }
  },
  "sorts": [
    {
      "field": "id",
      "sortOrder": "asc"
    }
  ],
  "limit": 25,
  "offset": 0
}
```

#### Responses

*   **200** Preference search executed successfully.
    
    Media type: `application/json`. Schema: `PreferenceValueSearchResult`.
    
    _Example: PreferenceSearchExample_ Search result for preferences across sites.
    
    ```
    {
      "limit": 2,
      "offset": 0,
      "total": 2,
      "hits": [
        {
          "id": "WapiStringAttr",
          "displayName": {
            "default": "String Attribute"
          },
          "description": {
            "default": "String Attribute"
          },
          "valueType": "string",
          "attributeDefinition": {
            "id": "WapiStringAttr",
            "displayName": {
              "default": "String Attribute"
            },
            "description": {
              "default": "String Attribute"
            },
            "valueType": "string"
          },
          "siteValues": {
            "RefArch": "MyString-RefArch-Staging",
            "RefArchGlobal": "MyString-RefArchGlobal-Staging"
          }
        },
        {
          "id": "WapiLocalizedStringAttr",
          "displayName": {
            "default": "Localized String Attribute"
          },
          "description": {
            "default": "Localized String Attribute"
          },
          "valueType": "string",
          "attributeDefinition": {
            "id": "WapiLocalizedStringAttr",
            "displayName": {
              "default": "Localized String Attribute"
            },
            "description": {
              "default": "Localized String Attribute"
            },
            "valueType": "string"
          },
          "siteValues": {
            "RefArch": "MyLocalizedString-RefArch-Staging"
          }
        }
      ],
      "query": {
        "matchAllQuery": {}
      },
      "sorts": [
        {
          "field": "id",
          "sortOrder": "asc"
        }
      ]
    }
    ```
    
    _Example: PreferenceSearchWithExpandValueExample_ Search result with expanded value definitions.
    
    ```
    {
      "limit": 1,
      "offset": 0,
      "total": 1,
      "hits": [
        {
          "id": "WapiEnumOfStringAttr",
          "displayName": {
            "default": "Enum Of String Attribute"
          },
          "description": {
            "default": "Enum Of String Attribute"
          },
          "valueType": "enum_of_string",
          "attributeDefinition": {
            "id": "WapiEnumOfStringAttr",
            "displayName": {
              "default": "Enum Of String Attribute"
            },
            "description": {
              "default": "Enum Of String Attribute"
            },
            "valueType": "enum_of_string",
            "valueDefinitions": [
              {
                "id": "WapiEnumOfStringValue1",
                "displayValue": {
                  "default": "Value 1"
                },
                "position": 0,
                "value": "WapiEnumOfStringValue1"
              },
              {
                "id": "WapiEnumOfStringValue2",
                "displayValue": {
                  "default": "Value 2"
                },
                "position": 1,
                "value": "WapiEnumOfStringValue2"
              }
            ]
          },
          "siteValues": {
            "RefArch": "WapiEnumOfStringValue1"
          }
        }
      ],
      "query": {
        "textQuery": {
          "fields": [
            "id"
          ],
          "searchPhrase": "WapiEnumOfStringAttr"
        }
      }
    }
    ```
    
*   **400** The request is malformed. This can be caused by an invalid instance type, an ill-formed search query, or attempting to sort by a non-sortable field.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example IllegalEnumerationValue: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 400 response._
    
    _Example: FieldNotSortable_
    
    ```
    {
      "title": "Field Not Sortable",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/field-not-sortable",
      "detail": "The field 'attributeDefinition' can't be used to sort the results.",
      "field": "attributeDefinition"
    }
    ```
    
*   **404** The preference group was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example CustomPreferenceGroupNotFound: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 404 response._
    

### GET Read a single preference value across sites in a preference group for a given instance type.

`GET /organizations/{organizationId}/site-preference-groups/{groupId}/{instanceType}/preferences/{preferenceId}`

Operation ID: `getSitePreference`. Security: AmOAuth2 (sfcc.preferences, sfcc.preferences.rw).

Read a specific preference value identified by its ID within the given preference group and instance type. Returns the preference value for all sites.

#### 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
    ```
    
*   `groupId` (path, string, required) The preference group ID.  
    Minimum length: 1. Maximum length: 256. Example: `WapiStringGroup`.
*   `instanceType` (path, string, required) The instance type for which to read or update preferences.  
    Allowed values: `staging`, `development`, `sandbox`, `production`. Example: `staging`.
    
    _Example_
    
    ```
    staging
    ```
    
*   `preferenceId` (path, string, required) The preference attribute ID.  
    Minimum length: 1. Maximum length: 256. Example: `WapiStringAttr`.
*   `maskPasswords` (query, boolean) The preference values of type Password are masked when set.  
    Default: `false`. Example: `true`.

#### Responses

*   **200** Preference value retrieved successfully.
    
    Media type: `application/json`. Schema: `PreferenceValue`.
    
    _Example: GetPreferenceValueExample_ A single preference value.
    
    ```
    {
      "id": "WapiStringAttr",
      "displayName": {
        "default": "String Attribute",
        "de-DE": "Zeichenkettenattribut"
      },
      "description": {
        "default": "A custom string preference attribute",
        "de-DE": "Ein benutzerdefiniertes Zeichenkettenattribut"
      },
      "valueType": "string",
      "siteValues": {
        "RefArch": "MyString-RefArch-Sandbox",
        "RefArchGlobal": "MyString-RefArchGlobal-Sandbox"
      },
      "attributeDefinition": {
        "id": "WapiStringAttr",
        "effectiveId": "c_WapiStringAttr",
        "displayName": {
          "default": "String Attribute",
          "de-DE": "Zeichenkettenattribut"
        },
        "description": {
          "default": "A custom string preference attribute",
          "de-DE": "Ein benutzerdefiniertes Zeichenkettenattribut"
        },
        "valueType": "string",
        "key": false,
        "mandatory": false,
        "localizable": true,
        "siteSpecific": true,
        "searchable": false,
        "queryable": true,
        "visible": true,
        "system": false,
        "unit": {
          "default": ""
        },
        "requiresEncoding": false,
        "multiValueType": false,
        "setValueType": false,
        "externallyManaged": false,
        "externallyDefined": false,
        "orderRequired": false,
        "readOnly": false,
        "regularExpression": "^[a-zA-Z0-9]*$",
        "fieldLength": 256,
        "fieldHeight": 1,
        "minLength": 1,
        "minValue": 0,
        "maxValue": 100,
        "scale": 2,
        "defaultValue": {
          "id": "defaultVal",
          "value": "defaultString",
          "position": 1,
          "displayValue": {
            "default": "Default Value"
          },
          "description": {
            "default": "The default value"
          }
        },
        "valueDefinitions": []
      }
    }
    ```
    
    _Example: GetPreferenceValueMultiSiteExample_ A single preference value with multiple site values.
    
    ```
    {
      "id": "WapiSetOfStringAttr",
      "displayName": {
        "default": "Set Of String Attribute"
      },
      "description": {
        "default": "Set Of String Attribute"
      },
      "siteValues": {
        "RefArch": [
          "value1-RefArch-Sandbox"
        ],
        "RefArchGlobal": [
          "value1-RefArchGlobal-Sandbox"
        ]
      },
      "valueType": "set_of_string"
    }
    ```
    
*   **400** Invalid instance type was provided.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example IllegalEnumerationValue: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 400 response._
    
*   **404** The preference group or preference was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example CustomPreferenceGroupNotFound: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 404 response._
    
    _Example: PreferenceNotFound_
    
    ```
    {
      "title": "Preference Not Found",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/preference-not-found",
      "detail": "No preference with ID 'noExists' could be found.",
      "preferenceId": "noExists"
    }
    ```
    

### PATCH Update a single preference value across sites in a preference group for a given instance type.

`PATCH /organizations/{organizationId}/site-preference-groups/{groupId}/{instanceType}/preferences/{preferenceId}`

Operation ID: `updateSitePreference`. Security: AmOAuth2 (sfcc.preferences.rw).

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.

#### 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
    ```
    
*   `groupId` (path, string, required) The preference group ID.  
    Minimum length: 1. Maximum length: 256. Example: `WapiStringGroup`.
*   `instanceType` (path, string, required) The instance type for which to read or update preferences.  
    Allowed values: `staging`, `development`, `sandbox`, `production`. Example: `staging`.
    
    _Example_
    
    ```
    staging
    ```
    
*   `preferenceId` (path, string, required) The preference attribute ID.  
    Minimum length: 1. Maximum length: 256. Example: `WapiStringAttr`.
*   `maskPasswords` (query, boolean) The preference values of type Password are masked when set.  
    Default: `false`. Example: `true`.

#### Request body (required)

The preference value to update with site-specific values.

Media type: `application/json`. Schema: `PreferenceValue`.

_Example: UpdateSitePreferenceValueRequest_ Update a preference value for multiple sites.

```
{
  "id": "WapiStringAttr",
  "valueType": "string",
  "displayName": {
    "default": "My String Attribute",
    "de-DE": "Mein Zeichenkettenattribut"
  },
  "description": {
    "default": "A custom string preference attribute",
    "de-DE": "Ein benutzerdefiniertes Zeichenkettenattribut"
  },
  "siteValues": {
    "RefArch": "new value for RefArch",
    "RefArchGlobal": "new value for RefArchGlobal"
  },
  "attributeDefinition": {
    "id": "WapiStringAttr",
    "displayName": {
      "default": "My String Attribute",
      "de-DE": "Mein Zeichenkettenattribut"
    },
    "description": {
      "default": "A custom string preference attribute",
      "de-DE": "Ein benutzerdefiniertes Zeichenkettenattribut"
    },
    "valueType": "string",
    "key": false,
    "mandatory": false,
    "localizable": true,
    "siteSpecific": true,
    "searchable": false,
    "visible": true,
    "unit": {
      "default": "kg"
    },
    "multiValueType": false,
    "externallyManaged": false,
    "externallyDefined": false,
    "orderRequired": false
  }
}
```

#### Responses

*   **200** Preference value updated successfully.
    
    Media type: `application/json`. Schema: `PreferenceValue`.
    
    _Example: UpdatePreferenceValueExample_ Updated preference value response.
    
    ```
    {
      "id": "WapiLocalizedStringAttr",
      "displayName": {
        "default": "Localized String Attribute"
      },
      "description": {
        "default": "Localized String Attribute"
      },
      "siteValues": {
        "RefArch": "value for RefArch",
        "RefArchGlobal": "value for RefArchGlobal"
      },
      "valueType": "string"
    }
    ```
    
*   **400** Invalid instance type was provided.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example IllegalEnumerationValue: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 400 response._
    
*   **404** The preference group or preference was not found.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example CustomPreferenceGroupNotFound: same as GET /organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType} 404 response._
    
    _Example PreferenceNotFound: same as GET /organizations/{organizationId}/site-preference-groups/{groupId}/{instanceType}/preferences/{preferenceId} 404 response._
    

## 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`.

### CustomPreferenceList

Document representing a Custom Preference result.

Includes all fields of `PaginatedResultBase`.

*   `data` (_array of CustomPreference_, required) The list of custom preferences in the search result.

### 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`.

### 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`.

### OrganizationPreferences

Represents custom preferences at the global (organization) level within a preference group. Custom preference attributes are returned with the "c\_" prefix.

*   `sitePreferences` (_array of SitePreferences_) The list of site-specific preferences, returned when expand=sites.

### SitePreferences

Represents custom preferences at the site level within a preference group. Custom preference attributes are returned with the "c\_" prefix.

*   `site` (_Site_)

### SearchRequest

Document representing a search request for retrieving items within the Data API. The query is a potentially complex set of expressions. The fields and expands that each query supports are defined within the search resource.

*   `limit` (_integer (int32)_) Maximum records to retrieve per request, not to exceed 200.  
    Minimum: 1. Maximum: 200. Example: `10`.
*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The list of sort clauses configured for the search request. Sort clauses are optional. See the description of the search endpoint for details on the default sorting behavior that is used when explicit sorts are not passed.
*   `offset` (_Offset_)

### PreferenceValueSearchResult

Document representing a preference value search result.

Includes all fields of `PaginatedSearchResult`.

*   `hits` (_array of PreferenceValue_) The sorted array of search hits. Can be empty.

### PreferenceValue

Represents a single preference value with its attribute definition and site-specific values.

*   `id` (_string_, required) The preference attribute ID  
    Minimum length: 1. Maximum length: 256. Example: `WapiStringAttr`.
*   `description` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Preference Description`.
    
    _Example_
    
    ```
    {
      "default": "Preference Description",
      "en-US": "Preference Description",
      "de-DE": "Einstellungsbeschreibung",
      "ja-JP": "設定の説明"
    }
    ```
    
*   `displayName` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Preference Display Name`.
    
    _Example_
    
    ```
    {
      "default": "Preference Display Name",
      "en-US": "Preference Display Name",
      "de-DE": "Anzeigename der Einstellung",
      "ja-JP": "設定の表示名"
    }
    ```
    
*   `attributeDefinition` (_ObjectAttributeDefinition_)
*   `siteValues` (_object_) A mapping of site IDs to their preference values.
*   `valueType` (_ValueType_)

### PaginatedResultBase

Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. If you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`.

Includes all fields of `ResultBase`.

*   `offset` (_Offset_, required)

### CustomPreference

Preference object

*   `groupId` (_string_, required) The ID of the preference group.
*   `id` (_string_, required) The Preference Id.
*   `value` (_any_, required) The value for the Preference Id.

### Site

*   `id` (_object_, required)
    
    ID
    
    The ID of the site.
    
    Includes all fields of `SiteId`.
    
*   `displayName` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Site Display Name`.
    
    _Example_
    
    ```
    {
      "default": "Site Display Name",
      "en-US": "Site Display Name",
      "de-DE": "Site-Anzeigename",
      "ja-JP": "サイト表示名"
    }
    ```
    
*   `description` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Site Description`.
    
    _Example_
    
    ```
    {
      "default": "Site Description",
      "en-US": "Site Description",
      "de-DE": "Site-Beschreibung",
      "ja-JP": "サイトの説明"
    }
    ```
    
*   `customerListLink` (_object_) The link to the customer list
    
    Includes all fields of `CustomerListLink`.
    
*   `inDeletion` (_boolean_) Specifies whether the site status is in deletion (true) or not (false)  
    Example: `false`.
*   `storefrontStatus` (_string_) Status of the storefront  
    Allowed values: `online`, `maintenance`, `to_be_deleted`, `protected`. Example: `online`.
*   `siteCatalogId` (_string_) The catalog bound to the given site.  
    Minimum length: 1. Maximum length: 256. Example: `storefront-catalog-m-en`.
*   `cartridges` (_string_, read-only) The effective cartridge path for the site, delimited by ':'. Includes both system cartridges and the site's custom cartridges (see `customCartridges`).  
    Maximum length: 4000. Example: `app_storefront_base:plugin_apple_pay:plugin_facebook:plugin_payments:plugin_pinterest_commerce:plugin_web_payments:bc_content:core`.
*   `customCartridges` (_string_) The custom cartridge path assigned to the site, delimited by ':'. Does not include system cartridges. This is the subset of `cartridges` that can be configured for the site.  
    Maximum length: 4000. Example: `app_storefront_base`.
*   `creationDate` (_string (date-time)_) The timestamp when the site was created.  
    Example: `2024-01-15T10:00:00.000Z`.
*   `lastModified` (_string (date-time)_) The timestamp when the site was last modified.  
    Example: `2024-10-14T15:30:00.000Z`.

### Query

A set of objects that define criteria used to select records. A query can contain one of the following:

*   `MatchAllQuery`

*   Matches all documents.

*   `TermQuery`

*   Matches one or more documents against one or more document fields.

*   `TextQuery`

*   Matches text against one or more fields.

*   `BoolQuery`

*   Allows construction of a logical expression of multiple queries.

*   `FilteredQuery`

*   Allows a filter to be applied to a query.

*   `NestedQuery`

*   Allows you to query on nested documents.
*   _Only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation._

Minimum properties: 1. Maximum properties: 1.

*   `boolQuery` (_BoolQuery_)
*   `filteredQuery` (_FilteredQuery_)
*   `matchAllQuery` (_MatchAllQuery_)
*   `nestedQuery` (_NestedQuery_)
*   `termQuery` (_TermQuery_)
*   `textQuery` (_TextQuery_)

_Example_

```
{
  "filteredQuery": {
    "query": {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "disabled"
      }
    },
    "filter": {
      "termFilter": {
        "field": "enabled",
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  }
}
```

### Sort

Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.

*   `field` (_string_, required) The name of the field to sort on.  
    Maximum length: 256. Example: `couponId`.
*   `sortOrder` (_string_) The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.  
    Allowed values: `asc`, `desc`. Default: `asc`. Example: `asc`.

_Example_

```
{
  "field": "couponId",
  "sortOrder": "desc"
}
```

### Offset

The zero-based index of the first hit/data to include in the result.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `0`.

### PaginatedSearchResult

Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.

Includes all fields of `PaginatedResultBase`.

*   `query` (_Query_, required)
*   `sorts` (_array of Sort_) The sorting that was applied to the result.
*   `hits` (_array of object_) The sorted array of search hits. Can be empty.

_Example_

```
{
  "limit": 1,
  "hits": [
    {
      "couponId": "coupon1",
      "creationDate": "2019-10-20T12:00:00Z",
      "description": "This coupon is used to give 10% off stuff.",
      "enabled": false,
      "exportedCodeCount": 0,
      "lastModified": "2019-10-30T04:23:59Z",
      "redemptionCount": 3,
      "redemptionLimits": {
        "limitPerCode": 1,
        "limitPerCustomer": 1,
        "limitPerTimeFrame": {
          "limit": 2,
          "redemptionTimeFrame": 24
        }
      },
      "singleCode": "MyCode",
      "systemCodesConfig": {
        "codePrefix": "SG",
        "numberOfCodes": 500000
      },
      "totalCodesCount": 50,
      "type": "single_code"
    }
  ],
  "query": {
    "textQuery": {
      "fields": [
        "id",
        "description"
      ],
      "searchPhrase": "stuff"
    }
  },
  "sorts": [
    {
      "field": "couponId",
      "sortOrder": "desc"
    }
  ],
  "offset": 2,
  "total": 8
}
```

### ObjectAttributeDefinition

Document representing an attribute definition

*   `id` (_string_, required) The user supplied ID of the attribute  
    Minimum length: 1. Maximum length: 256. Example: `color`.
*   `effectiveId` (_string_, read-only) The effective ID, which is c\_id if the attribute is custom, and just the id otherwise  
    Maximum length: 256. Example: `c_color`.
*   `displayName` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Localized value`.
    
    _Example_
    
    ```
    {
      "default": "Product",
      "de": "Produkt",
      "en": "Product"
    }
    ```
    
*   `description` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Localized value`.
    
    _Example_
    
    ```
    {
      "default": "Object type representing products.",
      "de": "Objekttyp, der Produkte repräsentiert.",
      "en": "Object type representing products."
    }
    ```
    
*   `key` (_boolean_) Flag indicating if this is a key attribute  
    Example: `false`.
*   `mandatory` (_boolean_) Flag indicating if a value is mandatory for the attribute  
    Example: `false`.
*   `localizable` (_boolean_) Flag indicating if this attribute can be localized  
    Example: `false`.
*   `siteSpecific` (_boolean_) Flag indicating if this attribute is site-specific  
    Example: `false`.
*   `searchable` (_boolean_) Flag indicating if this attribute is searchable  
    Example: `true`.
*   `queryable` (_boolean_, read-only) Returns true if the attribute definition is explicitly marked queryable or if the attribute value type belongs to a queryable type. Computed and read-only.  
    Example: `true`.
*   `valueType` (_ValueType_)
*   `visible` (_boolean_) Flag indicating if this attribute is visible  
    Example: `true`.
*   `system` (_boolean_) Flag indicating if this attribute is a system attribute  
    Example: `false`.
*   `unit` (_object_) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Localized value`.
    
    _Example_
    
    ```
    {
      "default": "General unit",
      "de": "Allgemeine Einheit",
      "en": "General unit"
    }
    ```
    
*   `requiresEncoding` (_boolean_, read-only) Flag indicating if this attribute can be encoded using the encoding='off' flag in ISML templates  
    Example: `false`.
*   `multiValueType` (_boolean_) True if the attribute can have multiple values. Applicable to set\_of\_\* and enum\_of\_\* types.  
    Example: `false`.
*   `setValueType` (_boolean_, read-only) Flag indicating if this attribute is of type 'Set of'  
    Example: `false`.
*   `externallyManaged` (_boolean_) Flag indicating if this attribute is externally managed  
    Example: `false`.
*   `externallyDefined` (_boolean_) Flag indicating if this attribute is externally defined  
    Example: `false`.
*   `orderRequired` (_boolean_) Flag indicating if this attribute is required for order of the attribute model's product  
    Example: `false`.
*   `regularExpression` (_string_, read-only) A regular expression that defines the legal values for this attribute  
    Maximum length: 4000. Example: `^[a-zA-Z]+$`.
*   `fieldLength` (_integer (int32)_, read-only) The length of the field for this attribute in the editor  
    Example: `50`.
*   `fieldHeight` (_integer (int32)_, read-only) The height of the field for this attribute in the editor  
    Example: `1`.
*   `minLength` (_integer (int32)_, read-only) The minimum length of the field for this attribute  
    Example: `1`.
*   `readOnly` (_boolean_, read-only) Flag indicating if this attribute is read-only  
    Example: `false`.
*   `minValue` (_number (double)_, read-only) The minimum possible value for this attribute  
    Example: `0`.
*   `maxValue` (_number (double)_, read-only) The maximum possible value for this attribute  
    Example: `100`.
*   `scale` (_integer (int32)_, read-only) The minimum number of fraction digits for a value of this attribute  
    Example: `2`.
*   `defaultValue` (_object_) The default value of this attribute. It can be updated, but not created.
    
    Includes all fields of `ObjectAttributeValueDefinition`.
    
*   `valueDefinitions` (_array of ObjectAttributeValueDefinition_, read-only) A set of values that are possible for this attribute
*   `creationDate` (_string (date-time)_, read-only) The date/time when the attribute definition was created  
    Example: `2024-01-15T10:30:00Z`.
*   `lastModified` (_string (date-time)_, read-only) The date/time when the attribute definition was last modified  
    Example: `2024-01-15T11:00:00Z`.

### ValueType

The type of an attribute value

Type: `string`.

Allowed 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`. Example: `string`.

### ResultBase

Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. Additionally it needs to be defined what data is returned.

*   `limit` (_integer (int32)_, required) Maximum records to retrieve per request. The limit with its constraints (minimum, maximum, default) is defined by the request parameter `limit` of the endpoint returning this schema.  
    Example: `10`.
*   `total` (_Total_, required)

### CustomerListLink

Document representing a link to a customer list.

*   `customerListId` (_string_) The customer list identifier  
    Minimum length: 1. Maximum length: 256. Example: `customer-list-1`.
*   `title` (_string_) The title of the customer list link  
    Maximum length: 256. Example: `Default Customer List`.

### BoolQuery

A boolean query allows construction of full logical expression trees that are composed of other queries (usually term queries and text queries). A boolean query has three sets of clauses:

*   `must`, which combines as an `AND` operator.
*   `should`, which combines as an `OR` operator.
*   `must_not`, which combines as a `NOT` operator.

If `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:

```
(must-1 AND must-1 AND ...)
  AND (should-1 OR should-2 OR ...)
  AND NOT (must_not-1 OR must_not-2 OR ...)
```

*   `must` (_array of Query_) List of queries to be evaluated as an `AND` operator.
*   `mustNot` (_array of Query_) List of queries to be evaluated as a `NOT` operator.
*   `should` (_array of Query_) List of queries to be evaluated as an `OR` operator.

_Example_

```
{
  "must": [
    {
      "textQuery": {
        "fields": [
          "couponId"
        ],
        "searchPhrase": "DEAL"
      }
    },
    {
      "textQuery": {
        "fields": [
          "description"
        ],
        "searchPhrase": "Big bargain deal"
      }
    }
  ],
  "mustNot": [
    {
      "termQuery": {
        "fields": [
          "enabled"
        ],
        "operator": "is",
        "values": [
          false
        ]
      }
    }
  ]
}
```

### FilteredQuery

Allows to filter the result of a possibly complex query using a possibly complex filter.

*   `filter` (_Filter_, required)
*   `query` (_Query_, required)

_Example_

```
{
  "query": {
    "textQuery": {
      "fields": [
        "couponId"
      ],
      "searchPhrase": "disabled"
    }
  },
  "filter": {
    "termFilter": {
      "field": "enabled",
      "operator": "is",
      "values": [
        false
      ]
    }
  }
}
```

### MatchAllQuery

Matches all documents (namespace and document type). This query comes in handy if you just want to filter a search result or really do not have any constraints.

### NestedQuery

Allows you to query nested documents that are part of a larger document. Say, for example, that you have a main product with variations in one big document, and you want to constrain a search to main products that have variations that match multiple constraints.

A `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.

*   `path` (_string_, required) The path to the nested document.  
    Maximum length: 2048. Example: `order.shippingAddresses`.
*   `query` (_Query_, required)
*   `scoreMode` (_string_) Indicates how scores for matching child objects affect the root parent document’s relevance score.  
    Allowed values: `avg`, `total`, `max`, `none`. Example: `avg`.

_Example_

```
{
  "path": "order.shippingAddresses",
  "query": {
    "boolQuery": {
      "must": [
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.firstName"
                  ],
                  "operator": "is",
                  "values": [
                    "John"
                  ]
                }
              }
            ]
          }
        },
        {
          "boolQuery": {
            "must": [
              {
                "termQuery": {
                  "fields": [
                    "order.shippingAddresses.lastName"
                  ],
                  "operator": "is",
                  "values": [
                    "Doe"
                  ]
                }
              }
            ]
          }
        }
      ]
    }
  },
  "scoreMode": "avg"
}
```

### TermQuery

A term query matches one or more values against one or more document fields. A document is considered a hit if one of the values matches exactly with at least one of the given fields. The operator `is` can only take one value, while `one_of` can take multiple values. If multiple fields are specified, they are combined using a logical `OR` operator.

**Limitations:**

*   The `greater` and `less` operators are not supported under certain conditions. Both operators are permitted unless the API documentation states otherwise.
*   A subset of Commerce APIs handle queries with multiple fields differently. If the query has multiple fields, the query is internally handled as a logical `OR` of `DisjointMaxQueries` (with the dismax matching a value against all fields). The dismax makes sure that a document carrying a single term in multiple fields does not get higher scores than a document matching multiple terms in multiple fields.

*   `fields` (_array of Field_, required) The document fields that the values are matched against, combined with the operator.  
    Minimum items: 1.
*   `operator` (_string_, required) Returns the operator to use for the term query.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string | number | boolean | integer_) The values that the fields are compared against, combined with the operator.  
    Items: Example: `myCouponId`.

### TextQuery

A text query is used to match some text (for example, a search phrase possibly consisting of multiple terms) against one or more fields. When multiple fields are provided, the phrase conceptually forms a logical `OR` over the fields. In this case, the terms of the phrase basically have to match within the text, that would result in concatenating all given fields.

*   `fields` (_array of Field_, required) The document fields that the search phrase matches against.  
    Minimum items: 1.
*   `searchPhrase` (_string_, required) A search phrase, which can include multiple terms separated by spaces.  
    Example: `campaign summer`.

_Example_

```
{
  "fields": [
    "couponId"
  ],
  "searchPhrase": "limit"
}
```

### ObjectAttributeValueDefinition

An attribute definition value

*   `id` (_string_, read-only) The ID of the attribute value  
    Maximum length: 256. Example: `value-1`.
*   `value` (_string_, read-only) The value of the attribute  
    Maximum length: 4000. Example: `1`.
*   `displayValue` (_object_, read-only) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Localized value`.
    
    _Example_
    
    ```
    {
      "default": "One",
      "de": "Eins",
      "en": "One"
    }
    ```
    
*   `description` (_object_, read-only) B2C Commerce API - Localization doc: [https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html](https://developer.salesforce.com/docs/commerce/commerce-api/guide/b2c-localization.html)
    
    Additional properties: `string`.
    
    Localized string
    
    Maximum length: 4000. Example: `Localized value`.
    
    _Example_
    
    ```
    {
      "default": "Object type representing products.",
      "de": "Objekttyp, der Produkte repräsentiert.",
      "en": "Object type representing products."
    }
    ```
    
*   `position` (_number (double)_, read-only) The position of the attribute value within the set of attribute values  
    Example: `1`.

### Total

The total number of hits that match the search's criteria. This can be greater than the number of results returned as search results are pagenated.

Type: `integer (int32)`.

Default: `0`. Minimum: 0. Example: `10`.

### Filter

Contains a set of objects that define criteria used to select records. A filter can contain one of the following:

*   `TermFilter`

*   Matches records where a field (or fields) exactly matches some simple value (including `null`).

*   `RangeFilter`

*   Matches records where a field value lies within a specified range.

*   `Range2Filter`

*   Matches records in a specified range across fields.

*   `QueryFilter`

*   Matches records based on a query.

*   `BoolFilter`

*   Provides filtering of records using a set of filters combined using a logical operator.

Minimum properties: 1. Maximum properties: 1.

*   `boolFilter` (_BoolFilter_)
*   `queryFilter` (_QueryFilter_)
*   `range2Filter` (_Range2Filter_)
*   `rangeFilter` (_RangeFilter_)
*   `termFilter` (_TermFilter_)

### Field

Name of the field. Might be a custom field name prefixed with c\_.

Type: `string`.

Maximum length: 260. Example: `couponId`.

### BoolFilter

Allows you to combine other filters into (possibly recursive) logical expression trees. A boolean filter is composed of a logical operator (`AND`, `OR`, `NOT`) and a list of filters that the operator relates to. Multiple filters can be negated with a single `NOT` operator, even when the filters are combined with the `AND` operator.

*   `filters` (_array of Filter_) A list of filters that are logically combined by an operator.
*   `operator` (_string_, required) The logical operator that is used to combine the filters.  
    Allowed values: `and`, `or`, `not`. Example: `and`.

_Example_

```
{
  "operator": "and",
  "filters": [
    {
      "termFilter": {
        "field": "id",
        "operator": "is",
        "values": [
          "myId"
        ]
      }
    },
    {
      "termFilter": {
        "field": "couponId",
        "operator": "is",
        "values": [
          "couponOne"
        ]
      }
    }
  ]
}
```

### QueryFilter

Wraps any query and allows it to be used as a filter.

*   `query` (_Query_, required)

### Range2Filter

Allows you to restrict a search result to hits where a range defined by specified attributes has a certain relationship to a specified range.

The first range (R1) is defined by a pair of attributes (`fromField` and `toField`) that specify the extent of a range, such as attributes `validFrom` and `validTo`.

The second range (R2) is defined by `fromValue` and `toValue`.

The filter mode specifies the method used to compare the two ranges:

*   `overlap`: R1 overlaps fully or partially with R2.
*   `containing`: R1 contains R2.
*   `contained`: R1 is contained in R2.

The range filter supports several value types, and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range 2 filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `filterMode` (_string_) Compare mode: overlap, containing, or contained.  
    Allowed values: `overlap`, `containing`, `contained`. Default: `overlap`. Example: `overlap`.
*   `fromField` (_object_, required) The field name of the field that starts the first range.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `fromValue` (_any_) The lower bound of the second range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.  
    Example: `2007-01-01T00:00:00.000Z`.
*   `toField` (_object_, required) The field name of the field that ends the first range.  
    Example: `validTo`.
    
    Includes all fields of `Field`.
    
    Example: `validTo`.
    
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `toValue` (_any_) The upper bound of the second range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.  
    Example: `2017-01-01T00:00:00.000Z`.

_Example_

```
{
  "fromField": "validFrom",
  "toField": "validTo",
  "filterMode": "overlap",
  "fromValue": "2007-01-01T00:00:00.000Z",
  "toValue": "2017-01-01T00:00:00.000Z"
}
```

### RangeFilter

Allows you to restrict a search result to hits that have values for a given attribute that fall within a given value range. The range filter supports several value types and relies on the natural sorting of the value type for range interpretation. Value ranges can be open-ended, but only at one end of the range. You can configure whether the lower bounds and upper bounds are inclusive or exclusive.

A range filter is useful for general restrictions that can be shared between searches (like a static date range) because the filter result is cached in memory. Range filters are not appropriate if the range is expected to be different for every query (for example, if the user controls the date range down to the hour via a UI control). Range filters are inclusive by default.

*   `field` (_object_, required) The search field.  
    Example: `validFrom`.
    
    Includes all fields of `Field`.
    
    Example: `validFrom`.
    
*   `from` (_string (date-time) | integer | number_) The lower bound of the filter range. If not specified, the range is open-ended with respect to the lower bound. You can't leave both the lower and upper bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-01T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `1`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `1`.
        
*   `fromInclusive` (_boolean_) A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.
*   `to` (_string (date-time) | integer | number_) The upper bound of the filter range. If not specified, the range is open-ended with respect to the upper bound. You can't leave both the upper and lower bounds open-ended.
    
    One of: `string (date-time)`, `integer`, `number`.
    
    *   _string (date-time)_
        
        Type: `string (date-time)`.
        
        Example: `2007-01-02T00:00:00.000Z`.
        
    *   _integer_
        
        Type: `integer`.
        
        Example: `2`.
        
    *   _number_
        
        Type: `number`.
        
        Example: `2`.
        
*   `toInclusive` (_boolean_) A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.  
    Default: `true`. Example: `true`.

### TermFilter

Allows you to restrict a search result to hits that match exactly one of the values configured for the filter. A term filter is useful for general restrictions that can be shared between searches. Use term filters whenever the criteria you filter on is a shared property of multiple searches (for example, like filtering by an order status). Use term filters for fields that have a discrete and small set of values only.

*   `field` (_object_, required) The filter field.
    
    Includes all fields of `Field`.
    
*   `operator` (_string_, required) The operator used to compare the field's values with the given values.  
    Allowed values: `is`, `one_of`, `is_null`, `is_not_null`, `less`, `greater`, `not_in`, `neq`. Example: `is`.
*   `values` (_array of string_) The filter values.  
    Items: Example: `myId`.

_Example_

```
{
  "field": "id",
  "operator": "is",
  "values": [
    "myId"
  ]
}
```