openapi: 3.0.3
info:
x-api-type: Admin
x-api-family: Configuration
title: Preferences
version: 1.2.2
description: "[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/preferences/preferences-oas-v1-public.yaml)\n\n# API Overview\nB2C 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.\n\nThe following Preferences API endpoints retrieve preference-related information:\n\n- Global custom preferences: \nRetrieves all custom preferences at the organization level. \n\n- Site custom prefererences: \nRetrieves all custom preferences at the site level.\n\nThe 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.\n\nNote: 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).\n\n## Authentication & Authorization\n\nFor 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.\n\nYou 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)\n\nFor detailed setup instructions, see the [Authorization for Admin APIs guide.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html)\n\n## Use Cases\n### Global Custom Preference:\nA 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.\n\n### Site Custom Preference: \nSite 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.\n\n### Caching\nCaching 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)"
servers:
- url: https://{shortCode}.api.commercecloud.salesforce.com/configuration/preferences/v1
variables:
shortCode:
default: shortCode
paths:
/organizations/{organizationId}/global-custom-preferences:
get:
summary: Retrieves the Global Custom Preferences.
operationId: getGlobalCustomPreferenceList
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/maskPassword'
- name: limit
in: query
required: false
schema:
type: integer
format: int32
default: 200
minimum: 1
maximum: 200
description: Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 200.
- name: offset
in: query
required: false
schema:
type: integer
format: int32
default: 0
minimum: 0
description: Used to retrieve the results based on a particular resource offset.
responses:
'200':
description: Retrieved Global Custom Preferences successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomPreferenceList'
examples:
GlobalCustomPreferenceExample:
$ref: '#/components/examples/GlobalCustomPreferenceExample'
'400':
description: Thrown if the query is ill-formed.
'401':
description: |
Unauthorized. Your Client ID is invalid, or you are not allowed to access
the content provided by the requested URL.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
InvalidAccessToken:
$ref: '#/components/examples/InvalidAccessToken'
security:
- AmOAuth2:
- sfcc.preferences
- sfcc.preferences.rw
/organizations/{organizationId}/site-custom-preferences:
get:
summary: Retrieves the Custom Preferences for a specified siteId.
operationId: getSiteCustomPreferenceList
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/maskPassword'
- $ref: '#/components/parameters/siteId'
- name: limit
in: query
required: false
schema:
type: integer
format: int32
default: 200
minimum: 1
maximum: 200
description: Number of records to retrieve per request. Must be between 1 (minimum) and 200 (maximum). Defaults to 200.
- name: offset
in: query
required: false
schema:
type: integer
format: int32
default: 0
minimum: 0
description: Used to retrieve the results based on a particular resource offset.
responses:
'200':
description: Retrieved Site Custom Preferences successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/CustomPreferenceList'
examples:
SiteCustomPreferenceExample:
$ref: '#/components/examples/SiteCustomPreferenceExample'
'400':
description: Thrown if the query is ill-formed.
'401':
description: |
Unauthorized. Your Client ID is invalid, or you are not allowed to access
the content provided by the requested URL.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
InvalidAccessToken:
$ref: '#/components/examples/InvalidAccessToken'
security:
- AmOAuth2:
- sfcc.preferences
- sfcc.preferences.rw
/organizations/{organizationId}/global-preference-groups/{groupId}/{instanceType}:
get:
summary: Read the custom preferences in a global preference group for a given instance type.
description: |
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.
operationId: getGlobalPreferenceGroup
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/groupId'
- $ref: '#/components/parameters/instanceType'
- $ref: '#/components/parameters/maskPasswords'
- $ref: '#/components/parameters/globalPreferenceGroupExpand'
responses:
'200':
description: Custom preferences retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationPreferences'
examples:
GetGlobalPreferencesExample:
$ref: '#/components/examples/GetGlobalPreferencesExample'
GetGlobalPreferencesWithSitesExample:
$ref: '#/components/examples/GetGlobalPreferencesWithSitesExample'
'400':
description: Invalid instance type was provided.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
IllegalEnumerationValue:
$ref: '#/components/examples/IllegalEnumerationValue'
'404':
description: The preference group was not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
CustomPreferenceGroupNotFound:
$ref: '#/components/examples/CustomPreferenceGroupNotFound'
security:
- AmOAuth2:
- sfcc.preferences
- sfcc.preferences.rw
patch:
summary: Update the custom preferences in a global preference group for a given instance type.
description: |
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.
operationId: updateGlobalPreferenceGroup
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/groupId'
- $ref: '#/components/parameters/instanceType'
- $ref: '#/components/parameters/maskPasswords'
requestBody:
description: |
The preferences to update. Custom preference attributes use the "c_" prefix.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationPreferences'
examples:
UpdateGlobalPreferencesRequest:
$ref: '#/components/examples/UpdateGlobalPreferencesRequest'
responses:
'200':
description: Custom preferences updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationPreferences'
examples:
UpdateGlobalPreferencesExample:
$ref: '#/components/examples/UpdateGlobalPreferencesExample'
'400':
description: Invalid instance type was provided.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
IllegalEnumerationValue:
$ref: '#/components/examples/IllegalEnumerationValue'
'404':
description: The preference group was not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
CustomPreferenceGroupNotFound:
$ref: '#/components/examples/CustomPreferenceGroupNotFound'
security:
- AmOAuth2:
- sfcc.preferences.rw
/organizations/{organizationId}/site-preference-groups/{groupId}/{instanceType}:
get:
summary: Read the custom preferences in a site preference group for a given instance type.
description: |
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.
operationId: getSitePreferenceGroup
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/groupId'
- $ref: '#/components/parameters/instanceType'
- $ref: '#/components/parameters/maskPasswords'
- $ref: '#/components/parameters/siteId'
responses:
'200':
description: Custom site preferences retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SitePreferences'
examples:
GetSitePreferencesExample:
$ref: '#/components/examples/GetSitePreferencesExample'
'400':
description: Invalid instance type was provided.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
IllegalEnumerationValue:
$ref: '#/components/examples/IllegalEnumerationValue'
'404':
description: The preference group was not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
CustomPreferenceGroupNotFound:
$ref: '#/components/examples/CustomPreferenceGroupNotFound'
security:
- AmOAuth2:
- sfcc.preferences
- sfcc.preferences.rw
patch:
summary: Update the custom preferences in a site preference group for a given instance type.
description: |
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.
operationId: updateSitePreferenceGroup
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/groupId'
- $ref: '#/components/parameters/instanceType'
- $ref: '#/components/parameters/maskPasswords'
- $ref: '#/components/parameters/siteId'
requestBody:
description: |
The site preferences to update. Custom preference attributes use the "c_" prefix.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SitePreferences'
examples:
UpdateSitePreferencesRequest:
$ref: '#/components/examples/UpdateSitePreferencesRequest'
responses:
'200':
description: Custom site preferences updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SitePreferences'
examples:
UpdateSitePreferencesExample:
$ref: '#/components/examples/UpdateSitePreferencesExample'
'400':
description: Invalid instance type was provided.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
IllegalEnumerationValue:
$ref: '#/components/examples/IllegalEnumerationValue'
'404':
description: The preference group was not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
CustomPreferenceGroupNotFound:
$ref: '#/components/examples/CustomPreferenceGroupNotFound'
security:
- AmOAuth2:
- sfcc.preferences.rw
/organizations/{organizationId}/site-preference-groups/{groupId}/{instanceType}/preference-search:
post:
summary: Search preferences across sites in a preference group for a given instance type.
description: |
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.
operationId: searchSitePreferences
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/groupId'
- $ref: '#/components/parameters/instanceType'
- $ref: '#/components/parameters/maskPasswords'
- $ref: '#/components/parameters/preferenceSearchExpand'
requestBody:
description: The search request document.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
examples:
SearchSitePreferencesRequest:
$ref: '#/components/examples/SearchSitePreferencesRequest'
responses:
'200':
description: Preference search executed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PreferenceValueSearchResult'
examples:
PreferenceSearchExample:
$ref: '#/components/examples/PreferenceSearchExample'
PreferenceSearchWithExpandValueExample:
$ref: '#/components/examples/PreferenceSearchWithExpandValueExample'
'400':
description: |
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.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
IllegalEnumerationValue:
$ref: '#/components/examples/IllegalEnumerationValue'
FieldNotSortable:
$ref: '#/components/examples/FieldNotSortable'
'404':
description: The preference group was not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
CustomPreferenceGroupNotFound:
$ref: '#/components/examples/CustomPreferenceGroupNotFound'
security:
- AmOAuth2:
- sfcc.preferences
- sfcc.preferences.rw
/organizations/{organizationId}/site-preference-groups/{groupId}/{instanceType}/preferences/{preferenceId}:
get:
summary: Read a single preference value across sites in a preference group for a given instance type.
description: |
Read a specific preference value identified by its ID within the given preference group
and instance type. Returns the preference value for all sites.
operationId: getSitePreference
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/groupId'
- $ref: '#/components/parameters/instanceType'
- $ref: '#/components/parameters/preferenceId'
- $ref: '#/components/parameters/maskPasswords'
responses:
'200':
description: Preference value retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PreferenceValue'
examples:
GetPreferenceValueExample:
$ref: '#/components/examples/GetPreferenceValueExample'
GetPreferenceValueMultiSiteExample:
$ref: '#/components/examples/GetPreferenceValueMultiSiteExample'
'400':
description: Invalid instance type was provided.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
IllegalEnumerationValue:
$ref: '#/components/examples/IllegalEnumerationValue'
'404':
description: The preference group or preference was not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
CustomPreferenceGroupNotFound:
$ref: '#/components/examples/CustomPreferenceGroupNotFound'
PreferenceNotFound:
$ref: '#/components/examples/PreferenceNotFound'
security:
- AmOAuth2:
- sfcc.preferences
- sfcc.preferences.rw
patch:
summary: Update a single preference value across sites in a preference group for a given instance type.
description: |
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.
operationId: updateSitePreference
parameters:
- $ref: '#/components/parameters/organizationId'
- $ref: '#/components/parameters/groupId'
- $ref: '#/components/parameters/instanceType'
- $ref: '#/components/parameters/preferenceId'
- $ref: '#/components/parameters/maskPasswords'
requestBody:
description: The preference value to update with site-specific values.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PreferenceValue'
examples:
UpdateSitePreferenceValueRequest:
$ref: '#/components/examples/UpdateSitePreferenceValueRequest'
responses:
'200':
description: Preference value updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PreferenceValue'
examples:
UpdatePreferenceValueExample:
$ref: '#/components/examples/UpdatePreferenceValueExample'
'400':
description: Invalid instance type was provided.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
IllegalEnumerationValue:
$ref: '#/components/examples/IllegalEnumerationValue'
'404':
description: The preference group or preference was not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
CustomPreferenceGroupNotFound:
$ref: '#/components/examples/CustomPreferenceGroupNotFound'
PreferenceNotFound:
$ref: '#/components/examples/PreferenceNotFound'
security:
- AmOAuth2:
- sfcc.preferences.rw
components:
securitySchemes:
AmOAuth2:
type: oauth2
description: AccountManager OAuth 2.0 bearer token Authentication.
flows:
clientCredentials:
tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
scopes:
sfcc.preferences: Preferences read scope
sfcc.preferences.rw: Preferences read/write scope
authorizationCode:
authorizationUrl: https://account.demandware.com/dwsso/oauth2/authorize
tokenUrl: https://account.demandware.com/dwsso/oauth2/access_token
scopes:
sfcc.preferences: Preferences read scope
sfcc.preferences.rw: Preferences read/write scope
schemas:
OrganizationId:
description: 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
type: string
pattern: ^f_ecom_[a-z]{4}_(prd|stg|dev|s[0-9]{2}|[0-9]{3})$
Total:
default: 0
minimum: 0
format: int32
description: 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
example: 10
ResultBase:
description: "Schema defining generic list result. Each response schema of a resource requiring a list response should extend this schema. \nAdditionally it needs to be defined what data is returned."
type: object
required:
- limit
- total
properties:
limit:
format: int32
description: 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.
type: integer
example: 10
total:
$ref: '#/components/schemas/Total'
Offset:
default: 0
minimum: 0
format: int32
description: The zero-based index of the first hit/data to include in the result.
type: integer
example: 0
PaginatedResultBase:
description: "Schema defining generic pageable result. Each response schema of a resource requiring pagination should extend this schema. \nIf you use this extend this schema directly, it needs to be defined what data is returned. Allowed names for the data field is `data`."
type: object
allOf:
- $ref: '#/components/schemas/ResultBase'
properties:
offset:
$ref: '#/components/schemas/Offset'
required:
- limit
- offset
- total
CustomPreference:
description: Preference object
properties:
groupId:
description: The ID of the preference group.
type: string
id:
description: The Preference Id.
type: string
value:
description: The value for the Preference Id.
required:
- groupId
- id
- value
type: object
CustomPreferenceList:
description: Document representing a Custom Preference result.
allOf:
- $ref: '#/components/schemas/PaginatedResultBase'
properties:
data:
description: The list of custom preferences in the search result.
type: array
items:
$ref: '#/components/schemas/CustomPreference'
required:
- limit
- data
- offset
- total
type: object
ErrorResponse:
type: object
additionalProperties: true
properties:
title:
description: "A short, human-readable summary of the problem\ntype. It will not change from occurrence to occurrence of the \nproblem, except for purposes of localization\n"
type: string
maxLength: 256
example: You do not have enough credit
type:
description: |
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.
type: string
maxLength: 2048
example: NotEnoughMoney
detail:
description: A human-readable explanation specific to this occurrence of the problem.
type: string
example: Your current balance is 30, but that costs 50
instance:
description: |
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.
type: string
maxLength: 2048
example: /account/12345/msgs/abc
required:
- title
- type
- detail
SiteId:
minLength: 1
maxLength: 32
description: 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: RefArch
type: string
CustomerListLink:
type: object
description: Document representing a link to a customer list.
properties:
customerListId:
type: string
minLength: 1
maxLength: 256
description: The customer list identifier
example: customer-list-1
title:
type: string
maxLength: 256
description: The title of the customer list link
example: Default Customer List
Site:
type: object
required:
- id
properties:
id:
title: ID
description: The ID of the site.
allOf:
- $ref: '#/components/schemas/SiteId'
displayName:
type: object
additionalProperties:
type: string
description: Localized string
example: Site Display Name
maxLength: 4000
description:
type: object
additionalProperties:
type: string
description: Localized string
example: Site Description
maxLength: 4000
customerListLink:
description: The link to the customer list
allOf:
- $ref: '#/components/schemas/CustomerListLink'
inDeletion:
type: boolean
description: Specifies whether the site status is in deletion (true) or not (false)
example: false
storefrontStatus:
type: string
description: Status of the storefront
enum:
- online
- maintenance
- to_be_deleted
- protected
example: online
siteCatalogId:
type: string
minLength: 1
maxLength: 256
description: The catalog bound to the given site.
example: storefront-catalog-m-en
cartridges:
type: string
maxLength: 4000
description: The cartridge names assigned to a site delemited by ':'.
example: app_storefront_core:app_storefront_base
creationDate:
type: string
format: date-time
description: The timestamp when the site was created.
example: '2024-01-15T10:00:00.000Z'
lastModified:
type: string
format: date-time
description: The timestamp when the site was last modified.
example: '2024-10-14T15:30:00.000Z'
SitePreferences:
description: |
Represents custom preferences at the site level within a preference group. Custom preference attributes are returned with the "c_" prefix.
type: object
properties:
site:
$ref: '#/components/schemas/Site'
additionalProperties: true
OrganizationPreferences:
description: |
Represents custom preferences at the global (organization) level within a preference group. Custom preference attributes are returned with the "c_" prefix.
type: object
properties:
sitePreferences:
description: The list of site-specific preferences, returned when expand=sites.
type: array
items:
$ref: '#/components/schemas/SitePreferences'
additionalProperties: true
Query:
minProperties: 1
maxProperties: 1
description: |-
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._
example:
filteredQuery:
query:
textQuery:
fields:
- couponId
searchPhrase: disabled
filter:
termFilter:
field: enabled
operator: is
values:
- false
type: object
properties:
boolQuery:
$ref: '#/components/schemas/BoolQuery'
filteredQuery:
$ref: '#/components/schemas/FilteredQuery'
matchAllQuery:
$ref: '#/components/schemas/MatchAllQuery'
nestedQuery:
$ref: '#/components/schemas/NestedQuery'
termQuery:
$ref: '#/components/schemas/TermQuery'
textQuery:
$ref: '#/components/schemas/TextQuery'
additionalProperties: false
BoolQuery:
description: "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:\n \n - `must`, which combines as an `AND` operator.\n - `should`, which combines as an `OR` operator.\n - `must_not`, which combines as a `NOT` operator.\n \nIf `must`, `mustNot`, or `should` appear in the same boolean query, they are combined logically using the `AND` operator. For example:\n\n (must-1 AND must-1 AND ...)\n AND (should-1 OR should-2 OR ...)\n AND NOT (must_not-1 OR must_not-2 OR ...)\n"
type: object
example:
value:
must:
- textQuery:
fields:
- couponId
searchPhrase: DEAL
- textQuery:
fields:
- description
searchPhrase: Big bargain deal
mustNot:
- termQuery:
fields:
- enabled
operator: is
values:
- false
properties:
must:
description: List of queries to be evaluated as an `AND` operator.
type: array
items:
$ref: '#/components/schemas/Query'
mustNot:
description: List of queries to be evaluated as a `NOT` operator.
type: array
items:
$ref: '#/components/schemas/Query'
should:
description: List of queries to be evaluated as an `OR` operator.
type: array
items:
$ref: '#/components/schemas/Query'
additionalProperties: false
Filter:
minProperties: 1
maxProperties: 1
description: |-
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.
example: null
type: object
properties:
boolFilter:
$ref: '#/components/schemas/BoolFilter'
queryFilter:
$ref: '#/components/schemas/QueryFilter'
range2Filter:
$ref: '#/components/schemas/Range2Filter'
rangeFilter:
$ref: '#/components/schemas/RangeFilter'
termFilter:
$ref: '#/components/schemas/TermFilter'
additionalProperties: false
BoolFilter:
description: 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.
example:
value:
operator: and
filters:
- termFilter:
field: id
operator: is
values:
- myId
- termFilter:
field: couponId
operator: is
values:
- couponOne
type: object
properties:
filters:
description: A list of filters that are logically combined by an operator.
type: array
items:
$ref: '#/components/schemas/Filter'
operator:
description: The logical operator that is used to combine the filters.
enum:
- and
- or
- not
type: string
example: and
required:
- operator
additionalProperties: false
QueryFilter:
description: Wraps any query and allows it to be used as a filter.
type: object
properties:
query:
$ref: '#/components/schemas/Query'
required:
- query
Field:
description: Name of the field. Might be a custom field name prefixed with c_.
maxLength: 260
type: string
example: couponId
Range2Filter:
description: |-
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.
example:
fromField: validFrom
toField: validTo
filterMode: overlap
fromValue: '2007-01-01T00:00:00.000Z'
toValue: '2017-01-01T00:00:00.000Z'
type: object
properties:
filterMode:
default: overlap
example: overlap
description: 'Compare mode: overlap, containing, or contained.'
enum:
- overlap
- containing
- contained
type: string
fromField:
description: The field name of the field that starts the first range.
example: validFrom
allOf:
- $ref: '#/components/schemas/Field'
fromInclusive:
default: true
example: true
description: A flag indicating if the lower bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.
type: boolean
fromValue:
description: 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:
description: The field name of the field that ends the first range.
example: validTo
allOf:
- $ref: '#/components/schemas/Field'
toInclusive:
default: true
example: true
description: A flag indicating if the upper bound of the second range is inclusive. To make the lower bound exclusive, set to `false`.
type: boolean
toValue:
description: 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'
required:
- fromField
- toField
additionalProperties: false
RangeFilter:
description: |-
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.
type: object
properties:
field:
example: validFrom
description: The search field.
allOf:
- $ref: '#/components/schemas/Field'
from:
oneOf:
- type: string
format: date-time
example: '2007-01-01T00:00:00.000Z'
- type: integer
example: 1
- type: number
example: 1
description: 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.
fromInclusive:
default: true
example: true
description: A flag indicating if the lower bound of the range is inclusive. To make the lower bound exclusive, set to `false`.
type: boolean
to:
oneOf:
- type: string
format: date-time
example: '2007-01-02T00:00:00.000Z'
- type: integer
example: 2
- type: number
example: 2
description: 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.
toInclusive:
default: true
example: true
description: A flag indicating if the upper bound of the range is inclusive. To make the upper bound exclusive, set to `false`.
type: boolean
required:
- field
TermFilter:
description: 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.
example:
field: id
operator: is
values:
- myId
type: object
properties:
field:
description: The filter field.
allOf:
- $ref: '#/components/schemas/Field'
operator:
description: The operator used to compare the field's values with the given values.
example: is
enum:
- is
- one_of
- is_null
- is_not_null
- less
- greater
- not_in
- neq
type: string
values:
description: The filter values.
type: array
items:
type: string
example: myId
required:
- field
- operator
additionalProperties: false
FilteredQuery:
description: Allows to filter the result of a possibly complex query using a possibly complex filter.
example:
query:
textQuery:
fields:
- couponId
searchPhrase: disabled
filter:
termFilter:
field: enabled
operator: is
values:
- false
type: object
properties:
filter:
$ref: '#/components/schemas/Filter'
query:
$ref: '#/components/schemas/Query'
required:
- filter
- query
additionalProperties: false
MatchAllQuery:
description: 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.
type: object
NestedQuery:
description: "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. \n\nA `NestedQuery` is only supported by some Commerce APIs. For more details, see the endpoint descriptions in the API documentation.\n"
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
type: object
properties:
path:
description: The path to the nested document.
type: string
example: order.shippingAddresses
maxLength: 2048
query:
$ref: '#/components/schemas/Query'
scoreMode:
description: Indicates how scores for matching child objects affect the root parent document’s relevance score.
enum:
- avg
- total
- max
- none
type: string
example: avg
required:
- path
- query
additionalProperties: false
TermQuery:
description: |-
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.
type: object
properties:
fields:
minItems: 1
description: The document fields that the values are matched against, combined with the operator.
type: array
items:
$ref: '#/components/schemas/Field'
operator:
description: Returns the operator to use for the term query.
enum:
- is
- one_of
- is_null
- is_not_null
- less
- greater
- not_in
- neq
type: string
example: is
values:
description: The values that the fields are compared against, combined with the operator.
type: array
items:
oneOf:
- type: string
example: myCouponId
- type: number
example: 1
- type: boolean
example: true
- type: integer
example: 1
example: myCouponId
required:
- fields
- operator
TextQuery:
description: 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.
example:
fields:
- couponId
searchPhrase: limit
type: object
properties:
fields:
minItems: 1
description: The document fields that the search phrase matches against.
type: array
items:
$ref: '#/components/schemas/Field'
searchPhrase:
description: A search phrase, which can include multiple terms separated by spaces.
type: string
example: campaign summer
required:
- fields
- searchPhrase
additionalProperties: false
Sort:
description: Document representing a sort request. Each API has a different default sort configuration that can be modified in the request.
example:
field: couponId
sortOrder: desc
type: object
properties:
field:
description: The name of the field to sort on.
type: string
maxLength: 256
example: couponId
sortOrder:
default: asc
description: The sort order to be applied when sorting. When omitted, the default sort order (asc) is used.
example: asc
enum:
- asc
- desc
type: string
required:
- field
additionalProperties: false
SearchRequest:
description: 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.
type: object
properties:
limit:
description: Maximum records to retrieve per request, not to exceed 200.
type: integer
format: int32
minimum: 1
example: 10
maximum: 200
query:
$ref: '#/components/schemas/Query'
sorts:
description: 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.
type: array
items:
$ref: '#/components/schemas/Sort'
offset:
$ref: '#/components/schemas/Offset'
required:
- query
PaginatedSearchResult:
description: Document representing a generic search result. Each search resource should extend this to define what is returned in the `hits`.
properties:
query:
$ref: '#/components/schemas/Query'
sorts:
description: The sorting that was applied to the result.
type: array
items:
$ref: '#/components/schemas/Sort'
hits:
description: The sorted array of search hits. Can be empty.
type: array
items:
type: object
allOf:
- $ref: '#/components/schemas/PaginatedResultBase'
type: object
required:
- query
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
additionalProperties: false
ValueType:
type: string
description: The type of an attribute value
enum:
- 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
ObjectAttributeValueDefinition:
type: object
description: An attribute definition value
properties:
id:
type: string
readOnly: true
maxLength: 256
description: The ID of the attribute value
example: value-1
value:
type: string
readOnly: true
maxLength: 4000
description: The value of the attribute
example: '1'
displayValue:
type: object
readOnly: true
additionalProperties:
type: string
maxLength: 4000
description: Localized string
example: Localized value
example:
default: One
de: Eins
en: One
description:
type: object
readOnly: true
additionalProperties:
type: string
maxLength: 4000
description: Localized string
example: Localized value
example:
default: Object type representing products.
de: Objekttyp, der Produkte repräsentiert.
en: Object type representing products.
position:
type: number
readOnly: true
format: double
description: The position of the attribute value within the set of attribute values
example: 1
ObjectAttributeDefinition:
type: object
description: Document representing an attribute definition
required:
- id
properties:
id:
type: string
minLength: 1
maxLength: 256
description: The user supplied ID of the attribute
example: color
effectiveId:
type: string
readOnly: true
maxLength: 256
description: The effective ID, which is c_id if the attribute is custom, and just the id otherwise
example: c_color
displayName:
type: object
additionalProperties:
type: string
maxLength: 4000
description: Localized string
example: Localized value
example:
default: Product
de: Produkt
en: Product
description:
type: object
additionalProperties:
type: string
maxLength: 4000
description: Localized string
example: Localized value
example:
default: Object type representing products.
de: Objekttyp, der Produkte repräsentiert.
en: Object type representing products.
key:
type: boolean
description: Flag indicating if this is a key attribute
example: false
mandatory:
type: boolean
description: Flag indicating if a value is mandatory for the attribute
example: false
localizable:
type: boolean
description: Flag indicating if this attribute can be localized
example: false
siteSpecific:
type: boolean
description: Flag indicating if this attribute is site-specific
example: false
searchable:
type: boolean
description: Flag indicating if this attribute is searchable
example: true
queryable:
type: boolean
readOnly: true
description: 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:
$ref: '#/components/schemas/ValueType'
visible:
type: boolean
description: Flag indicating if this attribute is visible
example: true
system:
type: boolean
description: Flag indicating if this attribute is a system attribute
example: false
unit:
type: object
additionalProperties:
type: string
maxLength: 4000
description: Localized string
example: Localized value
example:
default: General unit
de: Allgemeine Einheit
en: General unit
requiresEncoding:
type: boolean
readOnly: true
description: Flag indicating if this attribute can be encoded using the encoding='off' flag in ISML templates
example: false
multiValueType:
type: boolean
description: True if the attribute can have multiple values. Applicable to set_of_* and enum_of_* types.
example: false
setValueType:
type: boolean
readOnly: true
description: Flag indicating if this attribute is of type 'Set of'
example: false
externallyManaged:
type: boolean
description: Flag indicating if this attribute is externally managed
example: false
externallyDefined:
type: boolean
description: Flag indicating if this attribute is externally defined
example: false
orderRequired:
type: boolean
description: Flag indicating if this attribute is required for order of the attribute model's product
example: false
regularExpression:
type: string
readOnly: true
maxLength: 4000
description: A regular expression that defines the legal values for this attribute
example: ^[a-zA-Z]+$
fieldLength:
type: integer
readOnly: true
format: int32
description: The length of the field for this attribute in the editor
example: 50
fieldHeight:
type: integer
readOnly: true
format: int32
description: The height of the field for this attribute in the editor
example: 1
minLength:
type: integer
readOnly: true
format: int32
description: The minimum length of the field for this attribute
example: 1
readOnly:
type: boolean
readOnly: true
description: Flag indicating if this attribute is read-only
example: false
minValue:
type: number
readOnly: true
format: double
description: The minimum possible value for this attribute
example: 0
maxValue:
type: number
readOnly: true
format: double
description: The maximum possible value for this attribute
example: 100
scale:
type: integer
readOnly: true
format: int32
description: The minimum number of fraction digits for a value of this attribute
example: 2
defaultValue:
description: The default value of this attribute. It can be updated, but not created.
allOf:
- $ref: '#/components/schemas/ObjectAttributeValueDefinition'
valueDefinitions:
type: array
readOnly: true
items:
$ref: '#/components/schemas/ObjectAttributeValueDefinition'
description: A set of values that are possible for this attribute
creationDate:
type: string
readOnly: true
format: date-time
description: The date/time when the attribute definition was created
example: '2024-01-15T10:30:00Z'
lastModified:
type: string
readOnly: true
format: date-time
description: The date/time when the attribute definition was last modified
example: '2024-01-15T11:00:00Z'
PreferenceValue:
description: Represents a single preference value with its attribute definition and site-specific values.
type: object
properties:
id:
description: The preference attribute ID
type: string
minLength: 1
maxLength: 256
example: WapiStringAttr
description:
type: object
additionalProperties:
type: string
description: Localized string
example: Preference Description
maxLength: 4000
displayName:
type: object
additionalProperties:
type: string
description: Localized string
example: Preference Display Name
maxLength: 4000
attributeDefinition:
$ref: '#/components/schemas/ObjectAttributeDefinition'
siteValues:
description: A mapping of site IDs to their preference values.
type: object
additionalProperties: true
valueType:
$ref: '#/components/schemas/ValueType'
required:
- id
PreferenceValueSearchResult:
description: Document representing a preference value search result.
allOf:
- $ref: '#/components/schemas/PaginatedSearchResult'
properties:
hits:
description: The sorted array of search hits. Can be empty.
type: array
items:
$ref: '#/components/schemas/PreferenceValue'
type: object
parameters:
organizationId:
description: 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).
name: organizationId
in: path
required: true
example: f_ecom_zzxy_prd
schema:
$ref: '#/components/schemas/OrganizationId'
maskPassword:
name: maskPassword
in: query
description: Whether to mask password or not.
required: false
schema:
type: boolean
default: false
example: true
siteId:
description: 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.
name: siteId
in: query
required: true
examples:
SiteId:
value: RefArch
schema:
$ref: '#/components/schemas/SiteId'
groupId:
name: groupId
in: path
description: The preference group ID.
required: true
schema:
type: string
minLength: 1
maxLength: 256
example: WapiStringGroup
instanceType:
name: instanceType
in: path
description: The instance type for which to read or update preferences.
required: true
schema:
type: string
enum:
- staging
- development
- sandbox
- production
example: staging
example: staging
maskPasswords:
name: maskPasswords
in: query
description: The preference values of type Password are masked when set.
required: false
schema:
type: boolean
default: false
example: true
globalPreferenceGroupExpand:
name: expand
in: query
description: |
Expands the result document to include additional information. For global preference groups, the expansion "sites" retrieves the custom preferences for all the available sites.
required: false
schema:
type: array
items:
type: string
enum:
- sites
example: sites
style: form
explode: false
preferenceSearchExpand:
name: expand
in: query
description: |
Expands the result document to include additional information. For preference search, the expansion "value" retrieves the value definitions of the attribute definition.
required: false
schema:
type: array
items:
type: string
enum:
- value
example: value
style: form
explode: false
preferenceId:
name: preferenceId
in: path
description: The preference attribute ID.
required: true
schema:
type: string
minLength: 1
maxLength: 256
example: WapiStringAttr
examples:
GlobalCustomPreferenceExample:
value:
limit: 10
data:
- groupId: PreferenceGroup1
id: booleanValue
value: true
- groupId: PreferenceGroup1
id: htmlValue
value:
markup: HTML Value
source: HTML Value
- 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
InvalidAccessToken:
value:
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
SiteCustomPreferenceExample:
value:
limit: 10
data:
- groupId: PreferenceGroup1
id: booleanValue
value: true
- groupId: PreferenceGroup1
id: htmlValue
value:
markup: HTML Value
source: HTML Value
- 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
GetGlobalPreferencesExample:
summary: Global preferences with custom attributes.
value:
c_WapiStringAttr: MyString
c_WapiLocalizedStringAttr: MyLocalizedString
c_WapiSitespecificStringAttr: MySiteSpecificString
c_WapiSetOfStringAttr:
- value1
- value2
c_WapiEnumOfStringAttr: WapiEnumOfStringValue1
c_WapiEnumOfStringMSAttr:
- WapiEnumOfStringMSValue1
- WapiEnumOfStringMSValue2
GetGlobalPreferencesWithSitesExample:
summary: Global preferences with site-specific expansions.
value:
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
IllegalEnumerationValue:
value:
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
CustomPreferenceGroupNotFound:
value:
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
UpdateGlobalPreferencesRequest:
summary: Update global custom preferences.
value:
c_WapiStringAttr: UpdatedString
c_WapiIntAttr: 42
c_WapiBooleanAttr: true
c_WapiSetOfStringAttr:
- newValue1
- newValue2
UpdateGlobalPreferencesExample:
summary: Updated global preferences response.
value:
c_WapiStringAttr: UpdatedString
c_WapiLocalizedStringAttr: UpdatedLocalizedString
c_WapiSetOfStringAttr:
- newValue1
- newValue2
GetSitePreferencesExample:
summary: Site preferences with custom attributes.
value:
site:
id: RefArch
c_WapiStringAttr: MyString
c_WapiLocalizedStringAttr: MyLocalizedString
c_WapiPasswordAttr: '************'
UpdateSitePreferencesRequest:
summary: Update site custom preferences.
value:
c_WapiStringAttr: UpdatedString
c_WapiLocalizedStringAttr:
default: UpdatedLocalizedString
de-DE: AktualisierteLokalisierteZeichenkette
c_WapiIntAttr: 42
c_WapiBooleanAttr: true
c_WapiSetOfStringAttr:
- newValue1
- newValue2
UpdateSitePreferencesExample:
summary: Updated site preferences response.
value:
site:
id: RefArch
c_WapiStringAttr: UpdatedString
c_WapiLocalizedStringAttr: UpdatedLocalizedString
SearchSitePreferencesRequest:
summary: Search preferences by ID and value type.
value:
query:
boolQuery:
must:
- textQuery:
fields:
- id
searchPhrase: WapiString
- termQuery:
fields:
- valueType
operator: is
values:
- string
sorts:
- field: id
sortOrder: asc
limit: 25
offset: 0
PreferenceSearchExample:
summary: Search result for preferences across sites.
value:
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
PreferenceSearchWithExpandValueExample:
summary: Search result with expanded value definitions.
value:
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
FieldNotSortable:
value:
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
GetPreferenceValueExample:
summary: A single preference value.
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: []
GetPreferenceValueMultiSiteExample:
summary: A single preference value with multiple site values.
value:
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
PreferenceNotFound:
value:
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
UpdateSitePreferenceValueRequest:
summary: Update a preference value for multiple sites.
value:
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
UpdatePreferenceValueExample:
summary: Updated preference value response.
value:
id: WapiLocalizedStringAttr
displayName:
default: Localized String Attribute
description:
default: Localized String Attribute
siteValues:
RefArch: value for RefArch
RefArchGlobal: value for RefArchGlobal
valueType: string