Salesforce B2C Commerce 24.7 > Open Commerce API 23.2 > Data API resources 23.2

SitePreferences resource (Data API 23.2)

Summary

Http Method Resource Description
POST /site_preferences/preference_groups/{group_id}/{instance_type}/preference_search

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:

  • id - String
  • display_name - Localized String
  • description - Localized String
  • value_type* - one of {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}

* value_type can only be joined with other attributes using a conjunction (AND).

Note that only searchable attributes can be used in sorting.
GET /site_preferences/preference_groups/{group_id}/{instance_type}/preferences/{preference_id} Get a preference across sites in the specified preference group and instance.

Search Preferences

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:

  • id - String
  • display_name - Localized String
  • description - Localized String
  • value_type* - one of {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}

* value_type can only be joined with other attributes using a conjunction (AND).

Note that only searchable attributes can be used in sorting.

Url

POST https://hostname:port/dw/data/v23_2/site_preferences/preference_groups/{group_id}/{instance_type}/preference_search?mask_passwords={Boolean}&expand={String}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

SearchRequest

Response Document

PreferenceValueSearchResult

Path Parameters

Parameter Type Description Constraints
group_id String The ID of the preference group.  
instance_type String An instance type, one of {staging,development,sandbox,production}.  

Query Parameters

Parameter Type Description Constraints
expand String The expand "value" is available to retrieve value definitions of the attribute definition.  
mask_passwords Boolean The preference values of type Password are masked when set.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 MalformedSearchParameterException   Indicates the query is ill-formed.
404 CustomPreferenceGroupNotFoundException

preferenceGroupId (String)

 Indicates the preference group is not found.

Sample

POST /s/-/dw/data/v23_2/site_preferences/preference_groups/MyPreferenceGroup/staging/preference_search?expand=value HTTP/1.1
Host: example.com
Authorization: Bearer aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa

{
   "query": {
       "bool_query": {
           "must" : [
               {"text_query": { "fields": ["id"], "search_phrase": "EnumOfStringValue" } }
           ]
       }
   },
   "select": "(**)"
}

# in case of success:
{
  "_v" : "23.2",
  "_type": "preference_value_search_result",
  "count": 1,
  "hits": [
    {
      "_type": "preference_value",
      "attribute_definition": {
          "_type": "object_attribute_definition",
          "_resource_state": "8c1c9727e0c289dde4121a2335b0de85957b8b6d87e2bffdbe01fb6db6a2aa1f",
          "description": {
            "default": "Enum Of String Attribute"
          },
          "display_name": {
            "default": "Enum Of String Attribute"
          },
          "effective_id": "c_EnumOfStringAttr",
          "externally_defined": false,
          "externally_managed": false,
          "id": "EnumOfStringAttr",
          "key": false,
          "link": "https://example.com/s/-/dw/data/v23_2/system_object_definitions/SitePreferences/attribute_definitions/EnumOfStringAttr",
          "localizable": false,
          "mandatory": false,
          "min_length": 0,
          "multi_value_type": false,
          "order_required": false,
          "queryable": true,
          "read_only": false,
          "requires_encoding": false,
          "searchable": false,
          "set_value_type": false,
          "site_specific": false,
          "system": false,
          "value_definitions": [
            {
              "_type": "object_attribute_value_definition",
              "display_value": {
                "default": "Enum Of String Value 1"
              },
              "id": "EnumOfStringValue1",
              "position": 0.0,
              "value": "EnumOfStringValue1"
            },
            {
              "_type": "object_attribute_value_definition",
              "display_value": {
                "default": "Enum Of String Value 2"
              },
              "id": "EnumOfStringValue2",
              "position": 1.0,
              "value": "EnumOfStringValue2"
            },
            {
              "_type": "object_attribute_value_definition",
              "display_value": {
                "default": "Enum Of String Value 3"
              },
              "id": "EnumOfStringValue3",
              "position": 2.0,
              "value": "EnumOfStringValue3"
            }
          ],
          "value_type": "enum_of_string",
          "visible": false
        },
        "id": "EnumOfStringAttr",
        "site_values": {
            "SiteGenesis": "EnumOfStringValue1",
            "SiteGenesis-Customization": "EnumOfStringValue2"
        }
      }
  ],
  "query": {
    "bool_query": {
      "_type": "bool_query",
      "must": [
        {
          "text_query": {
            "_type": "text_query",
            "fields": [
              "id"
            ],
            "search_phrase": "EnumOfStringAttr"
          }
        }
      ]
    }
  },
  "select": "(**)",
  "start": 0,
  "total": 1
}

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
ETag: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "fault":{
    "type":"PreferenceGroupNotFoundException",
    "message":"No preference group with ID 'MyPreferenceGroup' was found."
  }
}

Get Preference

Get a preference across sites in the specified preference group and instance.

Url

GET https://hostname:port/dw/data/v23_2/site_preferences/preference_groups/{group_id}/{instance_type}/preferences/{preference_id}?mask_passwords={Boolean}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

PreferenceValue

Path Parameters

Parameter Type Description Constraints
group_id String The ID of the preference group.  
instance_type String An instance type, one of {staging,development,sandbox,production}.  
preference_id String The ID of the preference to retrieve. mandatory=true, minLength=1, nullable=false

Query Parameters

Parameter Type Description Constraints
mask_passwords Boolean The preference values of type Password are masked when set.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CustomPreferenceGroupNotFoundException

preferenceGroupId (String)

 Indicates the preference group is not found.
404 PreferenceNotFoundException

preferenceId (String)

 Indicates the preference is not found.

Sample

GET /s/-/dw/data/v23_2/site_preferences/preference_groups/MyPreferenceGroup/staging/preferences/StringPreference HTTP/1.1
Host: example.com
Authorization: Bearer aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa

# in case of success:
{
   "_v" : "23.2",
   "_type" : "organization_preferences",
   "link" : "https://example.com/s/-/dw/data/v23_2/site_preferences/preference_groups/MyPreferenceGroup/staging/preferences/StringPreference",
   "site_preferences" : 
   [
      {
         "_type" : "site_preferences",
         "link" : "https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/site_preferences/preference_groups/MyPreferenceGroup/staging",
         "site" : 
         {
            "_type" : "site",
            "customer_list_link" : 
            {
               "_type" : "customer_list_link",
               "customer_list_id" : "SiteGenesis",
               "link" : "https://example.com/s/-/dw/data/v23_2/customer_lists/SiteGenesis"
            },
            "display_name" : 
            {
               "default" : "SiteGenesis"
            },
            "id" : "SiteGenesis",
            "in_deletion" : false,
            "link" : "https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis",
            "storefront_status" : "online"
         }
      },
      
      {
         "_type" : "site_preferences",
         "link" : "https://example.com/s/-/dw/data/v23_2/sites/SiteGenesisGlobal/site_preferences/preference_groups/MyPreferenceGroup/staging",
         "site" : 
         {
            "_type" : "site",
            "customer_list_link" : 
            {
               "_type" : "customer_list_link",
               "customer_list_id" : "SiteGenesis",
               "link" : "https://example.com/s/-/dw/data/v23_2/customer_lists/SiteGenesis"
            },
            "display_name" : 
            {
               "default" : "SiteGenesisGlobal"
            },
            "id" : "SiteGenesisGlobal",
            "in_deletion" : false,
            "link" : "https://example.com/s/-/dw/data/v23_2/sites/SiteGenesisGlobal",
            "storefront_status" : "online"
         }
      }
   ],
   "c_StringPreference" : "String Preference"
}

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
ETag: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "fault":{
    "type":"PreferenceGroupNotFoundException",
    "message":"No preference group with ID 'MyPreferenceGroup' was found."
  }
}

Infocenter Retirement: On June 30, 2023, the Infocenter was retired, and documentation currently hosted on the Infocenter will be published to Salesforce Help, Commerce Cloud Developer Center, and Salesforce B2C Commerce Developer Documentation Resources. For more information, see the release note.

X OCAPI versions 15.x and 16.x will be retired on March 31, 2021. For dates and more information, see the OCAPI versioning and deprecation policy and this Knowledge Article.