openapi: 3.0.1
info:
title: Coveo Commerce API
description: API for Coveo Platform
termsOfService: https://www.coveo.com/en/support/terms-agreements
contact:
name: Coveo
url: https://connect.coveo.com/s/discussions
version: 1.0.0
servers:
- url: https://platform.cloud.coveo.com
description: Coveo public API endpoint
security:
- oauth2:
- full
paths:
/rest/organizations/{organizationId}/commerce/v2/tracking-ids/{trackingId}/facet/fields/bulk-update:
put:
tags:
- Facet Field Configurations
summary: Update Multiple Facet Fields
description: 'Updates multiple facet fields.Maximum 100 items per request.**Required privilege:** Merchandising
Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: path
description: The unique identifier of the tracking target.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: array
items:
oneOf:
- $ref: '#/components/schemas/ContinuousFacetFieldModel'
- $ref: '#/components/schemas/HierarchicalFacetFieldModel'
- $ref: '#/components/schemas/NumericalRangesFacetFieldModel'
- $ref: '#/components/schemas/RegularFacetFieldModel'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
type: array
items:
oneOf:
- $ref: '#/components/schemas/ContinuousFacetFieldModel'
- $ref: '#/components/schemas/HierarchicalFacetFieldModel'
- $ref: '#/components/schemas/NumericalRangesFacetFieldModel'
- $ref: '#/components/schemas/RegularFacetFieldModel'
x-pretty-name: bulkUpdate
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/tracking-ids/paramId/facet/fields/bulk-update_put
/rest/organizations/{organizationId}/commerce/v2/tracking-ids/{trackingId}/context-mappings/{key}:
get:
tags:
- Context Mapping Configurations
summary: Get Context Mapping
description: 'Gets a specific context mapping by key.**Required privilege:** Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: path
description: The unique identifier of the tracking target.
required: true
schema:
type: string
- name: key
in: path
description: The context mapping key
required: true
schema:
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/ContextMappingModel'
x-pretty-name: get
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/tracking-ids/paramId/context-mappings/paramId_get
put:
tags:
- Context Mapping Configurations
summary: Update Context Mapping
description: 'Updates an existing context mapping by key**Required privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: path
description: The unique identifier of the tracking target.
required: true
schema:
type: string
- name: key
in: path
description: The context mapping key
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContextMappingModel'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/ContextMappingModel'
x-pretty-name: update
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/tracking-ids/paramId/context-mappings/paramId_put
delete:
tags:
- Context Mapping Configurations
summary: Delete Context Mapping
description: 'Deletes a specific context mapping by key.**Required privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: path
description: The unique identifier of the tracking target.
required: true
schema:
type: string
- name: key
in: path
description: The context mapping key
required: true
schema:
type: string
responses:
'204':
description: No Content
x-pretty-name: delete
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/tracking-ids/paramId/context-mappings/paramId_delete
/rest/organizations/{organizationId}/commerce/v2/search/synonyms/{synonymId}:
get:
tags:
- Synonym
summary: Get a Synonym Rule.
description: 'Retrieves a synonym rule.**Required privilege:** Merchandising Hub - View
Privilege
required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
type: string
example: acmecorporation_ca
- name: synonymId
in: path
description: A UUID identifying the synonym rule.
required: true
schema:
type: string
format: uuid
example: 58bb4b98-1daa-4767-8c15-90a0ea67645c
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/SynonymModel'
x-pretty-name: getSynonym
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/search/synonyms/paramId_get
put:
tags:
- Synonym
summary: Edit Synonym Rule
description: 'Updates a synonym rule.**Required privilege:** Merchandising Hub - Edit
Privilege
required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
maxLength: 255
minLength: 1
type: string
example: acmecorporation_ca
- name: synonymId
in: path
description: A UUID identifying the synonym rule.
required: true
schema:
type: string
format: uuid
example: 58bb4b98-1daa-4767-8c15-90a0ea67645c
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SynonymModel'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/SynonymModel'
x-pretty-name: editSynonym
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/search/synonyms/paramId_put
delete:
tags:
- Synonym
summary: Delete Synonym Rule.
description: 'Deletes a synonym rule.**Required privilege:** Merchandising Hub - Edit
Privilege
required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
type: string
example: acmecorporation_ca
- name: synonymId
in: path
description: A UUID identifying the synonym rule.
required: true
schema:
type: string
format: uuid
example: 58bb4b98-1daa-4767-8c15-90a0ea67645c
responses:
'204':
description: No Content
x-pretty-name: deleteSynonym
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/search/synonyms/paramId_delete
/rest/organizations/{organizationId}/commerce/v2/recommendations/slots/{configurationId}:
get:
tags:
- Recommendations Configuration
summary: Retrieves a Slot Configuration
description: 'Shows a [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/) in an [organization](https://docs.coveo.com/en/185/).**Required
privilege:** Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: configurationId
in: path
description: The unique identifier of the [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/).
required: true
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/SlotConfigurationModel'
x-pretty-name: getSlotConfiguration
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/recommendations/slots/paramId_get
put:
tags:
- Recommendations Configuration
summary: Update a Slot Configuration
description: 'Updates a [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/) in an
[organization](https://docs.coveo.com/en/185/).**Required privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{body.trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: configurationId
in: path
description: The unique identifier of the [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/).
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SlotConfigurationModel'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/SlotConfigurationModel'
x-pretty-name: updateSlotConfiguration
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/recommendations/slots/paramId_put
delete:
tags:
- Recommendations Configuration
summary: Deletes a Slot Configuration
description: 'Deletes a [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/) in an
[organization](https://docs.coveo.com/en/185/).**Required privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: configurationId
in: path
description: The unique identifier of the [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/).
required: true
schema:
type: string
format: uuid
responses:
'204':
description: No Content
x-pretty-name: deleteSlotConfiguration
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/recommendations/slots/paramId_delete
/rest/organizations/{organizationId}/commerce/v2/recommendations/slots/{configurationId}/settings:
get:
tags:
- Recommendations Configuration
summary: Retrieves Slot Settings
description: 'Shows slot settings in an [organization](https://docs.coveo.com/en/185/).**Required privilege:**
Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: configurationId
in: path
description: The unique identifier of the [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/).
required: true
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/SlotSettingsModel'
x-pretty-name: getSlotSettings
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/recommendations/slots/paramId/settings_get
put:
tags:
- Recommendations Configuration
summary: Update Slot Settings
description: 'Updates slot settings in an [organization](https://docs.coveo.com/en/185/).**Required privilege:**
Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{body.trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: configurationId
in: path
description: The unique identifier of the [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/).
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SlotSettingsModel'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/SlotSettingsModel'
x-pretty-name: updateSlotSettings
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/recommendations/slots/paramId/settings_put
/rest/organizations/{organizationId}/commerce/v2/recommendations/slots/global/query-configuration:
get:
tags:
- Recommendations Configuration
summary: Retrieves a Global Query Configuration
description: 'Shows a Query configuration. in an [organization](https://docs.coveo.com/en/185/).**Required
privilege:** Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/Recommendation.QueryConfigurationModel'
x-pretty-name: getGlobalQueryConfiguration
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/recommendations/slots/global/query-configuration_get
put:
tags:
- Recommendations Configuration
summary: Update a Global Query Configuration
description: 'Updates a Query configuration. in an [organization](https://docs.coveo.com/en/185/).**Required
privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Recommendation.QueryConfigurationModel'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/Recommendation.QueryConfigurationModel'
x-pretty-name: updateGlobalQueryConfiguration
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/recommendations/slots/global/query-configuration_put
/rest/organizations/{organizationId}/commerce/v2/listings/pages/bulk-update:
put:
tags:
- Public Listing Page API
summary: Update Multiple Listing Pages
description: 'Updates multiple Listing pages in a [listing](https://docs.coveo.com/en/m1sf3187/). Maximum 100 items
per request..**Required privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PublicListingPageRequestModel'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
type: array
items:
$ref: '#/components/schemas/PublicListingPageResponseModel'
x-pretty-name: bulkUpdate
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/listings/pages/bulk-update_put
/rest/organizations/{organizationId}/commerce/v2/listing/preview/rules/{id}:
get:
tags:
- Listing Rule Preview
summary: Preview the Impact of a Listing Rule.
description: 'Returns a preview of products.**Required privilege:** Execute Query
Privilege
required
```
{"owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: id
in: path
description: The unique identifier of the rule.
required: true
schema:
type: string
format: uuid
- name: previewUrl
in: query
description: The URL used to retrieve the products listings.
required: true
schema:
type: string
example: http://acme.com/summersale
- name: listingName
in: query
description: The name of the listing configuration.
required: true
schema:
type: string
example: My Product Listing
- name: listingId
in: query
description: The unique identifier of the listing configuration.
required: true
schema:
type: string
example: 644e1dd7-2a7f-18fb-b8ed-ed78c3f92c2b
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
type: string
example: acmecorporation_ca
- name: language
in: query
description: An ISO 639-1 language code.
required: true
schema:
type: string
example: en
- name: country
in: query
description: An ISO 3166-1 alpha-2 country code.
required: true
schema:
type: string
example: US
- name: currency
in: query
description: An ISO 4217 currency code.
required: true
schema:
type: string
example: USD
- name: page
in: query
description: The page of products to request.
required: false
schema:
type: integer
format: int32
example: 7
- name: perPage
in: query
description: The number of products per page. Note that a value greater than 100 may be rejected in the future.
required: false
schema:
type: integer
format: int32
example: 30
- name: isEditingGlobal
in: query
description: Whether the rule is for the global config.
required: false
schema:
type: boolean
default: false
- name: debug
in: query
description: Whether to include the execution report on a successful response.
required: false
schema:
type: boolean
default: false
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/PreviewResponseModel_V2ProductView'
x-pretty-name: previewImpactOfRule
x-required-privilege:
owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-required-privileges:
- owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/listing/preview/rules/paramId_get
put:
tags:
- Listing Rule Preview
summary: Preview the Impact of an Updated Listing Rule Vs Not Having the Rule, or If compareWithPreviousState Is True,
the Impact of a Rule Update Vs the Previous State of the Rule.
description: 'Returns a preview of products.**Required privilege:** Execute Query
Privilege
required
```
{"owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: id
in: path
description: The unique identifier of the rule.
required: true
schema:
type: string
format: uuid
- name: isEditingGlobal
in: query
description: Whether the rule is for the global config.
required: false
schema:
type: boolean
default: false
- name: compareWithPreviousState
in: query
description: When previewing an update to a rule, whether to compare the preview results against those from one executed
with the previous state of the rule, or against a one executed without that rule at all.
required: false
schema:
type: boolean
default: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ListingRulePreviewRequestModel_V2ProductView'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/PreviewResponseModel_V2ProductView'
x-pretty-name: previewImpactOfUpdatingRule
x-required-privilege:
owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-required-privileges:
- owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/listing/preview/rules/paramId_put
/rest/organizations/{organizationId}/commerce/v2/configurations/search/global:
get:
tags:
- Search Configurations
summary: Retrieves the Global Search Configuration for the Organization
description: 'Shows the global GlobalSearch configuration. Does not accept pin rules. in an [organization](https://docs.coveo.com/en/185/).**Required
privilege:** Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
maxLength: 255
minLength: 1
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/SearchConfigurationModel'
x-pretty-name: getGlobal
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/search/global_get
put:
tags:
- Search Configurations
summary: Update the Global Search Configuration for the Organization
description: 'Updates the global Search configuration to be applied for the whole organization in a [organization](https://docs.coveo.com/en/185/).**Required
privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{body.trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchConfigurationModel'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/SearchConfigurationModel'
x-pretty-name: updateGlobal
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/search/global_put
/rest/organizations/{organizationId}/commerce/v2/configurations/query:
get:
tags:
- Query Configurations
summary: Get Query Configuration for a Solution
description: 'Retrieves the query configuration for a solution (e.g. listing, search) in an [organization](https://docs.coveo.com/en/185/).
Note: When using the Recommendation solution type, only the `perPage` and `additionalFields` parameters
within the query configuration model are supported.**Required privilege:** Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
type: string
example: acmecorporation_ca
- name: solutionType
in: query
description: The solution type for the rule. It can be either 'listing' or 'search' or 'recommendations'.
required: true
schema:
type: string
enum:
- listing
- search
- recommendation
- name: targets
in: query
description: List of target identifiers e.g. listing page name, slot ID
required: false
schema:
maxItems: 1
minItems: 1
type: array
items:
type: string
example:
- Surf With Us This Year
- name: isGlobal
in: query
description: Whether the query configuration is globally applied.
required: false
schema:
type: boolean
default: false
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/QueryConfigurationModel'
x-pretty-name: get
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/query_get
put:
tags:
- Query Configurations
summary: Update Query Configuration for a Solution
description: 'Updates a query configuration for a solution (e.g. listing, search) in an [organization](https://docs.coveo.com/en/185/).
Note: When using the Recommendation solution type, only the `perPage` and `additionalFields` parameters
within the query configuration model are supported.**Required privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{body.trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/QueryConfigurationRequestModel'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/QueryConfigurationModel'
x-pretty-name: update
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/query_put
post:
tags:
- Query Configurations
summary: Create Query Configuration for a Solution
description: 'Creates a query configuration for a solution (e.g. listing, search) in an [organization](https://docs.coveo.com/en/185/).
Note: When using the Recommendation solution type, only the `perPage` and `additionalFields` parameters
within the query configuration model are supported**Required privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{body.trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/QueryConfigurationRequestModel'
required: true
responses:
'201':
description: Created
content:
'*/*':
schema:
$ref: '#/components/schemas/QueryConfigurationModel'
x-pretty-name: create
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/query_post
delete:
tags:
- Query Configurations
summary: Delete the Query Configuration of a Solution
description: 'Deletes a query configuration for a solution (e.g. listing, search) in an [organization](https://docs.coveo.com/en/185/).
Note: When using the Recommendation solution type, only the `perPage` and `additionalFields` parameters
within the query configuration model are supported.**Required privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
type: string
example: acmecorporation_ca
- name: solutionType
in: query
description: The solution type for the rule. It can be either 'listing' or 'search' or 'recommendations'.
required: true
schema:
type: string
enum:
- listing
- search
- recommendation
- name: targets
in: query
description: List of target identifiers e.g. listing page name, slot ID
required: false
schema:
maxItems: 1
minItems: 1
type: array
items:
type: string
example:
- Surf With Us This Year
- name: isGlobal
in: query
description: Whether the query configuration is globally applied.
required: false
schema:
type: boolean
default: false
responses:
'204':
description: No Content
x-pretty-name: delete
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/query_delete
/rest/organizations/{organizationId}/commerce/v2/configurations/productSuggest:
get:
tags:
- Product Suggest Configurations
summary: Retrieves a Product Suggest Configuration
description: 'Shows a Product suggest configuration in an [organization](https://docs.coveo.com/en/185/).**Required
privilege:** Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: Tracking ID of the product suggest configuration
required: true
schema:
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/ProductSuggestConfigurationModel'
x-pretty-name: get
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/productSuggest_get
put:
tags:
- Product Suggest Configurations
summary: Update a Product Suggest Configuration
description: 'Updates a Product suggest configuration in an [organization](https://docs.coveo.com/en/185/).**Required
privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: Tracking ID of the product suggest configuration
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProductSuggestConfigurationModel'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/ProductSuggestConfigurationModel'
x-pretty-name: update
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/productSuggest_put
post:
tags:
- Product Suggest Configurations
summary: Create a Product Suggest Configuration
description: 'Creates a Product suggest configuration in an [organization](https://docs.coveo.com/en/185/).**Required
privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{body.trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ProductSuggestConfigurationModel'
required: true
responses:
'201':
description: Created
content:
'*/*':
schema:
$ref: '#/components/schemas/ProductSuggestConfigurationModel'
x-pretty-name: create
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/productSuggest_post
delete:
tags:
- Product Suggest Configurations
summary: Deletes a Product Suggest Configuration
description: 'Deletes a Product suggest configuration in an [organization](https://docs.coveo.com/en/185/).**Required
privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: Tracking ID of the product suggest configuration
required: true
schema:
type: string
responses:
'204':
description: No Content
x-pretty-name: delete
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/productSuggest_delete
/rest/organizations/{organizationId}/commerce/v2/configurations/listings/{configurationId}:
get:
tags:
- Listing Configurations
summary: Retrieves a Listing Configuration. WILL BE DEPRECATED on 2026-08-31.
description: '**WILL BE DEPRECATED ON 2026-08-31: See [this page](https://docs.coveo.com/en/q4dd0300/deprecations/search-and-listing-configuration-apis-deprecation)
for more details.**Shows a Listing configuration in an [organization](https://docs.coveo.com/en/185/).**Required
privilege:** Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: configurationId
in: path
description: The unique identifier of the listing configuration.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/ListingConfigurationModel'
x-pretty-name: get
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/listings/paramId_get
put:
tags:
- Listing Configurations
summary: Update a Listing Configuration. WILL BE DEPRECATED on 2026-08-31.
description: '**WILL BE DEPRECATED ON 2026-08-31: See [this page](https://docs.coveo.com/en/q4dd0300/deprecations/search-and-listing-configuration-apis-deprecation)
for more details.**Updates a Listing configuration in a [listing](https://docs.coveo.com/en/m1sf3187/).**Required
privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{body.trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: configurationId
in: path
description: The unique identifier of the listing configuration.
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ListingConfigurationModel'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/ListingConfigurationModel'
x-pretty-name: update
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/listings/paramId_put
delete:
tags:
- Listing Configurations
summary: Deletes a Listing Configuration. WILL BE DEPRECATED on 2026-08-31.
description: '**WILL BE DEPRECATED ON 2026-08-31: See [this page](https://docs.coveo.com/en/q4dd0300/deprecations/search-and-listing-configuration-apis-deprecation)
for more details.**Deletes a Listing configuration in an [organization](https://docs.coveo.com/en/185/).**Required
privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: configurationId
in: path
description: The unique identifier of the listing configuration.
required: true
schema:
type: string
format: uuid
responses:
'204':
description: No Content
x-pretty-name: delete
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/listings/paramId_delete
/rest/organizations/{organizationId}/commerce/v2/configurations/listings/global:
get:
tags:
- Listing Configurations
summary: Retrieves the Global Listing Configuration for the Organization
description: 'Shows the global GlobalListing configuration. Does not accept pin rules. in an [organization](https://docs.coveo.com/en/185/).**Required
privilege:** Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
maxLength: 255
minLength: 1
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/ListingConfigurationModel'
x-pretty-name: getGlobal
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/listings/global_get
put:
tags:
- Listing Configurations
summary: Update the Global Listing Configuration for the Organization
description: 'Updates the global GlobalListing configuration. Does not accept pin rules. to be applied for the whole
organization in a [listing](https://docs.coveo.com/en/m1sf3187/).**Required privilege:** Merchandising Hub
- Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{body.trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ListingConfigurationModel'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/ListingConfigurationModel'
x-pretty-name: updateGlobal
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/listings/global_put
/rest/organizations/{organizationId}/commerce/v2/tracking-ids/{trackingId}/facet/fields/bulk-create:
post:
tags:
- Facet Field Configurations
summary: Creates Multiple Facet Fields
description: 'Creates multiple facet fields. Maximum 100 items per request.**Required privilege:** Merchandising
Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: path
description: The unique identifier of the tracking target.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: array
items:
oneOf:
- $ref: '#/components/schemas/ContinuousFacetFieldModel'
- $ref: '#/components/schemas/HierarchicalFacetFieldModel'
- $ref: '#/components/schemas/NumericalRangesFacetFieldModel'
- $ref: '#/components/schemas/RegularFacetFieldModel'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
type: array
items:
oneOf:
- $ref: '#/components/schemas/ContinuousFacetFieldModel'
- $ref: '#/components/schemas/HierarchicalFacetFieldModel'
- $ref: '#/components/schemas/NumericalRangesFacetFieldModel'
- $ref: '#/components/schemas/RegularFacetFieldModel'
x-pretty-name: bulkCreate
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/tracking-ids/paramId/facet/fields/bulk-create_post
/rest/organizations/{organizationId}/commerce/v2/tracking-ids/{trackingId}/context-mappings:
get:
tags:
- Context Mapping Configurations
summary: List Context Mappings
description: 'Lists all context mapping configurations.**Required privilege:** Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: path
description: The unique identifier of the tracking target.
required: true
schema:
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
type: array
items:
$ref: '#/components/schemas/ContextMappingModel'
x-pretty-name: list
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/tracking-ids/paramId/context-mappings_get
post:
tags:
- Context Mapping Configurations
summary: Creates a Context Mapping
description: 'Creates a context mapping for a specific key.**Required privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: path
description: The unique identifier of the tracking target.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContextMappingModel'
required: true
responses:
'201':
description: Created
content:
'*/*':
schema:
$ref: '#/components/schemas/ContextMappingModel'
x-pretty-name: create
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/tracking-ids/paramId/context-mappings_post
/rest/organizations/{organizationId}/commerce/v2/tracking-ids/{trackingId}/badges:
post:
tags:
- Badges
summary: Get Badges for a Set of Placement IDs
description: 'Retrieve badges on products for a set of placements **Required privilege:** Execute Query
Privilege required
```
{"owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: path
description: The unique identifier of the tracking target.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BadgeRequestModel'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/NonPaginatedProductResponseProductBadgeViewModel'
x-pretty-name: badges
x-required-privilege:
owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-required-privileges:
- owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/tracking-ids/paramId/badges_post
/rest/organizations/{organizationId}/commerce/v2/setup:
post:
tags:
- Setup
summary: Create CMH Scaffolding
description: 'Creates the resources recommended to [setup](https://docs.coveo.com/en/o25a0034) Coveo for Commerce in
a [organization](https://docs.coveo.com/en/185/).**Required privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{body.trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SetupRequestModel'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/SetupResponseModel'
x-pretty-name: setup
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/setup_post
/rest/organizations/{organizationId}/commerce/v2/search:
post:
tags:
- Search
summary: Execute a Search Query
description: 'Returns products linked to a user query and merchandiser defined hub.**Required privilege:**
Execute Query
Privilege required
```
{"owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequestModel_V2SearchProductView'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/SearchResponseModel_V2SearchProductView'
x-pretty-name: search
x-required-privilege:
owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-required-privileges:
- owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/search_post
/rest/organizations/{organizationId}/commerce/v2/search/synonyms:
get:
tags:
- Synonym
summary: List Synonym Rules
description: 'List synonym rules.**Required privilege:** Merchandising Hub - View
Privilege
required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
maxLength: 255
minLength: 1
type: string
example: acmecorporation_ca
- name: language
in: query
description: An ISO 639-1 language code.
required: false
schema:
pattern: ^[a-z]{2}$
type: string
example: en
- name: country
in: query
description: An ISO 3166-1 alpha-2 country code.
required: false
schema:
pattern: ^[A-Z]{2}$
type: string
example: US
- name: currency
in: query
description: An ISO 4217 currency code.
required: false
schema:
pattern: ^[A-Z]{3}$
type: string
example: USD
- name: query
in: query
description: Filter on search term (query expression) when requesting rules.
required: false
schema:
type: string
example: mens shoes
- name: action
in: query
description: 'The synonym rule type. Possible values are: one-way, two-way, and one-way-reverse.'
required: false
schema:
type: string
example: one-way
- name: sort
in: query
description: property.direction to sort by.
required: false
schema:
type: string
example: query.asc
- name: page
in: query
description: The 0-based index number of the page of rules to retrieve.**Minimum:** `0`**Default:** `0`
required: false
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: perPage
in: query
description: The number of rules to list per page.**Minimum:** `1`**Maximum:** `1000`**Default:** `10`
required: false
schema:
maximum: 1000
minimum: 1
type: integer
format: int32
default: 10
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/CommercePageModelSynonymModel'
x-pretty-name: listSynonyms
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/search/synonyms_get
post:
tags:
- Synonym
summary: Create a Synonym Rule
description: 'Persists a synonym rule.**Required privilege:** Merchandising Hub - Edit
Privilege
required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
maxLength: 255
minLength: 1
type: string
example: acmecorporation_ca
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SynonymModel'
required: true
responses:
'201':
description: Created
content:
'*/*':
schema:
$ref: '#/components/schemas/SynonymModel'
x-pretty-name: createSynonym
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/search/synonyms_post
/rest/organizations/{organizationId}/commerce/v2/search/redirect:
post:
tags:
- Search
summary: Execute a Search Redirect Query
description: 'Returns a redirect linked to a user query and merchandiser defined hub.**Required privilege:**
Execute Query
Privilege required
```
{"owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRedirectRequestModel_V2SearchProductView'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/SearchRedirectResponseModel_V2SearchProductView'
x-pretty-name: redirect
x-required-privilege:
owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-required-privileges:
- owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/search/redirect_post
/rest/organizations/{organizationId}/commerce/v2/search/querySuggest:
post:
tags:
- Search
summary: Request Query Suggestions
description: 'Returns query suggestions.**Required privilege:** Execute Query
Privilege
required
```
{"owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/QuerySuggestRequestModel'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/QuerySuggestResponseModel'
x-pretty-name: querySuggest
x-required-privilege:
owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-required-privileges:
- owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/search/querySuggest_post
/rest/organizations/{organizationId}/commerce/v2/search/productSuggest:
post:
tags:
- Search
summary: Request Product Suggestions
description: 'Returns product suggestions.**Required privilege:** Execute Query
Privilege
required
```
{"owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequestModel_V2SearchProductView'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/SearchResponseModel_V2SearchProductView'
x-pretty-name: productSuggest
x-required-privilege:
owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-required-privileges:
- owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/search/productSuggest_post
/rest/organizations/{organizationId}/commerce/v2/search/preview/synonyms/new:
post:
tags:
- Synonym Preview
summary: Preview the Impact of a Synonym Rule
description: 'Previews the impact of a synonym rule.**Required privilege:** Execute Query
Privilege
required
```
{"owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
maxLength: 255
minLength: 1
type: string
example: acmecorporation_ca
- name: id
in: query
description: A UUID identifying the synonym rule.
required: false
schema:
type: string
format: uuid
example: 58bb4b98-1daa-4767-8c15-90a0ea67645c
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SynonymPreviewRequestModel_V2ProductView'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/PreviewResponseModel_V2ProductView'
x-pretty-name: previewSynonym
x-required-privilege:
owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-required-privileges:
- owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/search/preview/synonyms/new_post
/rest/organizations/{organizationId}/commerce/v2/recommendations:
post:
tags:
- Recommendations
summary: Execute a Recommendations Query
description: 'Returns products linked to a recommendations slot.**Required privilege:** Execute Query
Privilege required
```
{"owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RecommendationsRequestModel_V2ProductView'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/RecommendationsResponseModel_V2ProductView'
x-pretty-name: recommendations
x-required-privilege:
owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-required-privileges:
- owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/recommendations_post
/rest/organizations/{organizationId}/commerce/v2/recommendations/slots:
get:
tags:
- Recommendations Configuration
summary: Retrieves All Slot Configurations of an Organization
description: 'Lists all the [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/) in
an [organization](https://docs.coveo.com/en/185/).**Required privilege:** Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
maxLength: 255
minLength: 1
type: string
- name: page
in: query
description: The 0-based index number of the page of [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/)
to retrieve.**Minimum:** `0`**Default:** `0`
required: false
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: perPage
in: query
description: The number of [slot configurations](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/)
to list per page.**Minimum:** `1`**Maximum:** `1000`**Default:** `10`
required: false
schema:
maximum: 1000
minimum: 1
type: integer
format: int32
default: 10
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/CommercePageModelSlotConfigurationModel'
x-pretty-name: getSlotConfigurations
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/recommendations/slots_get
post:
tags:
- Recommendations Configuration
summary: Create a Slot Configuration
description: 'Creates a [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/) in an
[organization](https://docs.coveo.com/en/185/).**Required privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{body.trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SlotConfigurationModel'
required: true
responses:
'201':
description: Created
content:
'*/*':
schema:
$ref: '#/components/schemas/SlotConfigurationModel'
x-pretty-name: createSlotConfiguration
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/recommendations/slots_post
/rest/organizations/{organizationId}/commerce/v2/recommendations/preview:
post:
tags:
- Recommendations
summary: Preview a Recommendations Query
description: 'Returns a preview response of products linked to a recommendations slot.**Required privilege:**
Execute Query
Privilege required
```
{"owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RecommendationsPreviewRequestModel_V2ProductView'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/PreviewResponseModel_V2ProductView'
x-pretty-name: recommendationsPreview
x-required-privilege:
owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-required-privileges:
- owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/recommendations/preview_post
/rest/organizations/{organizationId}/commerce/v2/listings/pages/bulk-delete:
post:
tags:
- Public Listing Page API
summary: Delete Multiple Listing Pages
description: 'Deletes multiple Listing pages in a [listing](https://docs.coveo.com/en/m1sf3187/). Maximum 100 items
per request..**Required privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: array
items:
type: string
format: uuid
required: true
responses:
'204':
description: No Content
x-pretty-name: bulkDelete
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/listings/pages/bulk-delete_post
/rest/organizations/{organizationId}/commerce/v2/listings/pages/bulk-create:
post:
tags:
- Public Listing Page API
summary: Create Multiple Listing Pages
description: 'Creates multiple Listing pages in a [listing](https://docs.coveo.com/en/m1sf3187/). Maximum 100 items
per request..**Required privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PublicListingPageRequestModel'
required: true
responses:
'201':
description: Created
content:
'*/*':
schema:
type: array
items:
$ref: '#/components/schemas/PublicListingPageResponseModel'
x-pretty-name: bulkCreate
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/listings/pages/bulk-create_post
/rest/organizations/{organizationId}/commerce/v2/listing:
post:
tags:
- Listings
summary: Get a Listing Page
description: 'Shows products linked to a [product listing](https://docs.coveo.com/en/m1sf3187/) URL.**Required
privilege:** Execute Query
Privilege required
```
{"owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ListingRequestModel_V2ProductView'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/ListingResponseModel_V2ProductView'
x-pretty-name: getListing
x-required-privilege:
owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-required-privileges:
- owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/listing_post
/rest/organizations/{organizationId}/commerce/v2/listing/preview/rules:
post:
tags:
- Listing Rule Preview
summary: Preview the Impact of Creating a Listing Rule on a Config.
description: 'Returns a preview of products.**Required privilege:** Execute Query
Privilege
required
```
{"owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: isEditingGlobal
in: query
description: Whether the rule is for the global config.
required: false
schema:
type: boolean
default: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ListingRulePreviewRequestModel_V2ProductView'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/PreviewResponseModel_V2ProductView'
x-pretty-name: previewImpactOfCreatingRule
x-required-privilege:
owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-required-privileges:
- owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/listing/preview/rules_post
/rest/organizations/{organizationId}/commerce/v2/facet:
post:
tags:
- Facet
summary: Executes a Facet Search Query
description: 'Returns facet values for a given query.**Required privilege:** Execute Query
Privilege
required
```
{"owner":"SEARCH_API","targetDomain":"EXECUTE_QUERY","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: type
in: query
description: 'Solution type. Possible values are: LISTING, SEARCH.'
required: false
schema:
type: string
enum:
- LISTING
- SEARCH
example: LISTING
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FacetSearchRequestModel'
required: true
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/FacetSearchResponseModel'
x-pretty-name: facet
x-required-privilege:
owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-required-privileges:
- owner: SEARCH_API
targetDomain: EXECUTE_QUERY
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/facet_post
/rest/organizations/{organizationId}/commerce/v2/configurations/listings:
get:
tags:
- Listing Configurations
summary: Retrieves All Listing Configurations of an Organization. WILL BE DEPRECATED on 2026-08-31.
description: '**WILL BE DEPRECATED ON 2026-08-31: See [this page](https://docs.coveo.com/en/q4dd0300/deprecations/search-and-listing-configuration-apis-deprecation)
for more details.**Lists all the Listing configuration in an [organization](https://docs.coveo.com/en/185/).**Required
privilege:** Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
maxLength: 255
minLength: 1
type: string
- name: query
in: query
description: Filter on names when requesting listing configuration names & IDs. Will perform '*query*' match pattern.
required: false
schema:
type: string
example: Surf With Us Th
- name: page
in: query
description: The 0-based index number of the page of listing configurations to retrieve.**Minimum:** `0`**Default:**
`0`
required: false
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: perPage
in: query
description: The number of listing configurations to list per page.**Minimum:** `1`**Maximum:** `1000`**Default:**
`10`
required: false
schema:
maximum: 1000
minimum: 1
type: integer
format: int32
default: 10
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/CommercePageModelListingConfigurationModel'
x-pretty-name: getAll
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/listings_get
post:
tags:
- Listing Configurations
summary: Create a Listing Configuration. WILL BE DEPRECATED on 2026-08-31.
description: '**WILL BE DEPRECATED ON 2026-08-31: See [this page](https://docs.coveo.com/en/q4dd0300/deprecations/search-and-listing-configuration-apis-deprecation)
for more details.**Creates a Listing configuration in a [listing](https://docs.coveo.com/en/m1sf3187/).**Required
privilege:** Merchandising Hub - Edit
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{body.trackingId}"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ListingConfigurationModel'
required: true
responses:
'201':
description: Created
content:
'*/*':
schema:
$ref: '#/components/schemas/ListingConfigurationModel'
x-pretty-name: create
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: EDIT
targetId: '{body.trackingId}'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/listings_post
/rest/organizations/{organizationId}/commerce/v2/tracking-ids/{trackingId}/facet/fields:
get:
tags:
- Facet Field Configurations
summary: Retrieves All Facet Fields
description: 'Retrieve all facet fields.**Required privilege:** Merchandising Hub - View
Privilege
required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: path
description: The unique identifier of the tracking target.
required: true
schema:
type: string
- name: page
in: query
description: The 0-based index number of the page to retrieve.
required: false
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: perPage
in: query
description: The number of items to return per page.
required: false
schema:
maximum: 100
minimum: 1
type: integer
format: int32
default: 10
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/PaginatedResponseFacetFieldModel'
x-pretty-name: getAll
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/tracking-ids/paramId/facet/fields_get
/rest/organizations/{organizationId}/commerce/v2/recommendations/slots/{configurationId}/strategies:
get:
tags:
- Recommendations Configuration
summary: Retrieves Available Slot Strategies
description: 'Shows The available strategies to use for this slot. in an [organization](https://docs.coveo.com/en/185/).**Required
privilege:** Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: configurationId
in: path
description: The unique identifier of the [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/).
required: true
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/SlotStrategiesModel'
x-pretty-name: getSlotStrategies
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/recommendations/slots/paramId/strategies_get
/rest/organizations/{organizationId}/commerce/v2/recommendations/slots/strategies:
get:
tags:
- Recommendations Configuration
summary: Retrieves Available Slot Strategies
description: 'Shows The available strategies to use for this slot. in an [organization](https://docs.coveo.com/en/185/).**Required
privilege:** Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: slotType
in: query
description: A slot type label that identifies the location of a slot.
required: true
schema:
type: string
enum:
- cart
- confirmation
- global
- home
- listing
- productDetail
- search
- name: seedType
in: query
description: 'The primary [seed product](https://docs.coveo.com/en/n5jg0219/glossary/seed-product) type used by recommendations
strategies on this [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/). One of:
product, cart or purchased.'
required: true
schema:
type: string
enum:
- unseeded
- product
- cart
- purchased
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/SlotStrategiesModel'
x-pretty-name: getSlotStrategies
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/recommendations/slots/strategies_get
/rest/organizations/{organizationId}/commerce/v2/recommendations/slots/names:
get:
tags:
- Recommendations Configuration
summary: Retrieves All Slot Configuration Ids & Names of an Organization
description: 'Lists all the names of the [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/)
in an [organization](https://docs.coveo.com/en/185/).**Required privilege:** Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
maxLength: 255
minLength: 1
type: string
- name: query
in: query
description: Filter on names when requesting slot names & IDs. Will perform '*query*' match pattern.
required: false
schema:
type: string
example: slotName
- name: page
in: query
description: The 0-based index number of the page of [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/)
to retrieve.**Minimum:** `0`**Default:** `0`
required: false
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: perPage
in: query
description: The number of [slot configurations](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/)
to list per page.**Minimum:** `1`**Maximum:** `1000`**Default:** `10`
required: false
schema:
maximum: 1000
minimum: 1
type: integer
format: int32
default: 10
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/CommercePageModelSlotConfigurationNameModel'
x-pretty-name: getSlotConfigurationNames
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/recommendations/slots/names_get
/rest/organizations/{organizationId}/commerce/v2/listings/pages:
get:
tags:
- Public Listing Page API
summary: Retrieves All Listing Pages and Their Page Rules for a Tracking ID Within an Organization
description: 'Lists all the Listing configuration, returning only essential fields, in an [organization](https://docs.coveo.com/en/185/).**Required
privilege:** Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
maxLength: 255
minLength: 1
type: string
- name: page
in: query
description: The 0-based index number of the page of listing configurations to retrieve.**Minimum:** `0`**Default:**
`0`
required: false
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: perPage
in: query
description: The number of listing configurations to list per page.**Minimum:** `1`**Maximum:** `1000`**Default:**
`10`
required: false
schema:
maximum: 1000
minimum: 1
type: integer
format: int32
default: 100
- name: filter
in: query
description: A filter expressed in JSON logic format.
required: false
schema:
type: string
example:
in:
- test
- var: url
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/CommercePageModelPublicListingPageResponseModel'
x-pretty-name: getAll
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/listings/pages_get
/rest/organizations/{organizationId}/commerce/v2/configurations/listings/url:
get:
tags:
- Listing Configurations
summary: Retrieves a Listing Configuration by Its Matching Url. WILL BE DEPRECATED on 2026-08-31.
description: '**WILL BE DEPRECATED ON 2026-08-31: See [this page](https://docs.coveo.com/en/q4dd0300/deprecations/search-and-listing-configuration-apis-deprecation)
for more details.**Shows a Listing configuration in an [organization](https://docs.coveo.com/en/185/).**Required
privilege:** Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
maxLength: 255
minLength: 1
type: string
- name: url
in: query
description: URL
required: true
schema:
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/ListingConfigurationModel'
x-pretty-name: getByUrl
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/listings/url_get
/rest/organizations/{organizationId}/commerce/v2/configurations/listings/rules:
get:
tags:
- Listing Configurations
summary: Retrieves All Rules Related to Listings of an Organization. WILL BE DEPRECATED on 2026-08-31.
description: '**WILL BE DEPRECATED ON 2026-08-31: See [this page](https://docs.coveo.com/en/q4dd0300/deprecations/search-and-listing-configuration-apis-deprecation)
for more details.**Lists listing related rules in an [organization](https://docs.coveo.com/en/185/).**Required
privilege:** Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
type: string
- name: configurationId
in: query
description: The unique identifier of the listing configuration.
required: false
schema:
type: string
format: uuid
example: 644e1dd7-2a7f-18fb-b8ed-ed78c3f92c2b
- name: name
in: query
description: Filter on rule name when requesting rules.
required: false
schema:
type: string
example: Small name for a rule
- name: scope
in: query
description: 'Rule scope to return. One of: [specific, global]. Returns all if not specified.'
required: false
schema:
type: string
enum:
- global
- specific
example: specific
- name: essential
in: query
description: Indicates if the rule is essential to the listing page; the essential rule is added during page creation.
Returns all rules if not specified.
required: false
schema:
type: boolean
example: false
- name: language
in: query
description: An ISO 639-1 language code.
required: false
schema:
type: string
example: en
- name: country
in: query
description: An ISO 3166-1 alpha-2 country code.
required: false
schema:
type: string
example: US
- name: currency
in: query
description: An ISO 4217 currency code.
required: false
schema:
type: string
example: USD
- name: actions
in: query
description: 'Rule action type to return. One of: [boost, bury, pin, include, exclude, onlyShow]. Returns all if not
specified.'
required: false
schema:
type: array
items:
type: string
enum:
- boost
- bury
- pin
- include
- exclude
example: '[boost]'
- name: sort
in: query
description: List of property.direction to sort by
required: false
schema:
type: array
items:
type: string
default:
- name.asc
example: name.asc
- name: scheduleFilter
in: query
description: The schedule filter to apply.
required: false
schema:
type: string
enum:
- live
- unscheduled
- expired
example: liveRules
- name: page
in: query
description: The 0-based index number of the page of rules to retrieve.**Minimum:** `0`**Default:** `0`
required: false
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: perPage
in: query
description: The number of rules to list per page.**Minimum:** `1`**Maximum:** `1000`**Default:** `10`
required: false
schema:
maximum: 1000
minimum: 1
type: integer
format: int32
default: 10
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/PaginatedRuleItems'
x-pretty-name: getRules
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/listings/rules_get
/rest/organizations/{organizationId}/commerce/v2/configurations/listings/names:
get:
tags:
- Listing Configurations
summary: Retrieves All Listing Configurations Ids & Names of an Organization. WILL BE DEPRECATED on 2026-08-31.
description: '**WILL BE DEPRECATED ON 2026-08-31: See [this page](https://docs.coveo.com/en/q4dd0300/deprecations/search-and-listing-configuration-apis-deprecation)
for more details.**Lists all ids and names of the Listing configuration in an [organization](https://docs.coveo.com/en/185/).**Required
privilege:** Merchandising Hub - View
Privilege required
```
{"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}
```
**Example:**
`acmecorporation8tp8wu3`
required: true
schema:
type: string
- name: trackingId
in: query
description: The unique identifier of the tracking target.
required: true
schema:
maxLength: 255
minLength: 1
type: string
- name: query
in: query
description: Filter on names when requesting listing configuration names & IDs. Will perform '*query*' match pattern.
required: false
schema:
type: string
example: Surf With Us Th
- name: page
in: query
description: The 0-based index number of the page of listing configurations to retrieve.**Minimum:** `0`**Default:**
`0`
required: false
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: perPage
in: query
description: The number of listing configurations to list per page.**Minimum:** `1`**Maximum:** `1000`**Default:**
`10`
required: false
schema:
minimum: 1
type: integer
format: int32
default: 10
responses:
'200':
description: OK
content:
'*/*':
schema:
$ref: '#/components/schemas/CommercePageModelListingConfigurationNameModel'
x-pretty-name: getAllNames
x-required-privilege:
owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-required-privileges:
- owner: COMMERCE
targetDomain: MERCHANDISING_HUB
type: VIEW
targetId: '*'
x-ui-operation-id: /rest/organizations/paramId/commerce/v2/configurations/listings/names_get
components:
schemas:
AutomaticEvenNumericalRangesDetailsModel:
required:
- numberOfRanges
type: object
allOf:
- $ref: '#/components/schemas/NumericalRangesDetailsModel'
- type: object
properties:
type:
type: string
description: The type of numerical range.
example: AUTOMATIC_EVEN
enum:
- AUTOMATIC_EVEN
- MANUAL
numberOfRanges:
maximum: 10
minimum: 2
type: integer
description: The number of ranges to generate.
format: int32
example: 4
ContinuousFacetFieldModel:
required:
- displayNames
- field
type: object
allOf:
- $ref: '#/components/schemas/FacetFieldModel'
- type: object
properties:
id:
type: string
description: The unique identifier of the facet field configuration.
format: uuid
example: 755e2dd8-3a8f-19fb-b9ed-ed89c4f83c3b
field:
maxLength: 255
minLength: 0
type: string
description: The name of the underlying index field. This property can't be updated after creation.
example: ec_price
type:
type: string
description: The type of the facet field.
example: CONTINUOUS
enum:
- REGULAR
- CONTINUOUS
- NUMERICAL_RANGES
- HIERARCHICAL
displayNames:
uniqueItems: true
type: array
description: A list of localized display names for the facet field. When a localized display name is not provided
for a given language, the index non-localized display name is used. If a non-localized display name is not configured,
the index field name is used.
items:
$ref: '#/components/schemas/LocalizedValueModel'
injectionDepth:
minimum: 1000
type: integer
description: "The maximum number of items to scan for facet values.\n
When value is not provided:
\n \
\ \n - Creation: defaults to `1000`
\n - Update: preserves existing database value
\n\
\
\n"
format: int32
default: 1000
FacetFieldModel:
type: object
properties:
type:
type: string
enum:
- REGULAR
- CONTINUOUS
- NUMERICAL_RANGES
- HIERARCHICAL
discriminator:
propertyName: type
HierarchicalFacetFieldModel:
required:
- displayNames
- field
- initialNumberOfValues
- sortCriteria
type: object
allOf:
- $ref: '#/components/schemas/FacetFieldModel'
- type: object
properties:
id:
type: string
description: The unique identifier of the facet field configuration.
format: uuid
example: 755e2dd8-3a8f-19fb-b9ed-ed89c4f83c3b
field:
maxLength: 255
minLength: 0
type: string
description: The name of the underlying index field. This property can't be updated after creation.
example: ec_category
type:
type: string
description: The type of the facet field.
example: HIERARCHICAL
enum:
- REGULAR
- CONTINUOUS
- NUMERICAL_RANGES
- HIERARCHICAL
displayNames:
uniqueItems: true
type: array
description: A list of localized display names for the facet field. When a localized display name is not provided
for a given language, the index non-localized display name is used. If a non-localized display name is not configured,
the index field name is used.
items:
$ref: '#/components/schemas/LocalizedValueModel'
injectionDepth:
minimum: 1000
type: integer
description: "The maximum number of items to scan for facet values.\n
When value is not provided:
\n \
\ \n - Creation: defaults to `1000`
\n - Update: preserves existing database value
\n\
\
\n"
format: int32
default: 1000
sortCriteria:
type: string
description: The criteria used to sort facet field values.
example: relevance
enum:
- RELEVANCE
- ALPHANUMERIC
- OCCURRENCES
initialNumberOfValues:
maximum: 200
minimum: 1
type: integer
description: The initial number of facet values shown.
format: int32
useInFilterSuggestions:
type: boolean
description: Whether the facet field can be used in filter suggestions. See [here](https://docs.coveo.com/en/o8ce0240#headless-implementation)
for more guidance.
LocalizedPinnedFacetValuesModel:
required:
- language
- values
type: object
properties:
language:
minLength: 1
type: string
description: The IETF language tag for which the pinned values applies.
example: en
values:
maxItems: 100
minItems: 0
type: array
description: Identifies the facet values that must appear at the top, in this order. Facet values that are not pinned
will be sorted according to the `sortCriteria`.
example:
- Small
- Medium
- Large
items:
minLength: 1
type: string
description: Identifies the facet values that must appear at the top, in this order. Facet values that are not
pinned will be sorted according to the `sortCriteria`.
example: '["Small","Medium","Large"]'
description: A list of pinned facet values. Pinned values are always shown at the top of the facet in the provided order
when there is at least one product that matches the pinned value.
default: []
LocalizedValueModel:
required:
- language
- value
type: object
properties:
language:
minLength: 1
type: string
description: An ISO 639-1 language code.
example: en
value:
type: string
description: The localized value
example: Hello
description: A list of localized display names for the facet field. When a localized display name is not provided for
a given language, the index non-localized display name is used. If a non-localized display name is not configured,
the index field name is used.
ManualNumericalRangesDetailsModel:
required:
- ranges
type: object
allOf:
- $ref: '#/components/schemas/NumericalRangesDetailsModel'
- type: object
properties:
type:
type: string
description: The type of numerical range.
example: MANUAL
enum:
- AUTOMATIC_EVEN
- MANUAL
ranges:
minItems: 1
type: array
items:
$ref: '#/components/schemas/NumericalRangeModel'
NumericalRangeModel:
type: object
properties:
start:
type: number
format: double
end:
type: number
format: double
NumericalRangesDetailsModel:
type: object
properties:
type:
type: string
enum:
- AUTOMATIC_EVEN
- MANUAL
discriminator:
propertyName: type
NumericalRangesFacetFieldModel:
required:
- displayNames
- field
- rangeDetails
type: object
allOf:
- $ref: '#/components/schemas/FacetFieldModel'
- type: object
properties:
id:
type: string
description: The unique identifier of the facet field configuration.
format: uuid
example: 755e2dd8-3a8f-19fb-b9ed-ed89c4f83c3b
field:
maxLength: 255
minLength: 0
type: string
description: The name of the underlying index field. This property can't be updated after creation.
example: ec_price
type:
type: string
description: The type of the facet field.
example: NUMERICAL_RANGES
enum:
- REGULAR
- CONTINUOUS
- NUMERICAL_RANGES
- HIERARCHICAL
displayNames:
uniqueItems: true
type: array
description: A list of localized display names for the facet field. When a localized display name is not provided
for a given language, the index non-localized display name is used. If a non-localized display name is not configured,
the index field name is used.
items:
$ref: '#/components/schemas/LocalizedValueModel'
injectionDepth:
minimum: 1000
type: integer
description: "The maximum number of items to scan for facet values.\n
When value is not provided:
\n \
\ \n - Creation: defaults to `1000`
\n - Update: preserves existing database value
\n\
\
\n"
format: int32
default: 1000
rangeDetails:
oneOf:
- $ref: '#/components/schemas/AutomaticEvenNumericalRangesDetailsModel'
- $ref: '#/components/schemas/ManualNumericalRangesDetailsModel'
RegularFacetFieldModel:
required:
- displayNames
- field
- initialNumberOfValues
- pinnedValues
- sortCriteria
type: object
allOf:
- $ref: '#/components/schemas/FacetFieldModel'
- type: object
properties:
id:
type: string
description: The unique identifier of the facet field configuration.
format: uuid
example: 755e2dd8-3a8f-19fb-b9ed-ed89c4f83c3b
field:
maxLength: 255
minLength: 0
type: string
description: The name of the underlying index field. This property can't be updated after creation.
example: ec_brand
type:
type: string
description: The type of the facet field.
example: REGULAR
enum:
- REGULAR
- CONTINUOUS
- NUMERICAL_RANGES
- HIERARCHICAL
displayNames:
uniqueItems: true
type: array
description: A list of localized display names for the facet field. When a localized display name is not provided
for a given language, the index non-localized display name is used. If a non-localized display name is not configured,
the index field name is used.
items:
$ref: '#/components/schemas/LocalizedValueModel'
injectionDepth:
minimum: 1000
type: integer
description: "The maximum number of items to scan for facet values.\n
When value is not provided:
\n \
\ \n - Creation: defaults to `1000`
\n - Update: preserves existing database value
\n\
\
\n"
format: int32
default: 1000
sortCriteria:
type: string
description: The criteria used to sort facet field values.
example: relevance
default: RELEVANCE
enum:
- RELEVANCE
- ALPHANUMERIC
- OCCURRENCES
initialNumberOfValues:
maximum: 1000
minimum: 1
type: integer
description: The initial number of facet values shown.
format: int32
default: 8
useInFilterSuggestions:
type: boolean
description: Whether the facet field can be used in filter suggestions. See [here](https://docs.coveo.com/en/o8ce0240#headless-implementation)
for more guidance.
resultsMustMatch:
type: string
description: "Specifies how a result must match the selected values.\n
When value is not provided:
\n\
\ \n - Creation: defaults to `AT_LEAST_ONE_VALUE`
\n - Update: preserves existing\
\ database value
\n
\n"
example: AT_LEAST_ONE_VALUE
enum:
- AT_LEAST_ONE_VALUE
- ALL_VALUES
pinnedValues:
type: array
description: A list of pinned facet values. Pinned values are always shown at the top of the facet in the provided
order when there is at least one product that matches the pinned value.
items:
$ref: '#/components/schemas/LocalizedPinnedFacetValuesModel'
default: []
ContextMappingModel:
required:
- destinations
- key
- type
type: object
properties:
key:
pattern: ^[a-zA-Z]\w{0,63}$
type: string
description: A unique key for the context mapping. Must start with a letter and contain only letters, numbers, and
underscores.
example: user_segment
type:
type: string
description: The data type for context mapping values
example: STRING
enum:
- BOOLEAN
- STRING
- NUMBER
- PRODUCT_LIST
destinations:
minItems: 1
type: array
description: The list of destinations where this context mapping should be applied.
example:
- attribute: QUERY_PIPELINE_CONTEXT
- attribute: FIELD_ALIASES
items:
$ref: '#/components/schemas/MappingDestination'
description: The context mapping configuration to create
MappingDestination:
required:
- attribute
type: object
properties:
attribute:
type: string
description: The destination type where context mapping values can be applied
example: QUERY_PIPELINE_CONTEXT
enum:
- QUERY_PIPELINE_CONTEXT
- ML_CONTEXT
- FIELD_ALIASES
fieldAlias:
type: string
description: The field alias template used when attribute is FIELD_ALIASES. Must resolve to a field name pattern.
example: price_{{contextValue}}
fieldSource:
type: string
description: The field source template used when attribute is FIELD_ALIASES. Must resolve to 'field.subkey' pattern.
example: price.{{contextValue}}
description: The list of destinations where this context mapping should be applied.
example:
- attribute: QUERY_PIPELINE_CONTEXT
- attribute: FIELD_ALIASES
RuleLocaleModel:
type: object
properties:
language:
type: string
description: An ISO 639-1 language code.
example: en
country:
type: string
description: An ISO 3166-1 alpha-2 country code.
example: US
currency:
type: string
description: An ISO 4217 currency code.
example: USD
description: The list of locales the synonym applies to. When empty, the synonym applies to all locales.
example:
- language: en
country: US
currency: USD
SynonymModel:
required:
- action
- from
type: object
properties:
id:
type: string
description: A UUID identifying the synonym rule.
format: uuid
readOnly: true
example: 58bb4b98-1daa-4767-8c15-90a0ea67645c
action:
type: string
description: 'The synonym rule type. Possible values are: one-way, two-way, and one-way-reverse.'
example: one-way
enum:
- one-way
- two-way
- replace
- exact-match
from:
minItems: 1
type: array
description: The search terms contained in the output query if matched against a synonym rule.
example:
- sandals
- sneakers
items:
type: string
description: The search terms contained in the output query if matched against a synonym rule.
example: '["sandals","sneakers"]'
to:
type: array
description: The search terms contained in the input query.
example:
- shoes
- heels
items:
type: string
description: The search terms contained in the input query.
example: '["shoes","heels"]'
locales:
type: array
description: The list of locales the synonym applies to. When empty, the synonym applies to all locales.
example:
- language: en
country: US
currency: USD
items:
$ref: '#/components/schemas/RuleLocaleModel'
updatedAt:
type: string
description: The date and time at which the synonym was last updated.
description: The synonym rule to persist.
Headline:
required:
- headline
- language
type: object
properties:
headline:
maxLength: 255
minLength: 1
type: string
description: Localized recommendation headlines.
example: '[{"headline":"You might be interested in","language":"en"}]'
language:
minLength: 1
type: string
description: Localized recommendation headlines.
example:
- headline: You might be interested in
language: en
Recommendation.QueryConfigurationModel:
required:
- additionalFields
type: object
properties:
additionalFields:
uniqueItems: true
type: array
description: To retrieve [additional fields](https://docs.coveo.com/en/n73f0502#create-additional-commerce-fields)
you have created, that aren’t part of the [standard commerce fields](https://docs.coveo.com/en/n73f0502#standard-commerce-fields),
specify them here. These fields appear in the `additionalFields` object in the response.
example:
- color
- shirtsize
items:
type: string
perPage:
maximum: 100
minimum: 0
type: integer
description: The number of results to include per page.
Note: The specified value applies only to
parent items, not their grouped children. Query performance may be affected when returned items include many grouped
products.
format: int32
example: 20
description: Query configuration.
SlotConfigurationModel:
required:
- headlines
- minRecs
- name
- seedType
- slotType
- strategy
- trackingId
type: object
properties:
id:
type: string
description: The unique identifier of the [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/).
format: uuid
readOnly: true
example: 755e2dd8-3a8f-19fb-b9ed-ed89c4f83c3b
createdAt:
type: integer
description: When the [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/) was
created.
format: int64
readOnly: true
name:
maxLength: 50
minLength: 1
type: string
description: A unique name for the [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/).
example: Homepage Primary.
trackingId:
maxLength: 255
minLength: 1
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
slotType:
type: string
description: A slot type label that identifies the location of a slot.
example: home
enum:
- cart
- confirmation
- global
- home
- listing
- productDetail
- search
seedType:
type: string
description: 'The primary [seed product](https://docs.coveo.com/en/n5jg0219/glossary/seed-product) type used by
recommendations strategies on this [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/).
One of: product, cart or purchased.'
example: product
enum:
- unseeded
- product
- cart
- purchased
seed:
type: string
description: 'The seed number for the [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/). One
of: unseeded, single, multi.'
readOnly: true
example: unseeded
enum:
- unseeded
- single
- multi
strategy:
type: string
description: The [strategy](https://docs.coveo.com/en/3132/glossary/product-recommendations) to use for recommendations.
example: popular_bought
enum:
- bought_together
- popular_bought
- popular_viewed
- viewed_together
headlines:
minItems: 1
uniqueItems: true
type: array
description: Localized recommendation headlines.
example:
- headline: You might be interested in
language: en
items:
$ref: '#/components/schemas/Headline'
minRecs:
maximum: 100
minimum: 1
type: integer
description: Products to be returned.
format: int32
default: 1
queryConfiguration:
$ref: '#/components/schemas/Recommendation.QueryConfigurationModel'
SlotSettingsModel:
required:
- headlines
- minRecs
- name
- slotType
- strategy
- trackingId
type: object
properties:
id:
type: string
description: The unique identifier of the [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/).
format: uuid
readOnly: true
example: 755e2dd8-3a8f-19fb-b9ed-ed89c4f83c3b
name:
maxLength: 50
minLength: 1
type: string
description: A unique name for the [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/).
example: Homepage Primary.
trackingId:
maxLength: 255
minLength: 1
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
slotType:
type: string
description: A slot type label that identifies the location of a slot.
example: home
enum:
- cart
- confirmation
- global
- home
- listing
- productDetail
- search
strategy:
type: string
description: The [strategy](https://docs.coveo.com/en/3132/glossary/product-recommendations) to use for recommendations.
example: popular_bought
enum:
- bought_together
- popular_bought
- popular_viewed
- viewed_together
headlines:
minItems: 1
uniqueItems: true
type: array
description: Localized recommendation headlines.
example:
- headline: You might be interested in
language: en
items:
$ref: '#/components/schemas/Headline'
minRecs:
maximum: 100
minimum: 1
type: integer
description: Products to be returned.
format: int32
DecimalValueModel:
required:
- value
type: object
allOf:
- $ref: '#/components/schemas/FieldValueModel'
- type: object
properties:
value:
type: number
format: double
FieldValueModel:
required:
- type
type: object
properties:
type:
type: string
description: The value to apply the operator on.
example:
type: string
value: Blue
discriminator:
propertyName: type
HierarchicMultiValueModel:
required:
- value
type: object
allOf:
- $ref: '#/components/schemas/FieldValueModel'
- type: object
properties:
value:
maxLength: 255
minLength: 0
type: string
InclusiveRangeModel:
required:
- range
type: object
allOf:
- $ref: '#/components/schemas/FieldValueModel'
- type: object
properties:
range:
$ref: '#/components/schemas/RangeModel'
ListingPageApiPageRuleModel:
required:
- filters
- name
type: object
properties:
filters:
minItems: 1
type: array
description: A list of filters.
example:
- fieldName: price
operator: isExactly
value:
type: decimal
value: 99.99
- fieldName: item_count
operator: isBetween
value:
type: range
range:
from: 1000
to: 3000
items:
$ref: '#/components/schemas/QueryFilterModel'
locales:
uniqueItems: true
type: array
description: The list of locales the rule applies to. When empty, the rule applies to all locales.
example:
- language: en
country: US
currency: USD
items:
$ref: '#/components/schemas/RuleLocaleModel'
name:
maxLength: 255
minLength: 1
type: string
description: The name of the rule.
example: 'Pin #1 Short Open-Front Sweater for Women/Boost blue surfboards/Hide green t-shirts'
description: List of rules associated to a listing page. Rules are used to determine the page's contents.
example:
- name: Include ec_category_slug contains canoes-kayaks/kayaks/sports-kayaks
locales:
- language: en
country: US
currency: USD
filters:
- fieldName: ec_category_slug
operator: contains
value:
type: array
values:
- canoes-kayaks/kayaks/sports-kayaks
MatchingConfigurationModel:
required:
- url
type: object
properties:
url:
maxLength: 1024
minLength: 1
type: string
description: URL associated to a listing configuration used for pattern matching.
description: Possible patterns matching values associated to a listing configuration.
example:
- url: https://sports.barca.group/plp/clothing/pants
MultipleStringValuesModel:
required:
- values
type: object
allOf:
- $ref: '#/components/schemas/FieldValueModel'
- type: object
properties:
values:
minItems: 1
type: array
items:
maxLength: 255
minLength: 0
type: string
PublicListingPageRequestModel:
required:
- name
- pageRules
- patterns
- trackingId
type: object
properties:
id:
type: string
description: The unique identifier of the listing page.
format: uuid
readOnly: true
example: 533bba27-2a7f-18fb-b8ed-ed99c3f92f5c
name:
maxLength: 255
minLength: 1
type: string
description: A unique name for the listing configuration.
example: ACME Corp Summer Trends
patterns:
minItems: 1
type: array
description: Possible patterns matching values associated to a listing configuration.
example:
- url: https://sports.barca.group/plp/clothing/pants
items:
$ref: '#/components/schemas/MatchingConfigurationModel'
pageRules:
minItems: 1
type: array
description: List of rules associated to a listing page. Rules are used to determine the page's contents.
example:
- name: Include ec_category_slug contains canoes-kayaks/kayaks/sports-kayaks
locales:
- language: en
country: US
currency: USD
filters:
- fieldName: ec_category_slug
operator: contains
value:
type: array
values:
- canoes-kayaks/kayaks/sports-kayaks
items:
$ref: '#/components/schemas/ListingPageApiPageRuleModel'
trackingId:
maxLength: 255
minLength: 1
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
description: PublicListingPageRequestModel
QueryFilterModel:
required:
- fieldName
- operator
type: object
properties:
fieldName:
pattern: '[a-z][a-z0-9_]*'
type: string
description: The name of the field to apply the filter on.
example: name
operator:
type: string
description: The operator to apply on the field.
example: isExactly
enum:
- isExactly
- isExactlyNot
- contains
- doesNotContain
- isAnyOf
- isDefined
- isNotDefined
- isBetween
- isGreaterThan
- isGreaterThanOrEqualTo
- isLessThan
- isLessThanOrEqualTo
value:
oneOf:
- $ref: '#/components/schemas/DecimalValueModel'
- $ref: '#/components/schemas/HierarchicMultiValueModel'
- $ref: '#/components/schemas/InclusiveRangeModel'
- $ref: '#/components/schemas/MultipleStringValuesModel'
- $ref: '#/components/schemas/SeedRelativeValueModel'
- $ref: '#/components/schemas/StringValueModel'
description: A list of filters.
example:
- fieldName: price
operator: isExactly
value:
type: decimal
value: 99.99
- fieldName: item_count
operator: isBetween
value:
type: range
range:
from: 1000
to: 3000
RangeModel:
type: object
properties:
from:
type: number
format: double
to:
type: number
format: double
SeedRelativeValueModel:
type: object
allOf:
- $ref: '#/components/schemas/FieldValueModel'
StringValueModel:
required:
- value
type: object
allOf:
- $ref: '#/components/schemas/FieldValueModel'
- type: object
properties:
value:
maxLength: 255
minLength: 0
type: string
PublicListingPageResponseModel:
required:
- pageRules
- patterns
type: object
properties:
id:
type: string
description: The unique identifier of the listing page.
format: uuid
readOnly: true
example: 533bba27-2a7f-18fb-b8ed-ed99c3f92f5c
name:
maxLength: 255
minLength: 1
type: string
description: A unique name for the listing configuration.
example: ACME Corp Summer Trends
patterns:
minItems: 1
type: array
description: Possible patterns matching values associated to a listing configuration.
example:
- url: https://sports.barca.group/plp/clothing/pants
items:
$ref: '#/components/schemas/MatchingConfigurationModel'
pageRules:
minItems: 1
type: array
description: List of rules associated to a listing page. Rules are used to determine the page's contents.
example:
- name: Include ec_category_slug contains canoes-kayaks/kayaks/sports-kayaks
locales:
- language: en
country: US
currency: USD
filters:
- fieldName: ec_category_slug
operator: contains
value:
type: array
values:
- canoes-kayaks/kayaks/sports-kayaks
items:
$ref: '#/components/schemas/ListingPageApiPageRuleModel'
trackingId:
maxLength: 255
minLength: 1
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
updatedAt:
type: integer
description: The date and time at which the entity was last updated.
format: int64
readOnly: true
description: PublicListingPageResponseModel
DecimalValueModel_V2ProductView:
required:
- value
type: object
allOf:
- $ref: '#/components/schemas/FieldValueModel_V2ProductView'
- type: object
properties:
value:
type: number
format: double
FieldValueModel_V2ProductView:
required:
- type
type: object
properties:
type:
type: string
description: The value to apply the operator on.
example:
type: string
value: Blue
discriminator:
propertyName: type
FilterRuleModel_V2ProductView:
required:
- action
type: object
properties:
filters:
type: array
description: A list of filters.
example:
- fieldName: price
operator: isExactly
value:
type: decimal
value: 99.99
- fieldName: item_count
operator: isBetween
value:
type: range
range:
from: 1000
to: 3000
items:
$ref: '#/components/schemas/QueryFilterModel_V2ProductView'
action:
type: string
description: Whether the rule is an include or an exclude.
example: include
enum:
- include
- exclude
name:
type: string
description: The name of the rule.
example: 'Pin #1 Short Open-Front Sweater for Women/Boost blue surfboards/Hide green t-shirts'
id:
type: string
format: uuid
readOnly: true
essential:
type: boolean
description: Indicates if the rule is essential to the listing page; the essential rule is added during page creation.
updatedBy:
type: string
description: The user who last updated the rule.
readOnly: true
example: user@coveo.com
updatedAt:
type: string
description: The date and time at which the rule was last updated.
format: date-time
readOnly: true
locales:
type: array
description: The list of locales the rule applies to. When empty, the rule applies to all locales.
example:
- language: en
country: US
currency: USD
items:
$ref: '#/components/schemas/RuleLocaleModel_V2ProductView'
description: A filter rule.
HierarchicMultiValueModel_V2ProductView:
required:
- value
type: object
allOf:
- $ref: '#/components/schemas/FieldValueModel_V2ProductView'
- type: object
properties:
value:
maxLength: 255
minLength: 0
type: string
InclusiveRangeModel_V2ProductView:
required:
- range
type: object
allOf:
- $ref: '#/components/schemas/FieldValueModel_V2ProductView'
- type: object
properties:
range:
$ref: '#/components/schemas/RangeModel_V2ProductView'
ListingRulePreviewRequestModel_V2ProductView:
required:
- country
- currency
- language
- listingId
- previewUrl
- trackingId
type: object
properties:
filterRule:
$ref: '#/components/schemas/FilterRuleModel_V2ProductView'
rankingRule:
$ref: '#/components/schemas/RankingRuleModel_V2ProductView'
pinRule:
$ref: '#/components/schemas/PinRuleModel_V2ProductView'
trackingId:
minLength: 1
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
language:
minLength: 1
type: string
description: An ISO 639-1 language code.
example: en
country:
minLength: 1
type: string
description: An ISO 3166-1 alpha-2 country code.
example: US
currency:
minLength: 1
type: string
description: An ISO 4217 currency code.
example: USD
page:
maximum: 4
minimum: 0
type: integer
description: The page of products to request.
format: int32
example: 7
debug:
type: boolean
description: Whether to include the execution report on a successful response.
example: true
additionalFields:
uniqueItems: true
type: array
description: Some additional fields to include in the preview results.
example:
- cat_color
- cat_gender
items:
type: string
description: Some additional fields to include in the preview results.
example: '["cat_color","cat_gender"]'
perPage:
maximum: 100
type: integer
description: The number of products per page. Note that a value greater than 100 may be rejected in the future.
format: int32
example: 30
default: 30
previewUrl:
minLength: 1
type: string
description: The URL used to retrieve the products listings.
example: http://acme.com/summersale
listingId:
type: string
description: The unique identifier of the listing configuration.
example: 644e1dd7-2a7f-18fb-b8ed-ed78c3f92c2b
listingName:
type: string
description: The name of the listing configuration.
example: My Product Listing
action:
type: string
description: 'Rule action type. One of: [boost, bury, pin, include, exclude].'
example: boost
enum:
- boost
- bury
- pin
- include
- exclude
description: The rule impact preview request to be executed.
MultipleStringValuesModel_V2ProductView:
required:
- values
type: object
allOf:
- $ref: '#/components/schemas/FieldValueModel_V2ProductView'
- type: object
properties:
values:
minItems: 1
type: array
items:
maxLength: 255
minLength: 0
type: string
PinRuleModel_V2ProductView:
type: object
properties:
rankByPermanentId:
type: array
description: A map of product permanent IDs to their desired rank.
example:
'123456789': 1
'987654321': 2
items:
type: object
additionalProperties:
type: integer
format: int32
action:
type: string
description: Whether the rule is a pin.
example: pin
enum:
- pin
name:
type: string
description: The name of the rule.
example: 'Pin #1 Short Open-Front Sweater for Women/Boost blue surfboards/Hide green t-shirts'
id:
type: string
format: uuid
readOnly: true
essential:
type: boolean
description: Indicates if the rule is essential to the listing page; the essential rule is added during page creation.
updatedBy:
type: string
description: The user who last updated the rule.
readOnly: true
example: user@coveo.com
updatedAt:
type: string
description: The date and time at which the rule was last updated.
format: date-time
readOnly: true
locales:
type: array
description: The list of locales the rule applies to. When empty, the rule applies to all locales.
example:
- language: en
country: US
currency: USD
items:
$ref: '#/components/schemas/RuleLocaleModel_V2ProductView'
description: A pin rule.
QueryFilterModel_V2ProductView:
required:
- fieldName
- operator
type: object
properties:
fieldName:
pattern: '[a-z][a-z0-9_]*'
type: string
description: The name of the field to apply the filter on.
example: name
operator:
type: string
description: The operator to apply on the field.
example: isExactly
enum:
- isExactly
- isExactlyNot
- contains
- doesNotContain
- isAnyOf
- isDefined
- isNotDefined
- isBetween
- isGreaterThan
- isGreaterThanOrEqualTo
- isLessThan
- isLessThanOrEqualTo
value:
oneOf:
- $ref: '#/components/schemas/DecimalValueModel_V2ProductView'
- $ref: '#/components/schemas/HierarchicMultiValueModel_V2ProductView'
- $ref: '#/components/schemas/InclusiveRangeModel_V2ProductView'
- $ref: '#/components/schemas/MultipleStringValuesModel_V2ProductView'
- $ref: '#/components/schemas/SeedRelativeValueModel_V2ProductView'
- $ref: '#/components/schemas/StringValueModel_V2ProductView'
description: A list of filters.
example:
- fieldName: price
operator: isExactly
value:
type: decimal
value: 99.99
- fieldName: item_count
operator: isBetween
value:
type: range
range:
from: 1000
to: 3000
RangeModel_V2ProductView:
type: object
properties:
from:
type: number
format: double
to:
type: number
format: double
RankingRuleModel_V2ProductView:
required:
- action
type: object
properties:
filters:
type: array
description: A list of filters.
example:
- fieldName: price
operator: isExactly
value:
type: decimal
value: 99.99
- fieldName: item_count
operator: isBetween
value:
type: range
range:
from: 1000
to: 3000
items:
$ref: '#/components/schemas/QueryFilterModel_V2ProductView'
value:
maximum: 1000
minimum: 0
type: integer
description: The scale at which the rule should be applied.
format: int32
example: 250
action:
type: string
description: Whether the rule is a boost or a bury.
example: boost
enum:
- boost
- bury
name:
type: string
description: The name of the rule.
example: 'Pin #1 Short Open-Front Sweater for Women/Boost blue surfboards/Hide green t-shirts'
id:
type: string
format: uuid
readOnly: true
essential:
type: boolean
description: Indicates if the rule is essential to the listing page; the essential rule is added during page creation.
updatedBy:
type: string
description: The user who last updated the rule.
readOnly: true
example: user@coveo.com
updatedAt:
type: string
description: The date and time at which the rule was last updated.
format: date-time
readOnly: true
locales:
type: array
description: The list of locales the rule applies to. When empty, the rule applies to all locales.
example:
- language: en
country: US
currency: USD
items:
$ref: '#/components/schemas/RuleLocaleModel_V2ProductView'
description: A ranking rule.
RuleLocaleModel_V2ProductView:
type: object
properties:
language:
type: string
description: An ISO 639-1 language code.
example: en
country:
type: string
description: An ISO 3166-1 alpha-2 country code.
example: US
currency:
type: string
description: An ISO 4217 currency code.
example: USD
description: The list of locales the rule applies to. When empty, the rule applies to all locales.
example:
- language: en
country: US
currency: USD
SeedRelativeValueModel_V2ProductView:
type: object
allOf:
- $ref: '#/components/schemas/FieldValueModel_V2ProductView'
StringValueModel_V2ProductView:
required:
- value
type: object
allOf:
- $ref: '#/components/schemas/FieldValueModel_V2ProductView'
- type: object
properties:
value:
maxLength: 255
minLength: 0
type: string
BadgePlacementViewModel_V2ProductView:
type: object
properties:
placementId:
type: string
description: The placement unique identifier.
format: uuid
example: 36164bca-b489-4c42-8574-e1325d56d0be
badges:
type: array
description: The list of badges associated with this placement
items:
$ref: '#/components/schemas/BadgeViewModel_V2ProductView'
description: The list of badge placements associated with this product.
BadgeViewModel_V2ProductView:
type: object
properties:
text:
type: string
description: The localized text displayed on the badge.
example: Bestseller!
backgroundColor:
type: string
description: The badge background color in the format `#RRGGBB`.
example: '#FFFFFF'
textColor:
type: string
description: The badge text color in the format `#RRGGBB`.
example: '#000000'
iconUrl:
type: string
description: The url of an icon to render with the badge text.
example: https://example.com/icon.png
description: The list of badges associated with this placement
ChildProduct_V2ProductView:
type: object
allOf:
- $ref: '#/components/schemas/Product_V2ProductView'
- $ref: '#/components/schemas/Result_V2ProductView'
PaginationResponseModel_V2ProductView:
type: object
properties:
page:
type: integer
description: The page of products to request.
format: int32
example: 7
perPage:
type: integer
description: The number of products per page. Note that a value greater than 100 may be rejected in the future.
format: int32
example: 30
totalEntries:
type: integer
description: The total number of results that match the query.
format: int32
example: 100
totalPages:
type: integer
description: The total number of pages of items available.
format: int32
example: 10
totalProducts:
type: integer
description: The total number of products that match the query.
format: int32
example: 90
totalSpotlightContent:
type: integer
description: The total number of spotlight content that match the query.
format: int32
example: 10
description: Contextual pagination information about the query.
example:
page: 1
perPage: 10
totalPages: 10
totalEntries: 100
PreviewResponseExecutionReportsModel_V2ProductView:
type: object
description: The execution reports for a preview query.
example:
current:
children:
- name: RequestId
description: The id correlating logs for this request
duration: 0
result: null
X-Request-ID: 948cf669-43ae-4d8d-b285-9b66350c5433
- name: Organization ID
description: Organization ID
duration: 0
result: null
coveo_organization: barcasportsmcy01fvu
duration: 88
modified:
children:
- name: RequestId
description: The id correlating logs for this request
duration: 0
result: null
X-Request-ID: 148cf689-63ae-4d8d-b285-9b63350c5433
- name: Organization ID
description: Organization ID
duration: 0
result: null
coveo_organization: barcasportsmcy01fvu
duration: 86
PreviewResponseIdsModel_V2ProductView:
type: object
properties:
current:
type: string
description: The unique identifier of the API response. It can be attached to any subsequent impression or click
event to attribute them to the request.
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
modified:
type: string
description: The unique identifier of the API response. It can be attached to any subsequent impression or click
event to attribute them to the request.
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
description: The unique identifiers of the API responses for a preview request.
example:
current: 123e4567-e89b-12d3-a456-426614174000
modified: 94c3779c-0e42-40b5-95b8-93a6ed3ea162
PreviewResponseModel_V2ProductView:
type: object
properties:
products:
type: array
description: The subset of products returned by the query.
items:
$ref: '#/components/schemas/ProductForPreview_V2ProductView'
results:
type: array
description: List of results including products and spotlight content
items:
$ref: '#/components/schemas/PreviewResult_V2ProductView'
pagination:
$ref: '#/components/schemas/PaginationResponseModel_V2ProductView'
responseIds:
$ref: '#/components/schemas/PreviewResponseIdsModel_V2ProductView'
executionReports:
$ref: '#/components/schemas/PreviewResponseExecutionReportsModel_V2ProductView'
queryCorrection:
$ref: '#/components/schemas/QueryCorrectionResponse_V2ProductView'
PreviewResult_V2ProductView:
required:
- resultType
type: object
properties:
resultType:
type: string
description: Preview result item that can be a product or spotlight content (including placeholders)
discriminator:
propertyName: resultType
ProductForPreview_V2ProductView:
type: object
allOf:
- $ref: '#/components/schemas/Product_V2ProductView'
- type: object
properties:
score:
type: integer
description: The total ranking score computed for the product.
format: int32
example: 1292
scoreDifference:
type: integer
description: Score difference between the cached and previewed rules for a product.
format: int32
example: 1292
positionDifference:
type: integer
description: Position difference between the cached and previewed rules for a product.
format: int32
example: 9
included:
type: boolean
description: Whether the product has been included or not after applying a rule.
pinned:
type: boolean
description: Whether the product has been pinned or not after applying a rule.
reservedPosition:
type: boolean
description: Whether the product is in a position that is reserved for a query-time pin.
- $ref: '#/components/schemas/Result_V2ProductView'
QueryCorrectionResponse_V2ProductView:
type: object
properties:
originalQuery:
type: string
description: If the query was automatically corrected, this property indicates the original basic query expression
(q) that triggered the automatic query correction.
correctedQuery:
type: string
description: If the query was automatically corrected, this property indicates the corrected basic query expression
(q) that was executed instead of the original one.
corrections:
type: array
description: If the query wasn't automatically corrected, this property contains the basic query expression (q)
keyword corrections provided by the Did You Mean index feature.
example:
- correctedQuery: Coveo Cloud V2 platform
wordCorrections:
- correctedWord: platform
length: 8
offset: 15
originalWord: plattfomr
items:
$ref: '#/components/schemas/QueryCorrection_V2ProductView'
description: The query correction response, if the query was corrected.
QueryCorrection_V2ProductView:
type: object
properties:
correctedQuery:
type: string
description: The resulting query expression correction suggestion.
wordCorrections:
type: array
description: The word correction suggestions.
items:
$ref: '#/components/schemas/WordCorrection_V2ProductView'
description: If the query wasn't automatically corrected, this property contains the basic query expression (q) keyword
corrections provided by the Did You Mean index feature.
example:
- correctedQuery: Coveo Cloud V2 platform
wordCorrections:
- correctedWord: platform
length: 8
offset: 15
originalWord: plattfomr
WordCorrection_V2ProductView:
type: object
properties:
correctedWord:
type: string
description: The suggested word correction.
length:
type: integer
description: The length (in number of characters) of the corrected word.
format: int32
offset:
type: integer
description: The offset (in number of characters) of the corrected word, from the beginning of the resulting query
expression correction suggestion.
format: int32
originalWord:
type: string
description: The original, un-corrected word.
description: The word correction suggestions.
AbstractFacetRequestModelObject:
required:
- displayNames
- field
type: object
properties:
facetId:
type: string
description: The facet id. Common practice is to use the facet field name, unless there are multiple facet configurations
for the same field.
example: ec_brand
field:
minLength: 1
pattern: ^([a-z][a-z0-9_]{0,254})$
type: string
description: The facet field name.
example: ec_brand
displayNames:
minItems: 1
uniqueItems: true
type: array
description: The facet display name with its associated language.
items:
$ref: '#/components/schemas/DisplayName'
values:
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
type: object
description: The values displayed by the facet in the search interface at the moment of the request.
numberOfValues:
type: integer
description: The maximum number of facet values to fetch.
format: int32
type:
type: string
description: 'One of: `regular`, `dateRange`, `numericalRange`, `hierarchical`. For more information, see the [facet
types](https://docs.coveo.com/en/p3oa0420#facet-types) documentation.'
enum:
- regular
- dateRange
- numericalRange
- hierarchical
- regular
description: The facet operations to perform on the listing query.
discriminator:
propertyName: type
AbstractSortModel:
type: object
properties:
sortCriteria:
type: string
description: The criterion to use for sorting the results.
enum:
- relevance
- fields
description: Determines the order in which to retrieve the results.
example:
- sortCriteria: fields
fields:
- field: ec_price
direction: asc
displayNames:
- value: Price
language: en
- value: Prix
language: fr
discriminator:
propertyName: sortCriteria
BasePath:
required:
- language
- value
type: object
properties:
value:
minItems: 1
type: array
description: The base path shared by all values for the facet.
items:
type: string
language:
minLength: 1
type: string
description: An ISO 639-1 language code.
example: en
description: List of localized Base path shared by all values for the facet.
DateRangeFacetRequestModel:
required:
- displayNames
- field
type: object
description: Date range facet.
example:
facetId: year
field: year
displayNames:
- value: Year
language: en
- value: Année
language: fr
values:
- state: idle
preventAutoSelect: false
start: 2023/10/01@00:00:00
end: 2023/10/31@23:59:59
endInclusive: true
- state: idle
preventAutoSelect: true
start: 2023/11/01@00:00:00
end: 2023/11/30@23:59:59
endInclusive: false
- state: selected
preventAutoSelect: true
start: 2023/12/01@00:00:00
end: 2023/12/31@23:59:59
endInclusive: true
numberOfValues: 3
preventAutoSelect: false
sortCriteria: score
isFieldExpanded: true
type: dateRange
generateAutomaticRanges: true
allOf:
- $ref: '#/components/schemas/AbstractFacetRequestModelObject'
- type: object
properties:
values:
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
$ref: '#/components/schemas/DateRangeFacetRequestValueModel'
generateAutomaticRanges:
type: boolean
description: Whether to automatically generate range values for this facet.
freezeCurrentValues:
type: boolean
description: Whether to freeze the current list of facet values. Setting this to true keeps the facet from moving
around while the end-user interacts with it on the storefront.
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
sortCriteria:
type: string
description: The criterion to use for sorting returned facet values.
enum:
- score
- alphanumericNatural
- alphanumeric
- occurrences
filterFacetCount:
type: boolean
description: 'Default: `false`
Whether to exclude folded result parents when estimating the result count for
each facet value (see SearchAPI''s doc for more details).
Note: Note: The target folding field
must be a facet field with the ''Use cache for nested queries'' options enabled.'
isFieldExpanded:
type: boolean
description: Whether the facet is expanded in the search interface at the moment of the request.
DateRangeFacetRequestValueModel:
required:
- end
- start
type: object
properties:
state:
type: string
description: The current facet value state in the search interface.
enum:
- idle
- selected
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
start:
minLength: 1
type: string
description: The value to start the range at.
end:
minLength: 1
type: string
description: The value to end the range at. Must be greater (or later) than the start value.
endInclusive:
type: boolean
description: Whether to include the end value in the range.
description: The values displayed by the facet in the search interface at the moment of the request.
DisplayName:
required:
- language
- value
type: object
properties:
value:
minLength: 1
type: string
description: DEPRECATED - The display name of a field.
language:
minLength: 1
type: string
description: An ISO 639-1 language code.
example: en
description: The display names of a field to sort by associated with its language.
FacetRequestModel:
type: object
properties:
enableIndexFacetOrdering:
type: boolean
description: 'Default: `true`
Whether to take into account the scores generated by the index when reordering
facets.
Note: Setting this to `false` implies that only the scores generated by a Coveo ML DNE
model will be taken into account when automatically reordering facets. To completely disable automatic facet reordering,
set `freezeFacetOrder` to `true` instead.'
freezeFacetOrder:
type: boolean
description: 'Default: `false`
Whether facets should be returned in the same order in which they were requested.
Note:
Setting this to `true` completely disables automatic facet reordering. To allow automatic facet reordering, but
only take into account the scores generated by a Coveo ML DNE model, set `enableIndexFacetOrdering` to `false`
instead.'
facets:
type: array
description: The facet operations to perform on the listing query.
items:
oneOf:
- $ref: '#/components/schemas/DateRangeFacetRequestModel'
- $ref: '#/components/schemas/HierarchicalFacetRequestModel'
- $ref: '#/components/schemas/NumericalRangeFacetRequestModel'
- $ref: '#/components/schemas/RegularFacetRequestModel'
description: 'DEPRECATED ON 2026-08-31: The facet request configuration. See https://docs.coveo.com/en/q3cc0299/deprecations/legacy-commerce-api-facet-management-deprecation
for more details on the deprecation.'
FilterRuleModel:
required:
- action
type: object
properties:
filters:
type: array
description: A list of filters.
example:
- fieldName: price
operator: isExactly
value:
type: decimal
value: 99.99
- fieldName: item_count
operator: isBetween
value:
type: range
range:
from: 1000
to: 3000
items:
$ref: '#/components/schemas/QueryFilterModel'
action:
type: string
description: Whether the rule is an include or an exclude.
example: include
enum:
- include
- exclude
name:
type: string
description: The name of the rule.
example: 'Pin #1 Short Open-Front Sweater for Women/Boost blue surfboards/Hide green t-shirts'
id:
type: string
format: uuid
readOnly: true
essential:
type: boolean
description: Indicates if the rule is essential to the listing page; the essential rule is added during page creation.
updatedBy:
type: string
description: The user who last updated the rule.
readOnly: true
example: user@coveo.com
updatedAt:
type: string
description: The date and time at which the rule was last updated.
format: date-time
readOnly: true
locales:
type: array
description: The list of locales the rule applies to. When empty, the rule applies to all locales.
example:
- language: en
country: US
currency: USD
items:
$ref: '#/components/schemas/RuleLocaleModel'
description: List of the filter rules.
HierarchicalFacetRequestModel:
required:
- displayNames
- field
type: object
description: Hierarchical (tree-like) facet.
example:
facetId: ec_category
field: ec_category
displayNames:
- value: Category
language: en
- value: Catégorie
language: fr
values:
- state: selected
preventAutoSelect: true
value: Canoes & Kayaks
children:
- state: selected
preventAutoSelect: true
value: Kayaks
children:
- state: selected
preventAutoSelect: true
value: Folding Kayaks
- state: idle
preventAutoSelect: true
value: Sea Kayaks
- state: selected
preventAutoSelect: false
value: Canoes
numberOfValues: 5
preventAutoSelect: true
sortCriteria: score
isFieldExpanded: true
type: hierarchical
delimitingCharacter: '|'
basePaths:
value:
- Boats
language: en
filterByBasePath: true
allOf:
- $ref: '#/components/schemas/AbstractFacetRequestModelObject'
- type: object
properties:
values:
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
$ref: '#/components/schemas/HierarchicalFacetRequestValueModel'
delimitingCharacter:
type: string
description: The character to use to split field values into a hierarchical sequence.
basePaths:
uniqueItems: true
type: array
description: List of localized Base path shared by all values for the facet.
items:
$ref: '#/components/schemas/BasePath'
filterByBasePath:
type: boolean
description: Whether to use basePath as a filter for the results.
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
sortCriteria:
type: string
description: The criterion to use for sorting returned facet values.
enum:
- score
- alphanumericNatural
- alphanumeric
- occurrences
filterFacetCount:
type: boolean
description: 'Default: `false`
Whether to exclude folded result parents when estimating the result count for
each facet value (see SearchAPI''s doc for more details).
Note: Note: The target folding field
must be a facet field with the ''Use cache for nested queries'' options enabled.'
retrieveCount:
type: integer
description: The maximum number of children to retrieve for this hierarchical facet values.
format: int32
isFieldExpanded:
type: boolean
description: Whether the facet is expanded in the search interface at the moment of the request.
HierarchicalFacetRequestValueModel:
required:
- value
type: object
properties:
state:
type: string
description: The current facet value state in the search interface.
enum:
- idle
- selected
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
value:
minLength: 1
type: string
description: This represents a single path segment.
children:
type: array
description: The children of this hierarchical facet value.
items:
$ref: '#/components/schemas/HierarchicalFacetRequestValueModel'
retrieveCount:
type: integer
description: The maximum number of children to retrieve for this hierarchical facet value. Ignored if retrieveChildren
is false.
format: int32
description: The values displayed by the facet in the search interface at the moment of the request.
NumericalRangeFacetRequestModel:
required:
- displayNames
- field
type: object
description: Numerical range facet.
example:
facetId: ec_price
field: ec_price
displayNames:
- value: Price
language: en
- value: Prix
language: fr
values:
- state: idle
preventAutoSelect: true
start: '0'
end: '999'
endInclusive: 'true'
- state: selected
preventAutoSelect: true
start: '1000'
end: '2000'
endInclusive: 'false'
- state: selected
preventAutoSelect: true
start: '2001'
end: '3000'
endInclusive: 'false'
numberOfValues: 3
preventAutoSelect: true
sortCriteria: score
isFieldExpanded: true
type: numericalRange
generateAutomaticRanges: true
rangeAlgorithm: equiprobable
allOf:
- $ref: '#/components/schemas/AbstractFacetRequestModelObject'
- type: object
properties:
values:
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
$ref: '#/components/schemas/NumericalRangeFacetRequestValueModel'
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
filterFacetCount:
type: boolean
description: 'Default: `false`
Whether to exclude folded result parents when estimating the result count for
each facet value (see SearchAPI''s doc for more details).
Note: Note: The target folding field
must be a facet field with the ''Use cache for nested queries'' options enabled.'
generateAutomaticRanges:
type: boolean
description: Whether to automatically generate range values for this facet.
interval:
type: string
description: Determines the range interval type. Default is `continuous`.
default: continuous
enum:
- continuous
- discrete
- even
- equiprobable
domain:
$ref: '#/components/schemas/RangeDomain'
freezeCurrentValues:
type: boolean
description: Whether to freeze the current list of facet values. Setting this to true keeps the facet from moving
around while the end-user interacts with it on the storefront.
rangeAlgorithm:
type: string
description: Determines which algorithm is used to generate the ranges if generateAutomaticRanges is enabled.
enum:
- equiprobable
- even
sortCriteria:
type: string
description: The criterion to use for sorting returned facet values.
enum:
- score
- alphanumericNatural
- alphanumeric
- occurrences
isFieldExpanded:
type: boolean
description: Whether the facet is expanded in the search interface at the moment of the request.
NumericalRangeFacetRequestValueModel:
required:
- end
- start
type: object
properties:
state:
type: string
description: The current facet value state in the search interface.
enum:
- idle
- selected
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
start:
type: number
description: The value to start the range at.
end:
type: number
description: The value to end the range at. Must be greater (or later) than the start value.
endInclusive:
type: boolean
description: Whether to include the end value in the range.
description: The values displayed by the facet in the search interface at the moment of the request.
PinRuleModel:
type: object
properties:
rankByPermanentId:
type: array
description: A map of product permanent IDs to their desired rank.
example:
'123456789': 1
'987654321': 2
items:
type: object
additionalProperties:
type: integer
format: int32
action:
type: string
description: Whether the rule is a pin.
example: pin
enum:
- pin
name:
type: string
description: The name of the rule.
example: 'Pin #1 Short Open-Front Sweater for Women/Boost blue surfboards/Hide green t-shirts'
id:
type: string
format: uuid
readOnly: true
essential:
type: boolean
description: Indicates if the rule is essential to the listing page; the essential rule is added during page creation.
updatedBy:
type: string
description: The user who last updated the rule.
readOnly: true
example: user@coveo.com
updatedAt:
type: string
description: The date and time at which the rule was last updated.
format: date-time
readOnly: true
locales:
type: array
description: The list of locales the rule applies to. When empty, the rule applies to all locales.
example:
- language: en
country: US
currency: USD
items:
$ref: '#/components/schemas/RuleLocaleModel'
description: List of the pin rules.
QueryConfigurationLegacyModel:
type: object
properties:
additionalFields:
uniqueItems: true
type: array
description: To retrieve [additional fields](https://docs.coveo.com/en/n73f0502#create-additional-commerce-fields)
you have created, that aren’t part of the [standard commerce fields](https://docs.coveo.com/en/n73f0502#standard-commerce-fields),
specify them here. These fields appear in the `additionalFields` object in the response.
example:
- color
- shirtsize
items:
type: string
facets:
$ref: '#/components/schemas/FacetRequestModel'
perPage:
maximum: 100
minimum: 0
type: integer
description: The number of results to include per page.
Note: The specified value applies only to
parent items, not their grouped children. Query performance may be affected when returned items include many grouped
products.
format: int32
example: 20
sorts:
type: array
description: Determines the order in which to retrieve the results.
example:
- sortCriteria: fields
fields:
- field: ec_price
direction: asc
displayNames:
- value: Price
language: en
- value: Prix
language: fr
items:
oneOf:
- $ref: '#/components/schemas/SortByFieldsModel'
- $ref: '#/components/schemas/SortByRelevanceModel'
filterFieldRange:
type: integer
description: 'Default: `5`
The maximum number of items to include in the childResults array of a folded query
result (see SearchAPI''s doc for more details).'
format: int32
productGrouping:
type: string
description: The product grouping. Determines if pin rules should consider results to be grouped on the query pipeline,
or not.
enum:
- none
- query_pipeline
description: Query configuration.
RangeDomain:
required:
- max
- min
type: object
properties:
min:
minimum: 0
type: integer
format: int32
max:
maximum: 1000000
type: integer
format: int32
increment:
maximum: 1000000
minimum: 0
type: integer
format: int32
description: Limits the range values to the specified domain.
RankingRuleModel:
required:
- action
type: object
properties:
filters:
type: array
description: A list of filters.
example:
- fieldName: price
operator: isExactly
value:
type: decimal
value: 99.99
- fieldName: item_count
operator: isBetween
value:
type: range
range:
from: 1000
to: 3000
items:
$ref: '#/components/schemas/QueryFilterModel'
value:
maximum: 1000
minimum: 0
type: integer
description: The scale at which the rule should be applied.
format: int32
example: 250
action:
type: string
description: Whether the rule is a boost or a bury.
example: boost
enum:
- boost
- bury
name:
type: string
description: The name of the rule.
example: 'Pin #1 Short Open-Front Sweater for Women/Boost blue surfboards/Hide green t-shirts'
id:
type: string
format: uuid
readOnly: true
essential:
type: boolean
description: Indicates if the rule is essential to the listing page; the essential rule is added during page creation.
updatedBy:
type: string
description: The user who last updated the rule.
readOnly: true
example: user@coveo.com
updatedAt:
type: string
description: The date and time at which the rule was last updated.
format: date-time
readOnly: true
locales:
type: array
description: The list of locales the rule applies to. When empty, the rule applies to all locales.
example:
- language: en
country: US
currency: USD
items:
$ref: '#/components/schemas/RuleLocaleModel'
description: List of the ranking rules.
RegularFacetRequestModel:
required:
- displayNames
- field
type: object
description: Regular (single string value) facet.
example:
facetId: ec_brand
field: ec_brand
displayNames:
- value: Brand
language: en
- value: Marque
language: fr
values:
- state: selected
preventAutoSelect: false
value: Aqua Sports
- state: idle
preventAutoSelect: false
value: Aqua Marina
- state: idle
preventAutoSelect: false
value: HO Sports
numberOfValues: 3
preventAutoSelect: false
sortCriteria: score
isFieldExpanded: true
type: regular
customOrder:
- string
allOf:
- $ref: '#/components/schemas/AbstractFacetRequestModelObject'
- type: object
properties:
values:
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
$ref: '#/components/schemas/RegularFacetRequestValueModel'
customOrder:
type: array
description: A custom sort order for the facet values.
items:
type: string
freezeCurrentValues:
type: boolean
description: Whether to freeze the current list of facet values. Setting this to true keeps the facet from moving
around while the end-user interacts with it on the storefront.
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
sortCriteria:
type: string
description: The criterion to use for sorting returned facet values.
enum:
- score
- alphanumericNatural
- alphanumeric
- occurrences
filterFacetCount:
type: boolean
description: 'Default: `false`
Whether to exclude folded result parents when estimating the result count for
each facet value (see SearchAPI''s doc for more details).
Note: Note: The target folding field
must be a facet field with the ''Use cache for nested queries'' options enabled.'
resultsMustMatch:
type: string
description: Specifies how a result must match the selected values.
default: atLeastOneValue
enum:
- atLeastOneValue
- allValues
isFieldExpanded:
type: boolean
description: Whether the facet is expanded in the search interface at the moment of the request.
RegularFacetRequestValueModel:
required:
- value
type: object
properties:
state:
type: string
description: The current facet value state in the search interface.
enum:
- idle
- selected
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
value:
minLength: 1
type: string
description: The facet value name.
description: The values displayed by the facet in the search interface at the moment of the request.
RulesModel:
type: object
properties:
rankingRules:
type: array
description: List of the ranking rules.
items:
$ref: '#/components/schemas/RankingRuleModel'
filterRules:
type: array
description: List of the filter rules.
items:
$ref: '#/components/schemas/FilterRuleModel'
pinRules:
type: array
description: List of the pin rules.
items:
$ref: '#/components/schemas/PinRuleModel'
description: Rules to apply at query time.
SearchConditionModel:
required:
- operator
- values
type: object
properties:
operator:
type: string
description: The operator for the search condition.
enum:
- isExactly
- contains
values:
maxItems: 1
minItems: 0
type: array
description: Values that are used by the operator.
items:
type: string
description: Values that are used by the operator.
description: Search conditions associated to query-based rules on a search configuration.
SearchConfigurationModel:
required:
- rules
- trackingId
type: object
properties:
id:
type: string
description: The unique identifier of the search configuration.
format: uuid
readOnly: true
example: 755e2dd8-3a8f-19fb-b9ed-ed89c4f83c3b
name:
maxLength: 255
minLength: 1
type: string
description: A unique name for the search configuration.
example: Queries including `Summer`
trackingId:
maxLength: 255
minLength: 1
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
conditions:
maxItems: 1
minItems: 0
uniqueItems: true
type: array
description: Search conditions associated to query-based rules on a search configuration.
items:
$ref: '#/components/schemas/SearchConditionModel'
queryConfiguration:
$ref: '#/components/schemas/QueryConfigurationLegacyModel'
rules:
$ref: '#/components/schemas/RulesModel'
scope:
type: string
description: 'Rule scope to return. One of: [specific, global]. Returns all if not specified.'
example: specific
enum:
- global
- specific
SortByFieldModel:
required:
- displayNames
- field
type: object
properties:
field:
minLength: 1
pattern: ^([a-z][a-z0-9_]{0,254})$
type: string
description: The name of a field to sort by.
direction:
type: string
description: 'Sort order:
Default: `ascending`
- `asc` - Ascending, from A to Z
- `desc` - Descending,
from Z to A
'
enum:
- asc
- desc
displayNames:
minItems: 1
uniqueItems: true
type: array
description: The display names of a field to sort by associated with its language.
items:
$ref: '#/components/schemas/DisplayName'
description: Defines the fields and, optionally, their sort order.
SortByFieldsModel:
required:
- fields
type: object
allOf:
- $ref: '#/components/schemas/AbstractSortModel'
- type: object
properties:
fields:
minItems: 1
type: array
description: Defines the fields and, optionally, their sort order.
items:
$ref: '#/components/schemas/SortByFieldModel'
SortByRelevanceModel:
type: object
allOf:
- $ref: '#/components/schemas/AbstractSortModel'
QueryConfigurationModel:
type: object
properties:
additionalFields:
uniqueItems: true
type: array
description: To retrieve [additional fields](https://docs.coveo.com/en/n73f0502#create-additional-commerce-fields)
you have created, that aren’t part of the [standard commerce fields](https://docs.coveo.com/en/n73f0502#standard-commerce-fields),
specify them here. These fields appear in the `additionalFields` object in the response.
example:
- color
- shirtsize
items:
type: string
facets:
$ref: '#/components/schemas/FacetRequestModel'
perPage:
maximum: 100
minimum: 0
type: integer
description: The number of results to include per page.
Note: The specified value applies only to
parent items, not their grouped children. Query performance may be affected when returned items include many grouped
products.
format: int32
example: 20
sorts:
type: array
description: Determines the order in which to retrieve the results.
example:
- sortCriteria: fields
fields:
- field: ec_price
direction: asc
displayNames:
- value: Price
language: en
- value: Prix
language: fr
items:
oneOf:
- $ref: '#/components/schemas/SortByFieldsModel'
- $ref: '#/components/schemas/SortByRelevanceModel'
numberOfChildren:
type: integer
description: Equivalent to `filterFieldRange` in the Search API. The maximum number of items to include in the childResults
array of a folded query result (see SearchAPI's doc for more details).
format: int32
grouping:
$ref: '#/components/schemas/QueryParamGroupingOverridesConfigModel'
description: Query configuration.
QueryConfigurationRequestModel:
required:
- configurationModel
- solutionType
- trackingId
type: object
properties:
trackingId:
maxLength: 255
minLength: 1
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
solutionType:
type: string
description: The solution type for the rule. It can be either 'listing' or 'search' or 'recommendations'.
enum:
- listing
- search
- recommendation
targets:
maxItems: 1
minItems: 1
type: array
description: List of target identifiers e.g. listing page name, slot ID
example:
- Surf With Us This Year
items:
type: string
description: List of target identifiers e.g. listing page name, slot ID
example: '["Surf With Us This Year"]'
isGlobal:
type: boolean
description: Whether the query configuration is globally applied.
default: false
configurationModel:
$ref: '#/components/schemas/QueryConfigurationModel'
description: Request for editing query configurations.
QueryParamGroupingOverridesConfigModel:
required:
- type
type: object
properties:
type:
type: string
description: The product grouping. Determines if pin rules should consider results to be grouped on the query pipeline,
or not.
enum:
- none
- query_pipeline
description: The product grouping. Determines if pin rules should consider results to be grouped on the query pipeline,
or not.
ProductSuggestConfigurationModel:
required:
- trackingId
type: object
properties:
id:
type: string
description: The unique identifier of the search configuration.
format: uuid
readOnly: true
example: 755e2dd8-3a8f-19fb-b9ed-ed89c4f83c3b
trackingId:
maxLength: 255
minLength: 1
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
queryConfiguration:
$ref: '#/components/schemas/QueryConfigurationLegacyModel'
description: Product suggest configuration
ListingConfigurationModel:
required:
- name
- patterns
- rules
- trackingId
type: object
properties:
id:
type: string
description: The unique identifier of the listing configuration.
format: uuid
readOnly: true
example: 644e1dd7-2a7f-18fb-b8ed-ed78c3f92c2b
name:
maxLength: 255
minLength: 1
type: string
description: A unique name for the listing configuration.
example: ACME Corp Summer Trends
trackingId:
maxLength: 255
minLength: 1
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
patterns:
minItems: 1
type: array
description: Possible patterns matching values associated to a listing configuration.
example:
- url: https://sports.barca.group/plp/clothing/pants
items:
$ref: '#/components/schemas/MatchingConfigurationModel'
queryConfiguration:
$ref: '#/components/schemas/QueryConfigurationLegacyModel'
rules:
$ref: '#/components/schemas/RulesModel'
facetCollectionConfigurationId:
type: string
description: The unique identifier of the [facet collection configuration](https://docs.coveo.com/en/p5890502/glossary/facet-collection).Can
only be modified via /facetCollection endpoint
format: uuid
readOnly: true
example: 755e2dd8-3a8f-19fb-b9ed-ed89c4f83c3b
scope:
type: string
description: 'Rule scope to return. One of: [specific, global]. Returns all if not specified.'
example: specific
enum:
- global
- specific
BadgeRequestModel:
required:
- context
- country
- currency
- language
- placementIds
type: object
properties:
language:
minLength: 1
type: string
description: An ISO 639-1 language code.
example: en
country:
minLength: 1
type: string
description: An ISO 3166-1 alpha-2 country code.
example: US
currency:
minLength: 1
type: string
description: An ISO 4217 currency code.
example: USD
placementIds:
maxItems: 5
minItems: 1
uniqueItems: true
type: array
description: The list of placement unique identifiers for which to retrieve badges. Maximum of 5 placement IDs allowed
per request.
example:
- 36164bca-b489-4c42-8574-e1325d56d0be
- 47275dcb-c590-5d53-9685-f2436e67e1cf
items:
type: string
description: The list of placement unique identifiers for which to retrieve badges. Maximum of 5 placement IDs
allowed per request.
format: uuid
context:
$ref: '#/components/schemas/BadgingContextModel'
description: The badge request containing placement identifiers and context information to retrieve badges for products.
BadgingContextModel:
required:
- view
type: object
properties:
user:
$ref: '#/components/schemas/UserModel'
view:
$ref: '#/components/schemas/ViewModel'
cart:
type: array
description: The cart information.
items:
$ref: '#/components/schemas/CartItemModel'
source:
type: array
description: Defines one or more client side libraries that generated the analytics event. The format should be
the library's name followed by '@', and then the version. For example, '[custom.library.js@2.0.0]'.
example:
- '@coveo/headless@2.61.0'
- custom.library.js@2.0.0
items:
minLength: 1
pattern: ^[^@]*@.*$
type: string
description: A context source
example: '@coveo/headless@2.61.0'
capture:
type: boolean
description: Whether the request should be tracked for analytics and machine learning purposes. When set to `true`,
this will trigger a server-side event to be logged. When set to `false`, the server-side event will not be logged.
example: true
labels:
type: object
additionalProperties:
type: string
description: Deprecated - The context labels.
example: '{"category":"garden > garden-tools > chainsaws","brand":"ACME"}'
description: Deprecated - The context labels.
example:
category: garden > garden-tools > chainsaws
brand: ACME
custom:
type: object
additionalProperties:
type: object
description: Custom context values under context.custom. Use this for context mapping.
example:
fitmentProducts:
- sku_123
- sku_456
description: Custom context values under context.custom. Use this for context mapping.
example:
fitmentProducts:
- sku_123
- sku_456
product:
$ref: '#/components/schemas/ProductItemModel'
description: Contextual information about the query.
CartItemModel:
type: object
properties:
productId:
type: string
description: The id of the product.
example: shoe-a1-red
quantity:
type: integer
description: The product quantity.
format: int32
example: 2
description: A cart item.
ProductItemModel:
type: object
properties:
productId:
type: string
description: The id of the product.
example: shoe-a1-red
description: The product ID used to generate the recommendations.
UserModel:
type: object
properties:
userAgent:
type: string
description: 'The user agent of the request. If not present, the user agent is obtained from the [User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent)
header.\n\n**Note**: This information is required when endpoints are behind a proxy.'
example: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36
description: The user information.
ViewModel:
required:
- url
type: object
properties:
url:
minLength: 1
type: string
description: The URL used to retrieve the products. Used as `documentLocation` for analytics purposes, which indicates
the URL of the resource where the request originated.
example: https://acme.com/summersale
referrer:
type: string
description: Typically the URL of the page that linked to the interface from which the request originates (e.g.,
in JavaScript, this would correspond to the `document.referrer` value).\n\nCoveo Machine Learning models may use
this information to provide contextually relevant output. Used as `documentReferrer` for analytics purposes.
nullable: true
example: https://example.com/
description: 'A collection of data points describing the view. Note: The term ''view'' is used instead of ''page'' to
accommodate usage in contexts such as mobile apps.'
BadgePlacementViewModel:
type: object
properties:
placementId:
type: string
description: The placement unique identifier.
format: uuid
example: 36164bca-b489-4c42-8574-e1325d56d0be
badges:
type: array
description: The list of badges associated with this placement
items:
$ref: '#/components/schemas/BadgeViewModel'
description: The list of badge placements associated with this product.
BadgeViewModel:
type: object
properties:
text:
type: string
description: The localized text displayed on the badge.
example: Bestseller!
backgroundColor:
type: string
description: The badge background color in the format `#RRGGBB`.
example: '#FFFFFF'
textColor:
type: string
description: The badge text color in the format `#RRGGBB`.
example: '#000000'
iconUrl:
type: string
description: The url of an icon to render with the badge text.
example: https://example.com/icon.png
description: The list of badges associated with this placement
NonPaginatedProductResponseProductBadgeViewModel:
type: object
properties:
products:
type: array
description: The list of products
items:
$ref: '#/components/schemas/ProductBadgeViewModel'
ProductBadgeViewModel:
type: object
properties:
productId:
type: string
description: The product identifier.
example: 0000003035-45
badgePlacements:
type: array
description: The list of badge placements associated with this product.
items:
$ref: '#/components/schemas/BadgePlacementViewModel'
description: The list of products
PipelineSetup:
required:
- pipelineId
type: object
properties:
pipelineId:
minLength: 1
type: string
description: The identifier of the pipeline used to process the query.
example: 9716d88a-f02b-480e-bf44-ab1b1af165a8
pipelineProductGrouping:
$ref: '#/components/schemas/ProductGrouping'
deactivateRankingFactor:
type: boolean
description: Indicates whether the ranking factors should be deactivated for the pipeline. If null, the ranking
factors will not be changed.
example: false
description: List of pipeline setups to configure
ProductGrouping:
required:
- trackingId
type: object
properties:
trackingId:
type: string
description: The tracking id which we wish to applied global grouping to.
example: MyTrackingID
globalProductGroupingEnabled:
type: boolean
description: Indicates whether the pipeline should be grouped. Use this option to control the aggregation behavior of
the pipeline. If null, the grouping will not be changed.
SetupRequestModel:
required:
- trackingIdToCatalogMapping
type: object
properties:
trackingId:
maxLength: 255
minLength: 1
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
trackingIdToCatalogMapping:
type: array
description: The mappings related to the supplied tracking IDs
items:
$ref: '#/components/schemas/TrackingIdToCatalogMappingSetupModel'
pipelineSetups:
type: array
description: List of pipeline setups to configure
items:
$ref: '#/components/schemas/PipelineSetup'
description: The scaffolding to setup.
TrackingIdToCatalogMappingSetupModel:
required:
- catalogName
- country
- currency
- language
type: object
properties:
catalogName:
type: string
description: The name of the catalog for this mapping
example: MyCatalog
language:
pattern: ^[a-z]{2}$
type: string
description: Language code that must conform to the ISO 639-1 language code specification
example: en
country:
pattern: ^[A-Z]{2}$
type: string
description: Country code that must conform to the ISO 3166-1 country code specification
example: GB
currency:
pattern: ^[A-Z]{3}$
type: string
description: Currency code that must conform to the ISO 4217 currency code specification
example: USD
description: The mappings related to the supplied tracking IDs
GlobalConfigurationUpdatedModel:
type: object
properties:
productGrouping:
type: string
description: 'Indicates whether the product grouping configuration was updated by the setup request. Possible values:
`QUERY_PIPELINE` or `NONE`.'
example: NONE
enum:
- none
- query_pipeline
pipelineId:
type: string
description: The query pipelines updated by the setup request.
example: pipelineId
description: The list of updated global configurations.
QueryPipelineConfigurationModel:
type: object
properties:
id:
type: string
description: The unique identifier of the pipeline in UUID format.
readOnly: true
example: 9a0914c9-08d4-42f6-ba37-44c8c3d4c196
name:
type: string
description: The unique identifier of the pipeline in UUID format.
readOnly: true
example: 9a0914c9-08d4-42f6-ba37-44c8c3d4c196
deactivateRankingFactor:
type: boolean
pipelineProductGroupingEnabled:
type: boolean
description: The list of query pipeline configurations created or modified.
SetupResponseModel:
type: object
properties:
queryPipelines:
type: array
description: The list of query pipeline configurations created or modified.
items:
$ref: '#/components/schemas/QueryPipelineConfigurationModel'
globalConfigurationUpdated:
type: array
description: The list of updated global configurations.
items:
$ref: '#/components/schemas/GlobalConfigurationUpdatedModel'
trackingIdToCatalogMapping:
type: array
items:
$ref: '#/components/schemas/TrackingIdToCatalogMappingModel'
TrackingIdToCatalogMappingCatalogModel:
type: object
properties:
id:
type: string
description: The unique identifier of this catalog
format: uuid
example: 644e1dd7-2a7f-18fb-b8ed-ed78c3f92c2b
name:
type: string
description: The name of the catalog
sourceName:
type: string
description: The source name of the catalog
example: acmecorporation8tp8wu3-qwpdaajjq3ahak5wlq7adhciuq
availabilitySourceName:
type: string
description: The source name containing the availability for the catalog
example: availabilitysource
catalogConfiguration:
$ref: '#/components/schemas/TrackingIdToCatalogMappingCatalogModelCatalogConfiguration'
description: This will contain the full catalog info as per the catalog resource
TrackingIdToCatalogMappingCatalogModelCatalogConfiguration:
type: object
properties:
product:
$ref: '#/components/schemas/TrackingIdToCatalogMappingCatalogModelCatalogConfigurationProduct'
available:
$ref: '#/components/schemas/TrackingIdToCatalogMappingCatalogModelCatalogConfigurationAvailability'
description: The configuration of the catalog
TrackingIdToCatalogMappingCatalogModelCatalogConfigurationAvailability:
type: object
properties:
idField:
type: string
description: The unique identifier of this availability in the catalog
example: availabilityid
TrackingIdToCatalogMappingCatalogModelCatalogConfigurationProduct:
type: object
properties:
idField:
type: string
description: The unique identifier of this product in the catalog
example: productid
TrackingIdToCatalogMappingModel:
required:
- catalogName
- country
- currency
- language
- primary
type: object
properties:
catalogName:
type: string
description: The name of the catalog for this mapping
example: MyCatalog
language:
pattern: ^[a-z]{2}$
type: string
description: Language code that must conform to the ISO 639-1 language code specification
example: en
country:
pattern: ^[A-Z]{2}$
type: string
description: Country code that must conform to the ISO 3166-1 country code specification
example: GB
currency:
pattern: ^[A-Z]{3}$
type: string
description: Currency code that must conform to the ISO 4217 currency code specification
example: USD
primary:
type: boolean
description: Determines if this mapping is the primary one for a specific tracking id
example: true
catalog:
$ref: '#/components/schemas/TrackingIdToCatalogMappingCatalogModel'
AbstractSortRequestResponseModel_V2SearchProductView:
type: object
properties:
sortCriteria:
type: string
description: The criterion to use for sorting the results.
enum:
- relevance
- fields
description: Determines the order in which to retrieve the results.
example:
- sortCriteria: fields
fields:
- field: ec_price
direction: asc
displayNames:
- value: Price
language: en
- value: Prix
language: fr
discriminator:
propertyName: sortCriteria
default: relevance
CartItemModel_V2SearchProductView:
type: object
properties:
productId:
type: string
description: The id of the product.
example: shoe-a1-red
quantity:
type: integer
description: The product quantity.
format: int32
example: 2
description: A cart item.
ContextModel_V2SearchProductView:
required:
- view
type: object
properties:
user:
$ref: '#/components/schemas/UserModel_V2SearchProductView'
view:
$ref: '#/components/schemas/ViewModel_V2SearchProductView'
cart:
type: array
description: The cart information.
items:
$ref: '#/components/schemas/CartItemModel_V2SearchProductView'
source:
type: array
description: Defines one or more client side libraries that generated the analytics event. The format should be
the library's name followed by '@', and then the version. For example, '[custom.library.js@2.0.0]'.
example:
- '@coveo/headless@2.61.0'
- custom.library.js@2.0.0
items:
minLength: 1
pattern: ^[^@]*@.*$
type: string
description: A context source
example: '@coveo/headless@2.61.0'
capture:
type: boolean
description: Whether the request should be tracked for analytics and machine learning purposes. When set to `true`,
this will trigger a server-side event to be logged. When set to `false`, the server-side event will not be logged.
example: true
labels:
type: object
additionalProperties:
type: string
description: Deprecated - The context labels.
example: '{"category":"garden > garden-tools > chainsaws","brand":"ACME"}'
description: Deprecated - The context labels.
example:
category: garden > garden-tools > chainsaws
brand: ACME
custom:
type: object
additionalProperties:
type: object
description: Custom context values under context.custom. Use this for context mapping.
example:
fitmentProducts:
- sku_123
- sku_456
description: Custom context values under context.custom. Use this for context mapping.
example:
fitmentProducts:
- sku_123
- sku_456
description: Contextual information about the query.
DateRangeFacetModel_V2SearchProductView:
required:
- field
- values
type: object
description: Date range facet.
example:
facetId: year
field: year
displayNames:
- value: Year
language: en
- value: Année
language: fr
values:
- state: idle
preventAutoSelect: false
start: 2023/10/01@00:00:00
end: 2023/10/31@23:59:59
endInclusive: true
- state: idle
preventAutoSelect: true
start: 2023/11/01@00:00:00
end: 2023/11/30@23:59:59
endInclusive: false
- state: selected
preventAutoSelect: true
start: 2023/12/01@00:00:00
end: 2023/12/31@23:59:59
endInclusive: true
numberOfValues: 3
preventAutoSelect: false
sortCriteria: score
isFieldExpanded: true
type: dateRange
generateAutomaticRanges: true
allOf:
- $ref: '#/components/schemas/RequestFacetBaseObject_V2SearchProductView'
- type: object
properties:
values:
minItems: 1
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
$ref: '#/components/schemas/DateRangeValueModel_V2SearchProductView'
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
sortCriteria:
type: string
description: The criterion to use for sorting returned facet values.
enum:
- score
- alphanumericNatural
- alphanumeric
- occurrences
generateAutomaticRanges:
type: boolean
description: Whether to automatically generate range values for this facet.
freezeCurrentValues:
type: boolean
description: Should always be set to `false` except when selecting/unselecting facet values. See [here](https://docs.coveo.com/en/3199/build-a-search-ui/implement-facets#toggle-facet-values)
for more guidance.
isFieldExpanded:
type: boolean
description: The value provided is only copied back in the `isFieldExpanded` property of the response. It does
not affect the behaviour of the Commerce Service in any way.
DateRangeValueModel_V2SearchProductView:
required:
- end
- start
type: object
properties:
state:
type: string
description: The current facet value state in the search interface.
enum:
- idle
- selected
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
start:
minLength: 1
type: string
description: The value to start the range at.
end:
minLength: 1
type: string
description: The value to end the range at. Must be greater (or later) than the start value.
endInclusive:
type: boolean
description: Whether to include the end value in the range.
description: The values displayed by the facet in the search interface at the moment of the request.
HierarchicalFacetModel_V2SearchProductView:
required:
- field
- values
type: object
description: Hierarchical (tree-like) facet.
example:
facetId: ec_category
field: ec_category
displayNames:
- value: Category
language: en
- value: Catégorie
language: fr
values:
- state: selected
preventAutoSelect: true
value: Canoes & Kayaks
children:
- state: selected
preventAutoSelect: true
value: Kayaks
children:
- state: selected
preventAutoSelect: true
value: Folding Kayaks
- state: idle
preventAutoSelect: true
value: Sea Kayaks
- state: selected
preventAutoSelect: false
value: Canoes
numberOfValues: 5
preventAutoSelect: true
sortCriteria: score
isFieldExpanded: true
type: hierarchical
delimitingCharacter: '|'
basePath:
- Boats
filterByBasePath: true
allOf:
- $ref: '#/components/schemas/RequestFacetBaseObject_V2SearchProductView'
- type: object
properties:
values:
minItems: 1
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
$ref: '#/components/schemas/HierarchicalValueModel_V2SearchProductView'
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
sortCriteria:
type: string
description: The criterion to use for sorting returned facet values.
enum:
- score
- alphanumericNatural
- alphanumeric
- occurrences
delimitingCharacter:
type: string
description: The character to use to split field values into a hierarchical sequence.
filterByBasePath:
type: boolean
description: Whether to use basePath as a filter for the results.
retrieveCount:
type: object
properties:
empty:
type: boolean
present:
type: boolean
asInt:
type: integer
format: int32
description: The maximum number of children to retrieve for this hierarchical facet values.
isFieldExpanded:
type: boolean
description: The value provided is only copied back in the `isFieldExpanded` property of the response. It does
not affect the behaviour of the Commerce Service in any way.
HierarchicalValueModel_V2SearchProductView:
required:
- value
type: object
properties:
state:
type: string
description: The current facet value state in the search interface.
enum:
- idle
- selected
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
value:
minLength: 1
type: string
description: This represents a single path segment.
children:
type: array
description: The children of this hierarchical facet value.
items:
$ref: '#/components/schemas/HierarchicalValueModel_V2SearchProductView'
retrieveCount:
type: integer
description: The maximum number of children to retrieve for this hierarchical facet value. Ignored if retrieveChildren
is false.
format: int32
description: The values displayed by the facet in the search interface at the moment of the request.
LegacyFacetOptions_V2SearchProductView:
type: object
properties:
freezeFacetOrder:
type: boolean
description: 'Default: `false`
Whether facets should be returned in the same order in which they were requested.'
description: Facet Options for legacy (v1) facets.
NumericalRangeFacetModel_V2SearchProductView:
required:
- field
- values
type: object
description: Numerical range facet.
example:
facetId: ec_price
field: ec_price
displayNames:
- value: Price
language: en
- value: Prix
language: fr
values:
- state: idle
preventAutoSelect: true
start: '0'
end: '999'
endInclusive: 'true'
- state: selected
preventAutoSelect: true
start: '1000'
end: '2000'
endInclusive: 'false'
- state: selected
preventAutoSelect: true
start: '2001'
end: '3000'
endInclusive: 'false'
numberOfValues: 3
preventAutoSelect: true
sortCriteria: score
isFieldExpanded: true
type: numericalRange
allOf:
- $ref: '#/components/schemas/RequestFacetBaseObject_V2SearchProductView'
- type: object
properties:
values:
minItems: 1
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
$ref: '#/components/schemas/NumericalRangeValueModel_V2SearchProductView'
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
sortCriteria:
type: string
description: The criterion to use for sorting returned facet values.
enum:
- score
- alphanumericNatural
- alphanumeric
- occurrences
interval:
type: string
description: Determines the range interval type. Default is `continuous`.
default: continuous
enum:
- continuous
- discrete
- even
- equiprobable
domain:
$ref: '#/components/schemas/RangeDomain_V2SearchProductView'
freezeCurrentValues:
type: boolean
description: Should always be set to `false` except when selecting/unselecting facet values. See [here](https://docs.coveo.com/en/3199/build-a-search-ui/implement-facets#toggle-facet-values)
for more guidance.
isFieldExpanded:
type: boolean
description: The value provided is only copied back in the `isFieldExpanded` property of the response. It does
not affect the behaviour of the Commerce Service in any way.
NumericalRangeValueModel_V2SearchProductView:
required:
- end
- start
type: object
properties:
state:
type: string
description: The current facet value state in the search interface.
enum:
- idle
- selected
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
start:
type: number
description: The value to start the range at.
end:
type: number
description: The value to end the range at. Must be greater (or later) than the start value.
endInclusive:
type: boolean
description: Whether to include the end value in the range. It should typically be set to the value last received
in the `endInclusive` property of the facet response.
description: The values displayed by the facet in the search interface at the moment of the request.
RangeDomain_V2SearchProductView:
required:
- max
- min
type: object
properties:
min:
minimum: 0
type: integer
format: int32
max:
maximum: 1000000
type: integer
format: int32
increment:
maximum: 1000000
minimum: 0
type: integer
format: int32
description: Limits the range values to the specified domain.
RegularFacetModel_V2SearchProductView:
required:
- field
- values
type: object
description: Regular (single string value) facet.
example:
facetId: ec_brand
field: ec_brand
displayNames:
- value: Brand
language: en
- value: Marque
language: fr
values:
- state: selected
preventAutoSelect: false
value: Aqua Sports
- state: idle
preventAutoSelect: false
value: Aqua Marina
- state: idle
preventAutoSelect: false
value: HO Sports
numberOfValues: 3
preventAutoSelect: false
sortCriteria: score
isFieldExpanded: true
type: regular
customOrder:
- string
allOf:
- $ref: '#/components/schemas/RequestFacetBaseObject_V2SearchProductView'
- type: object
properties:
values:
minItems: 1
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
$ref: '#/components/schemas/RegularValueModel_V2SearchProductView'
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
sortCriteria:
type: string
description: The criterion to use for sorting returned facet values.
enum:
- score
- alphanumericNatural
- alphanumeric
- occurrences
customOrder:
type: array
description: A custom sort order for the facet values.
items:
type: string
freezeCurrentValues:
type: boolean
description: Should always be set to `false` except when selecting/unselecting facet values. See [here](https://docs.coveo.com/en/3199/build-a-search-ui/implement-facets#toggle-facet-values)
for more guidance.
resultsMustMatch:
type: string
description: Specifies how a result must match the selected values.
default: atLeastOneValue
enum:
- atLeastOneValue
- allValues
isFieldExpanded:
type: boolean
description: The value provided is only copied back in the `isFieldExpanded` property of the response. It does
not affect the behaviour of the Commerce Service in any way.
RegularValueModel_V2SearchProductView:
required:
- value
type: object
properties:
state:
type: string
description: The current facet value state in the search interface.
enum:
- idle
- selected
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
value:
minLength: 1
type: string
description: The facet value name.
description: The values displayed by the facet in the search interface at the moment of the request.
RequestFacetBaseObject_V2SearchProductView:
required:
- field
- values
type: object
properties:
facetId:
type: string
description: Name of the field to execute the facet search request against.
example: color
field:
minLength: 1
type: string
description: The facet field name.
example: ec_brand
displayName:
type: string
description: The facet display name.
example: Brand
values:
minItems: 1
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
type: object
description: The values displayed by the facet in the search interface at the moment of the request.
numberOfValues:
type: object
properties:
empty:
type: boolean
present:
type: boolean
asInt:
type: integer
format: int32
description: 'The maximum number of facet values to fetch. It should typically be set to the value last received
in the `numberOfValues` property of the facet response.
An exception to this guideline is the case where the last response had
`moreValuesAvailable=true` and the user asks to see more values for this facet. In this case,
the front-end is expected to send a value greater than the `numberOfValues` that it last received
in the response. This ensures that more values are fetched from the index.
When not provided, the default number of values configured for this facet is used.
'
type:
type: string
description: 'One of: `regular`, `dateRange`, `numericalRange`, `hierarchical`. For more information, see the [facet
types](https://docs.coveo.com/en/p3oa0420#facet-types) documentation.'
enum:
- regular
- dateRange
- numericalRange
- hierarchical
- regular
description: The facet operations to perform on the query. Note that this parameter is ignored in the '/productSuggest'
endpoint.
example:
- field: ec_category
type: regular
values:
- value: shoes
state: idle
discriminator:
propertyName: type
SearchRequestModel_V2SearchProductView:
required:
- context
- country
- currency
- language
- query
- trackingId
type: object
properties:
trackingId:
minLength: 1
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
language:
minLength: 1
type: string
description: An ISO 639-1 language code.
example: en
country:
minLength: 1
type: string
description: An ISO 3166-1 alpha-2 country code.
example: US
currency:
minLength: 1
type: string
description: An ISO 4217 currency code.
example: USD
clientId:
type: string
description: A GUID which represents the current client.\n\nIf your implementation uses the Atomic or Headless libraries,
then the [client ID](https://docs.coveo.com/en/masb0234/) is generated automatically in client-side code.\n\nIf
you have a custom Coveo implementation, you will have to generate a [UUID v4]()-formatted
GUID. You will need to send this ID in every request that is sent to the Commerce API.\n\nCoveo Machine Learning
models may use this information to provide contextually relevant output.
example: 58bb4b98-1daa-4767-8c15-90a0ea67645c
facets:
type: array
description: The facet operations to perform on the query. Note that this parameter is ignored in the '/productSuggest'
endpoint.
example:
- field: ec_category
type: regular
values:
- value: shoes
state: idle
items:
oneOf:
- $ref: '#/components/schemas/DateRangeFacetModel_V2SearchProductView'
- $ref: '#/components/schemas/HierarchicalFacetModel_V2SearchProductView'
- $ref: '#/components/schemas/NumericalRangeFacetModel_V2SearchProductView'
- $ref: '#/components/schemas/RegularFacetModel_V2SearchProductView'
page:
minimum: 0
type: integer
description: The page of products to request.
format: int32
example: 7
perPage:
maximum: 1000
minimum: 1
type: integer
description: The number of products per page. Note that a value greater than 100 may be rejected in the future.
format: int32
example: 30
sort:
oneOf:
- $ref: '#/components/schemas/SortByFieldsRequestResponseModel_V2SearchProductView'
- $ref: '#/components/schemas/SortByRelevanceRequestResponseModel_V2SearchProductView'
debug:
type: boolean
description: Whether to include the execution report on a successful response.
example: true
query:
type: string
description: The query expression, typically the keywords entered by the end user in a search box.
example: blue shoes
context:
$ref: '#/components/schemas/ContextModel_V2SearchProductView'
legacyFacetOptions:
$ref: '#/components/schemas/LegacyFacetOptions_V2SearchProductView'
enableResults:
type: boolean
description: Enable spotlight content in the results. When enabled, the products list in the response will always
be empty and the results list should be used instead.
description: The query suggestion request to be executed.
SortByFieldRequestResponseModel_V2SearchProductView:
required:
- field
type: object
properties:
field:
minLength: 1
type: string
description: The name of a field to sort by.
direction:
type: string
description: 'Sort order:
Default: `ascending`
- `asc` - Ascending, from A to Z
- `desc` - Descending,
from Z to A
'
enum:
- asc
- desc
displayName:
type: string
description: The display name of a field.
description: Defines the fields and, optionally, their sort order.
SortByFieldsRequestResponseModel_V2SearchProductView:
required:
- fields
type: object
allOf:
- $ref: '#/components/schemas/AbstractSortRequestResponseModel_V2SearchProductView'
- type: object
properties:
fields:
minItems: 1
type: array
description: Defines the fields and, optionally, their sort order.
items:
$ref: '#/components/schemas/SortByFieldRequestResponseModel_V2SearchProductView'
SortByRelevanceRequestResponseModel_V2SearchProductView:
type: object
allOf:
- $ref: '#/components/schemas/AbstractSortRequestResponseModel_V2SearchProductView'
UserModel_V2SearchProductView:
type: object
properties:
userAgent:
type: string
description: 'The user agent of the request. If not present, the user agent is obtained from the [User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent)
header.\n\n**Note**: This information is required when endpoints are behind a proxy.'
example: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36
description: The user information.
ViewModel_V2SearchProductView:
required:
- url
type: object
properties:
url:
minLength: 1
type: string
description: The URL used to retrieve the products. Used as `documentLocation` for analytics purposes, which indicates
the URL of the resource where the request originated.
example: https://acme.com/summersale
referrer:
type: string
description: Typically the URL of the page that linked to the interface from which the request originates (e.g.,
in JavaScript, this would correspond to the `document.referrer` value).\n\nCoveo Machine Learning models may use
this information to provide contextually relevant output. Used as `documentReferrer` for analytics purposes.
nullable: true
example: https://example.com/
description: 'A collection of data points describing the view. Note: The term ''view'' is used instead of ''page'' to
accommodate usage in contexts such as mobile apps.'
AbstractFacetResultObject_V2SearchProductView:
required:
- type
type: object
properties:
facetId:
type: string
field:
type: string
displayName:
type: string
values:
type: array
items:
type: object
numberOfValues:
type: integer
description: 'The number of values that were requested to the index for this facet. When the facet
is part of the request and the `numberOfValues` request parameter is not null, the returned value
will be equal to the value found in the request. Otherwise, the returned value will be equal to
the default number of values configured for this facet.
Note: This value can be greater than the number of values returned in the `values` array.
'
format: int32
type:
type: string
description: The available facets. Note that this array will always be empty in the '/productSuggest' endpoint.
discriminator:
propertyName: type
BadgePlacementViewModel_V2SearchProductView:
type: object
properties:
placementId:
type: string
description: The placement unique identifier.
format: uuid
example: 36164bca-b489-4c42-8574-e1325d56d0be
badges:
type: array
description: The list of badges associated with this placement
items:
$ref: '#/components/schemas/BadgeViewModel_V2SearchProductView'
description: The list of badge placements associated with this product.
BadgeViewModel_V2SearchProductView:
type: object
properties:
text:
type: string
description: The localized text displayed on the badge.
example: Bestseller!
backgroundColor:
type: string
description: The badge background color in the format `#RRGGBB`.
example: '#FFFFFF'
textColor:
type: string
description: The badge text color in the format `#RRGGBB`.
example: '#000000'
iconUrl:
type: string
description: The url of an icon to render with the badge text.
example: https://example.com/icon.png
description: The list of badges associated with this placement
ChildProduct_V2SearchProductView:
type: object
allOf:
- $ref: '#/components/schemas/Result_V2SearchProductView'
DateRangeFacetResultValue_V2SearchProductView:
type: object
properties:
state:
type: string
enum:
- idle
- selected
numberOfResults:
type: integer
format: int64
isAutoSelected:
type: boolean
isSuggested:
type: boolean
moreValuesAvailable:
type: boolean
start:
type: string
end:
type: string
endInclusive:
type: boolean
DateRangeFacetResult_V2SearchProductView:
type: object
allOf:
- $ref: '#/components/schemas/AbstractFacetResultObject_V2SearchProductView'
- type: object
properties:
values:
type: array
items:
$ref: '#/components/schemas/DateRangeFacetResultValue_V2SearchProductView'
moreValuesAvailable:
type: boolean
fromAutoSelect:
type: boolean
isFieldExpanded:
type: boolean
description: 'The value received in the `isFieldExpanded` property of the request. If the facet was
not part of the request, `false` is returned.
'
HierarchicalFacetResultValue_V2SearchProductView:
type: object
properties:
state:
type: string
enum:
- idle
- selected
numberOfResults:
type: integer
format: int64
isAutoSelected:
type: boolean
isSuggested:
type: boolean
moreValuesAvailable:
type: boolean
description: Whether additional facet values matching the request are available.
value:
type: string
description: This represents a single path segment.
path:
type: array
items:
type: string
isLeafValue:
type: boolean
children:
type: array
description: The children of this hierarchical facet value.
items:
$ref: '#/components/schemas/HierarchicalFacetResultValue_V2SearchProductView'
HierarchicalFacetResult_V2SearchProductView:
type: object
allOf:
- $ref: '#/components/schemas/AbstractFacetResultObject_V2SearchProductView'
- type: object
properties:
values:
type: array
items:
$ref: '#/components/schemas/HierarchicalFacetResultValue_V2SearchProductView'
delimitingCharacter:
type: string
moreValuesAvailable:
type: boolean
fromAutoSelect:
type: boolean
isFieldExpanded:
type: boolean
description: 'The value received in the `isFieldExpanded` property of the request. If the facet was
not part of the request, `false` is returned.
'
Highlight_V2SearchProductView:
type: object
properties:
length:
type: integer
description: The length of the highlight.
format: int32
example: 4
offset:
type: integer
description: The offset of the highlight.
format: int32
example: 15
description: The product exerts highlights.
NumericalRangeFacetResultValue_V2SearchProductView:
type: object
properties:
state:
type: string
enum:
- idle
- selected
numberOfResults:
type: integer
format: int64
isAutoSelected:
type: boolean
isSuggested:
type: boolean
moreValuesAvailable:
type: boolean
start:
type: number
end:
type: number
endInclusive:
type: boolean
NumericalRangeFacetResult_V2SearchProductView:
type: object
allOf:
- $ref: '#/components/schemas/AbstractFacetResultObject_V2SearchProductView'
- type: object
properties:
values:
type: array
items:
$ref: '#/components/schemas/NumericalRangeFacetResultValue_V2SearchProductView'
moreValuesAvailable:
type: boolean
fromAutoSelect:
type: boolean
domain:
$ref: '#/components/schemas/RangeDomain_V2SearchProductView'
interval:
type: string
enum:
- continuous
- discrete
- even
- equiprobable
isFieldExpanded:
type: boolean
description: 'The value received in the `isFieldExpanded` property of the request. If the facet was
not part of the request, `false` is returned.
'
PaginationResponseModel_V2SearchProductView:
type: object
properties:
page:
type: integer
description: The page of products to request.
format: int32
example: 7
perPage:
type: integer
description: The number of products per page. Note that a value greater than 100 may be rejected in the future.
format: int32
example: 30
totalEntries:
type: integer
description: The total number of results that match the query.
format: int32
example: 100
totalPages:
type: integer
description: The total number of pages of items available.
format: int32
example: 10
totalProducts:
type: integer
description: The total number of products that match the query.
format: int32
example: 90
totalSpotlightContent:
type: integer
description: The total number of spotlight content that match the query.
format: int32
example: 10
description: Contextual pagination information about the query.
example:
page: 1
perPage: 10
totalPages: 10
totalEntries: 100
ProductForPreview_V2SearchProductView:
type: object
allOf:
- $ref: '#/components/schemas/Result_V2SearchProductView'
- type: object
properties:
score:
type: integer
description: The total ranking score computed for the product.
format: int32
example: 1292
scoreDifference:
type: integer
description: Score difference between the cached and previewed rules for a product.
format: int32
example: 1292
positionDifference:
type: integer
description: Position difference between the cached and previewed rules for a product.
format: int32
example: 9
included:
type: boolean
description: Whether the product has been included or not after applying a rule.
pinned:
type: boolean
description: Whether the product has been pinned or not after applying a rule.
reservedPosition:
type: boolean
description: Whether the product is in a position that is reserved for a query-time pin.
Product_V2SearchProductView:
type: object
allOf:
- $ref: '#/components/schemas/Result_V2SearchProductView'
- type: object
properties:
additionalFields:
type: object
additionalProperties:
type: object
description: The product additional fields.
example:
size: M
material: cotton
description: The product additional fields.
example:
size: M
material: cotton
queryPinned:
type: boolean
description: Indicates whether the product was pinned by a reserved position rule.
example: true
badgePlacements:
type: array
description: The list of badge placements associated with this product.
items:
$ref: '#/components/schemas/BadgePlacementViewModel_V2SearchProductView'
ec_name:
type: string
description: The product name.
example: ACME T-Shirt.
ec_description:
type: string
description: The product description.
example: A very nice T-Shirt. Comes in blue and green colors.
ec_shortdesc:
type: string
description: The product short description.
example: A very nice T-Shirt.
ec_brand:
type: string
description: The product brand.
example: ACME
ec_category:
type: array
description: The product category.
example:
- T-Shirts
items:
type: string
description: The product category.
example: '["T-Shirts"]'
ec_thumbnails:
type: array
description: The product thumbnails.
example:
- https://example.com/thumbnail1.jpg
- https://example.com/thumbnail2.jpg
items:
type: string
description: The product thumbnails.
example: '["https://example.com/thumbnail1.jpg","https://example.com/thumbnail2.jpg"]'
ec_images:
type: array
description: The product images.
example:
- https://example.com/image1.jpg
- https://example.com/image2.jpg
items:
type: string
description: The product images.
example: '["https://example.com/image1.jpg","https://example.com/image2.jpg"]'
ec_price:
type: number
description: The product price.
format: double
example: 19.99
ec_promo_price:
type: number
description: The product promotional price.
format: double
example: 14.99
ec_in_stock:
type: boolean
description: The product availability.
example: true
ec_item_group_id:
type: string
description: The product item group identifier.
example: '0000003035'
ec_rating:
type: number
description: The product rating.
format: double
example: 4.5
ec_product_id:
type: string
description: The product identifier.
example: 0000003035-45
ec_gender:
type: string
description: The intended gender of the product user.
example: M
ec_color:
type: string
description: The product color.
example: Blue
ec_listing:
type: string
description: The product listing.
example: T-Shirt
clickUri:
type: string
description: The product click URI.
example: https://example.com/product/0000003035-45
permanentid:
type: string
description: The product permanent identifier.
example: 0000003035-45
nameHighlights:
type: array
description: The product name highlights.
example:
- ACME
- T-Shirt
items:
$ref: '#/components/schemas/Highlight_V2SearchProductView'
excerpt:
type: string
description: The product exerts.
example: The T-Shirt is very nice
excerptHighlights:
type: array
description: The product exerts highlights.
items:
$ref: '#/components/schemas/Highlight_V2SearchProductView'
children:
type: array
description: The product child results.
items:
$ref: '#/components/schemas/ChildProduct_V2SearchProductView'
totalNumberOfChildren:
type: integer
description: The total number of child results.
format: int32
example: 2
QueryCorrectionResponse_V2SearchProductView:
type: object
properties:
originalQuery:
type: string
description: If the query was automatically corrected, this property indicates the original basic query expression
(q) that triggered the automatic query correction.
correctedQuery:
type: string
description: If the query was automatically corrected, this property indicates the corrected basic query expression
(q) that was executed instead of the original one.
corrections:
type: array
description: If the query wasn't automatically corrected, this property contains the basic query expression (q)
keyword corrections provided by the Did You Mean index feature.
example:
- correctedQuery: Coveo Cloud V2 platform
wordCorrections:
- correctedWord: platform
length: 8
offset: 15
originalWord: plattfomr
items:
$ref: '#/components/schemas/QueryCorrection_V2SearchProductView'
description: The query correction response, if the query was corrected.
QueryCorrection_V2SearchProductView:
type: object
properties:
correctedQuery:
type: string
description: The resulting query expression correction suggestion.
wordCorrections:
type: array
description: The word correction suggestions.
items:
$ref: '#/components/schemas/WordCorrection_V2SearchProductView'
description: If the query wasn't automatically corrected, this property contains the basic query expression (q) keyword
corrections provided by the Did You Mean index feature.
example:
- correctedQuery: Coveo Cloud V2 platform
wordCorrections:
- correctedWord: platform
length: 8
offset: 15
originalWord: plattfomr
RegularFacetResultValue_V2SearchProductView:
type: object
properties:
state:
type: string
enum:
- idle
- selected
numberOfResults:
type: integer
format: int64
isAutoSelected:
type: boolean
isSuggested:
type: boolean
moreValuesAvailable:
type: boolean
value:
type: string
RegularFacetResult_V2SearchProductView:
type: object
allOf:
- $ref: '#/components/schemas/AbstractFacetResultObject_V2SearchProductView'
- type: object
properties:
values:
type: array
items:
$ref: '#/components/schemas/RegularFacetResultValue_V2SearchProductView'
moreValuesAvailable:
type: boolean
fromAutoSelect:
type: boolean
isFieldExpanded:
type: boolean
description: 'The value received in the `isFieldExpanded` property of the request. If the facet was
not part of the request, `false` is returned.
'
Result_V2SearchProductView:
required:
- resultType
type: object
properties:
resultType:
type: string
description: List of results including products and spotlight content
discriminator:
propertyName: resultType
SearchResponseModel_V2SearchProductView:
type: object
properties:
responseId:
type: string
description: The unique identifier of the API response. It can be attached to any subsequent impression or click
event to attribute them to the request.
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
products:
type: array
description: The subset of products returned by the query.
items:
oneOf:
- $ref: '#/components/schemas/Product_V2SearchProductView'
- $ref: '#/components/schemas/ChildProduct_V2SearchProductView'
- $ref: '#/components/schemas/ProductForPreview_V2SearchProductView'
results:
type: array
description: List of results including products and spotlight content
items:
oneOf:
- $ref: '#/components/schemas/ChildProduct_V2SearchProductView'
- $ref: '#/components/schemas/ProductForPreview_V2SearchProductView'
- $ref: '#/components/schemas/Product_V2SearchProductView'
- $ref: '#/components/schemas/SpotlightContentModel_V2SearchProductView'
facets:
type: array
description: The available facets. Note that this array will always be empty in the '/productSuggest' endpoint.
items:
oneOf:
- $ref: '#/components/schemas/DateRangeFacetResult_V2SearchProductView'
- $ref: '#/components/schemas/HierarchicalFacetResult_V2SearchProductView'
- $ref: '#/components/schemas/NumericalRangeFacetResult_V2SearchProductView'
- $ref: '#/components/schemas/RegularFacetResult_V2SearchProductView'
pagination:
$ref: '#/components/schemas/PaginationResponseModel_V2SearchProductView'
sort:
$ref: '#/components/schemas/SortResponseModel_V2SearchProductView'
triggers:
type: array
description: The actions for the client to perform based on the Trigger statements defined.
example:
- type: redirect
content: https://www.example.com
items:
$ref: '#/components/schemas/TriggerModel_V2SearchProductView'
queryCorrection:
$ref: '#/components/schemas/QueryCorrectionResponse_V2SearchProductView'
SortResponseModel_V2SearchProductView:
type: object
properties:
appliedSort:
oneOf:
- $ref: '#/components/schemas/SortByFieldsRequestResponseModel_V2SearchProductView'
- $ref: '#/components/schemas/SortByRelevanceRequestResponseModel_V2SearchProductView'
availableSorts:
type: array
description: The list of available sorting methods.
example:
- sortCriteria: relevance
- sortCriteria: fields
fields:
- field: ec_price
direction: desc
displayName: Price
items:
oneOf:
- $ref: '#/components/schemas/SortByFieldsRequestResponseModel_V2SearchProductView'
- $ref: '#/components/schemas/SortByRelevanceRequestResponseModel_V2SearchProductView'
description: The applied and available sort options for the query.
example:
appliedSort:
sortCriteria: fields
fields:
- field: ec_brand
direction: asc
displayName: Brand
availableSorts:
- sortCriteria: relevance
- sortCriteria: fields
fields:
- field: ec_price
direction: desc
displayName: Price
SpotlightContentModel_V2SearchProductView:
required:
- clickUri
- desktopImage
type: object
description: Spotlight Content
allOf:
- $ref: '#/components/schemas/Result_V2SearchProductView'
- type: object
properties:
id:
type: string
description: The unique identifier of the spotlight content
format: uuid
readOnly: true
example: 123e4567-e89b-12d3-a456-426614174000
name:
maxLength: 255
minLength: 1
type: string
description: The name of the spotlight content
example: Summer Sale
description:
maxLength: 255
minLength: 1
type: string
description: The description of the spotlight content
example: Get up to 50% off on summer items
clickUri:
maxLength: 1024
minLength: 1
type: string
description: The click URI for the spotlight content
example: https://example.com/summer-sale
desktopImage:
maxLength: 1024
minLength: 1
type: string
description: The desktop image URL for the spotlight content
example: https://example.com/images/summer-sale-desktop.jpg
mobileImage:
maxLength: 1024
minLength: 1
type: string
description: The mobile image URL for the spotlight content
example: https://example.com/images/summer-sale-mobile.jpg
nameFontColor:
type: string
description: The font color for the name text in the format `#RRGGBB`.
example: '#000000'
descriptionFontColor:
type: string
description: The font color for the description text in the format `#RRGGBB`.
example: '#000000'
altText:
maxLength: 255
minLength: 1
type: string
description: The alt text for the spotlight content image for accessibility
example: Summer sale promotional banner
TriggerModel_V2SearchProductView:
type: object
properties:
type:
type: string
description: The type of trigger.
example: redirect
enum:
- execute
- notify
- redirect
- query
content:
type: string
description: The content of the trigger.
example: https://www.example.com
description: The actions for the client to perform based on the Trigger statements defined.
example:
- type: redirect
content: https://www.example.com
WordCorrection_V2SearchProductView:
type: object
properties:
correctedWord:
type: string
description: The suggested word correction.
length:
type: integer
description: The length (in number of characters) of the corrected word.
format: int32
offset:
type: integer
description: The offset (in number of characters) of the corrected word, from the beginning of the resulting query
expression correction suggestion.
format: int32
originalWord:
type: string
description: The original, un-corrected word.
description: The word correction suggestions.
RedirectContextModel_V2SearchProductView:
required:
- view
type: object
properties:
user:
$ref: '#/components/schemas/UserModel_V2SearchProductView'
view:
$ref: '#/components/schemas/ViewModel_V2SearchProductView'
source:
type: array
description: Defines one or more client side libraries that generated the analytics event. The format should be
the library's name followed by '@', and then the version. For example, '[custom.library.js@2.0.0]'.
example:
- '@coveo/headless@2.61.0'
- custom.library.js@2.0.0
items:
minLength: 1
pattern: ^[^@]*@.*$
type: string
description: A context source
example: '@coveo/headless@2.61.0'
capture:
type: boolean
description: Whether the request should be tracked for analytics and machine learning purposes. When set to `true`,
this will trigger a server-side event to be logged. When set to `false`, the server-side event will not be logged.
example: true
description: Contextual information about the query.
SearchRedirectRequestModel_V2SearchProductView:
required:
- context
- country
- currency
- language
- query
- trackingId
type: object
properties:
query:
type: string
description: The query expression, typically the keywords entered by the end user in a search box.
example: blue shoes
trackingId:
minLength: 1
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
language:
minLength: 1
type: string
description: An ISO 639-1 language code.
example: en
country:
minLength: 1
type: string
description: An ISO 3166-1 alpha-2 country code.
example: US
currency:
minLength: 1
type: string
description: An ISO 4217 currency code.
example: USD
context:
$ref: '#/components/schemas/RedirectContextModel_V2SearchProductView'
clientId:
type: string
description: A GUID which represents the current client.\n\nIf your implementation uses the Atomic or Headless libraries,
then the [client ID](https://docs.coveo.com/en/masb0234/) is generated automatically in client-side code.\n\nIf
you have a custom Coveo implementation, you will have to generate a [UUID v4]()-formatted
GUID. You will need to send this ID in every request that is sent to the Commerce API.\n\nCoveo Machine Learning
models may use this information to provide contextually relevant output.
format: uuid
example: 58bb4b98-1daa-4767-8c15-90a0ea67645c
debug:
type: boolean
description: Whether to include the execution report on a successful response.
example: true
description: The search query to be executed.
SearchRedirectResponseModel_V2SearchProductView:
type: object
properties:
redirect:
type: string
description: The redirect URL.
example: https://example.com/products
ContextModel:
required:
- view
type: object
properties:
user:
$ref: '#/components/schemas/UserModel'
view:
$ref: '#/components/schemas/ViewModel'
cart:
type: array
description: The cart information.
items:
$ref: '#/components/schemas/CartItemModel'
source:
type: array
description: Defines one or more client side libraries that generated the analytics event. The format should be
the library's name followed by '@', and then the version. For example, '[custom.library.js@2.0.0]'.
example:
- '@coveo/headless@2.61.0'
- custom.library.js@2.0.0
items:
minLength: 1
pattern: ^[^@]*@.*$
type: string
description: A context source
example: '@coveo/headless@2.61.0'
capture:
type: boolean
description: Whether the request should be tracked for analytics and machine learning purposes. When set to `true`,
this will trigger a server-side event to be logged. When set to `false`, the server-side event will not be logged.
example: true
labels:
type: object
additionalProperties:
type: string
description: Deprecated - The context labels.
example: '{"category":"garden > garden-tools > chainsaws","brand":"ACME"}'
description: Deprecated - The context labels.
example:
category: garden > garden-tools > chainsaws
brand: ACME
custom:
type: object
additionalProperties:
type: object
description: Custom context values under context.custom. Use this for context mapping.
example:
fitmentProducts:
- sku_123
- sku_456
description: Custom context values under context.custom. Use this for context mapping.
example:
fitmentProducts:
- sku_123
- sku_456
description: Contextual information about the query.
QuerySuggestRequestModel:
required:
- context
- currency
- language
- trackingId
type: object
properties:
query:
type: string
description: The query expression, typically the keywords entered by the end user in a search box.
example: blue shoes
trackingId:
minLength: 1
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
language:
minLength: 1
type: string
description: An ISO 639-1 language code.
example: en
currency:
minLength: 1
type: string
description: An ISO 4217 currency code.
example: USD
clientId:
type: string
description: A GUID which represents the current client.\n\nIf your implementation uses the Atomic or Headless libraries,
then the [client ID](https://docs.coveo.com/en/masb0234/) is generated automatically in client-side code.\n\nIf
you have a custom Coveo implementation, you will have to generate a [UUID v4]()-formatted
GUID. You will need to send this ID in every request that is sent to the Commerce API.\n\nCoveo Machine Learning
models may use this information to provide contextually relevant output.
example: 58bb4b98-1daa-4767-8c15-90a0ea67645c
context:
$ref: '#/components/schemas/ContextModel'
count:
maximum: 1000
minimum: 1
type: integer
description: The number of suggested queries to return.
format: int32
example: 30
debug:
type: boolean
description: Whether to include the execution report on a successful response.
example: true
description: The query suggestion request to be executed.
Completion:
type: object
properties:
expression:
type: string
description: The query suggestion expression.
example: albert camus
highlighted:
type: string
description: The highlighted query suggestion expression.
example: '[albert] {cam}[us]'
description: The list of query suggestions.
QuerySuggestResponseModel:
type: object
properties:
responseId:
type: string
description: The unique identifier of the API response. It can be attached to any subsequent impression or click
event to attribute them to the request.
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
completions:
type: array
description: The list of query suggestions.
items:
$ref: '#/components/schemas/Completion'
SynonymModel_V2ProductView:
required:
- action
- from
type: object
properties:
id:
type: string
description: A UUID identifying the synonym rule.
format: uuid
readOnly: true
example: 58bb4b98-1daa-4767-8c15-90a0ea67645c
action:
type: string
description: 'The synonym rule type. Possible values are: one-way, two-way, and one-way-reverse.'
example: one-way
enum:
- one-way
- two-way
- replace
- exact-match
from:
minItems: 1
type: array
description: The search terms contained in the output query if matched against a synonym rule.
example:
- sandals
- sneakers
items:
type: string
description: The search terms contained in the output query if matched against a synonym rule.
example: '["sandals","sneakers"]'
to:
type: array
description: The search terms contained in the input query.
example:
- shoes
- heels
items:
type: string
description: The search terms contained in the input query.
example: '["shoes","heels"]'
locales:
type: array
description: The list of locales the synonym applies to. When empty, the synonym applies to all locales.
example:
- language: en
country: US
currency: USD
items:
$ref: '#/components/schemas/RuleLocaleModel_V2ProductView'
updatedAt:
type: string
description: The date and time at which the synonym was last updated.
description: The synonym rule to preview.
SynonymPreviewRequestModel_V2ProductView:
required:
- country
- currency
- language
- query
type: object
properties:
language:
minLength: 1
type: string
description: An ISO 639-1 language code.
example: en
country:
minLength: 1
type: string
description: An ISO 3166-1 alpha-2 country code.
example: US
currency:
minLength: 1
type: string
description: An ISO 4217 currency code.
example: USD
page:
maximum: 4
minimum: 0
type: integer
description: The page of products to request.
format: int32
example: 7
perPage:
maximum: 1000
minimum: 1
type: integer
description: The number of products per page. Note that a value greater than 100 may be rejected in the future.
format: int32
example: 30
default: 30
query:
type: string
description: The query expression, typically the keywords entered by the end user in a search box.
example: blue shoes
synonym:
$ref: '#/components/schemas/SynonymModel_V2ProductView'
debug:
type: boolean
description: Whether to include the execution report on a successful response.
example: true
additionalFields:
uniqueItems: true
type: array
description: Some additional fields to include in the preview results.
example:
- cat_color
- cat_gender
items:
type: string
description: Some additional fields to include in the preview results.
example: '["cat_color","cat_gender"]'
CartItemModel_V2ProductView:
type: object
properties:
productId:
type: string
description: The id of the product.
example: shoe-a1-red
quantity:
type: integer
description: The product quantity.
format: int32
example: 2
description: A purchased item.
ProductItemModel_V2ProductView:
type: object
properties:
productId:
type: string
description: The id of the product.
example: shoe-a1-red
description: The product ID used to generate the recommendations.
RecommendationsContextModel_V2ProductView:
required:
- view
type: object
properties:
user:
$ref: '#/components/schemas/UserModel_V2ProductView'
view:
$ref: '#/components/schemas/ViewModel_V2ProductView'
cart:
type: array
description: The cart information.
items:
$ref: '#/components/schemas/CartItemModel_V2ProductView'
source:
type: array
description: Defines one or more client side libraries that generated the analytics event. The format should be
the library's name followed by '@', and then the version. For example, '[custom.library.js@2.0.0]'.
example:
- '@coveo/headless@2.61.0'
- custom.library.js@2.0.0
items:
minLength: 1
pattern: ^[^@]*@.*$
type: string
description: A context source
example: '@coveo/headless@2.61.0'
capture:
type: boolean
description: Whether the request should be tracked for analytics and machine learning purposes. When set to `true`,
this will trigger a server-side event to be logged. When set to `false`, the server-side event will not be logged.
example: true
labels:
type: object
additionalProperties:
type: string
description: Deprecated - The context labels.
example: '{"category":"garden > garden-tools > chainsaws","brand":"ACME"}'
description: Deprecated - The context labels.
example:
category: garden > garden-tools > chainsaws
brand: ACME
custom:
type: object
additionalProperties:
type: object
description: Custom context values under context.custom. Use this for context mapping.
example:
fitmentProducts:
- sku_123
- sku_456
description: Custom context values under context.custom. Use this for context mapping.
example:
fitmentProducts:
- sku_123
- sku_456
product:
$ref: '#/components/schemas/ProductItemModel_V2ProductView'
purchased:
type: array
description: The purchased product IDs and quantity used to generate the recommendations.
items:
$ref: '#/components/schemas/CartItemModel_V2ProductView'
description: Contextual information about the query.
RecommendationsRequestModel_V2ProductView:
required:
- context
- country
- currency
- language
- slotId
- trackingId
type: object
properties:
trackingId:
minLength: 1
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
language:
minLength: 1
type: string
description: An ISO 639-1 language code.
example: en
country:
minLength: 1
type: string
description: An ISO 3166-1 alpha-2 country code.
example: US
currency:
minLength: 1
type: string
description: An ISO 4217 currency code.
example: USD
clientId:
type: string
description: A GUID which represents the current client.\n\nIf your implementation uses the Atomic or Headless libraries,
then the [client ID](https://docs.coveo.com/en/masb0234/) is generated automatically in client-side code.\n\nIf
you have a custom Coveo implementation, you will have to generate a [UUID v4]()-formatted
GUID. You will need to send this ID in every request that is sent to the Commerce API.\n\nCoveo Machine Learning
models may use this information to provide contextually relevant output.
example: 58bb4b98-1daa-4767-8c15-90a0ea67645c
page:
minimum: 0
type: integer
description: The page of products to request.
format: int32
example: 7
perPage:
maximum: 1000
minimum: 1
type: integer
description: The number of products per page. Note that a value greater than 100 may be rejected in the future.
format: int32
example: 30
debug:
type: boolean
description: Whether to include the execution report on a successful response.
example: true
slotId:
type: string
description: The slot identifier
format: uuid
example: 77f997a1-5143-490e-aeff-f219c7718c5f
context:
$ref: '#/components/schemas/RecommendationsContextModel_V2ProductView'
description: The recommendations query to be executed.
UserModel_V2ProductView:
type: object
properties:
userAgent:
type: string
description: 'The user agent of the request. If not present, the user agent is obtained from the [User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent)
header.\n\n**Note**: This information is required when endpoints are behind a proxy.'
example: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36
description: The user information.
ViewModel_V2ProductView:
required:
- url
type: object
properties:
url:
minLength: 1
type: string
description: The URL used to retrieve the products. Used as `documentLocation` for analytics purposes, which indicates
the URL of the resource where the request originated.
example: https://acme.com/summersale
referrer:
type: string
description: Typically the URL of the page that linked to the interface from which the request originates (e.g.,
in JavaScript, this would correspond to the `document.referrer` value).\n\nCoveo Machine Learning models may use
this information to provide contextually relevant output. Used as `documentReferrer` for analytics purposes.
nullable: true
example: https://example.com/
description: 'A collection of data points describing the view. Note: The term ''view'' is used instead of ''page'' to
accommodate usage in contexts such as mobile apps.'
Product_V2ProductView:
type: object
allOf:
- $ref: '#/components/schemas/Result_V2ProductView'
- type: object
properties:
additionalFields:
type: object
additionalProperties:
type: object
description: The product additional fields.
example:
size: M
material: cotton
description: The product additional fields.
example:
size: M
material: cotton
queryPinned:
type: boolean
description: Indicates whether the product was pinned by a reserved position rule.
example: true
badgePlacements:
type: array
description: The list of badge placements associated with this product.
items:
$ref: '#/components/schemas/BadgePlacementViewModel_V2ProductView'
ec_name:
type: string
description: The product name.
example: ACME T-Shirt.
ec_description:
type: string
description: The product description.
example: A very nice T-Shirt. Comes in blue and green colors.
ec_shortdesc:
type: string
description: The product short description.
example: A very nice T-Shirt.
ec_brand:
type: string
description: The product brand.
example: ACME
ec_category:
type: array
description: The product category.
example:
- T-Shirts
items:
type: string
description: The product category.
example: '["T-Shirts"]'
ec_thumbnails:
type: array
description: The product thumbnails.
example:
- https://example.com/thumbnail1.jpg
- https://example.com/thumbnail2.jpg
items:
type: string
description: The product thumbnails.
example: '["https://example.com/thumbnail1.jpg","https://example.com/thumbnail2.jpg"]'
ec_images:
type: array
description: The product images.
example:
- https://example.com/image1.jpg
- https://example.com/image2.jpg
items:
type: string
description: The product images.
example: '["https://example.com/image1.jpg","https://example.com/image2.jpg"]'
ec_price:
type: number
description: The product price.
format: double
example: 19.99
ec_promo_price:
type: number
description: The product promotional price.
format: double
example: 14.99
ec_in_stock:
type: boolean
description: The product availability.
example: true
ec_item_group_id:
type: string
description: The product item group identifier.
example: '0000003035'
ec_rating:
type: number
description: The product rating.
format: double
example: 4.5
ec_product_id:
type: string
description: The product identifier.
example: 0000003035-45
ec_gender:
type: string
description: The intended gender of the product user.
example: M
ec_color:
type: string
description: The product color.
example: Blue
ec_listing:
type: string
description: The product listing.
example: T-Shirt
clickUri:
type: string
description: The product click URI.
example: https://example.com/product/0000003035-45
permanentid:
type: string
description: The product permanent identifier.
example: 0000003035-45
children:
type: array
description: The product child results.
items:
$ref: '#/components/schemas/ChildProduct_V2ProductView'
totalNumberOfChildren:
type: integer
description: The total number of child results.
format: int32
example: 2
RecommendationsResponseModel_V2ProductView:
type: object
properties:
responseId:
type: string
description: The unique identifier of the API response. It can be attached to any subsequent impression or click
event to attribute them to the request.
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
headline:
type: string
description: The recommendations slot headline.
example: Recommended for you
products:
type: array
description: The subset of products returned by the query.
items:
oneOf:
- $ref: '#/components/schemas/Product_V2ProductView'
- $ref: '#/components/schemas/ChildProduct_V2ProductView'
- $ref: '#/components/schemas/ProductForPreview_V2ProductView'
pagination:
$ref: '#/components/schemas/PaginationResponseModel_V2ProductView'
triggers:
type: array
description: The actions for the client to perform based on the Trigger statements defined.
example:
- type: redirect
content: https://www.example.com
items:
$ref: '#/components/schemas/TriggerModel_V2ProductView'
TriggerModel_V2ProductView:
type: object
properties:
type:
type: string
description: The type of trigger.
example: redirect
enum:
- execute
- notify
- redirect
- query
content:
type: string
description: The content of the trigger.
example: https://www.example.com
description: The actions for the client to perform based on the Trigger statements defined.
example:
- type: redirect
content: https://www.example.com
RecommendationsPreviewRequestModel_V2ProductView:
required:
- country
- currency
- language
- strategy
- trackingId
type: object
properties:
slotId:
type: string
description: The slot identifier
format: uuid
example: 77f997a1-5143-490e-aeff-f219c7718c5f
trackingId:
minLength: 1
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
language:
minLength: 1
type: string
description: An ISO 639-1 language code.
example: en
country:
minLength: 1
type: string
description: An ISO 3166-1 alpha-2 country code.
example: US
currency:
minLength: 1
type: string
description: An ISO 4217 currency code.
example: USD
page:
minimum: 0
type: integer
description: The page of products to request.
format: int32
example: 7
perPage:
maximum: 1000
minimum: 1
type: integer
description: The number of products per page. Note that a value greater than 100 may be rejected in the future.
format: int32
example: 30
default: 30
products:
type: array
description: The product IDs used to generate the recommendations.
items:
$ref: '#/components/schemas/ProductItemModel_V2ProductView'
strategy:
type: string
description: The [strategy](https://docs.coveo.com/en/3132/glossary/product-recommendations) to use for recommendations.
example: popular_bought
enum:
- bought_together
- popular_bought
- popular_viewed
- viewed_together
debug:
type: boolean
description: Whether to include the execution report on a successful response.
example: true
minRecs:
maximum: 100
minimum: 1
type: integer
description: Products to be returned.
format: int32
description: The recommendations query to be executed.
AbstractSortRequestResponseModel_V2ProductView:
type: object
properties:
sortCriteria:
type: string
description: The criterion to use for sorting the results.
enum:
- relevance
- fields
description: Determines the order in which to retrieve the results.
example:
- sortCriteria: fields
fields:
- field: ec_price
direction: asc
displayNames:
- value: Price
language: en
- value: Prix
language: fr
discriminator:
propertyName: sortCriteria
default: relevance
ContextModel_V2ProductView:
required:
- view
type: object
properties:
user:
$ref: '#/components/schemas/UserModel_V2ProductView'
view:
$ref: '#/components/schemas/ViewModel_V2ProductView'
cart:
type: array
description: The cart information.
items:
$ref: '#/components/schemas/CartItemModel_V2ProductView'
source:
type: array
description: Defines one or more client side libraries that generated the analytics event. The format should be
the library's name followed by '@', and then the version. For example, '[custom.library.js@2.0.0]'.
example:
- '@coveo/headless@2.61.0'
- custom.library.js@2.0.0
items:
minLength: 1
pattern: ^[^@]*@.*$
type: string
description: A context source
example: '@coveo/headless@2.61.0'
capture:
type: boolean
description: Whether the request should be tracked for analytics and machine learning purposes. When set to `true`,
this will trigger a server-side event to be logged. When set to `false`, the server-side event will not be logged.
example: true
labels:
type: object
additionalProperties:
type: string
description: Deprecated - The context labels.
example: '{"category":"garden > garden-tools > chainsaws","brand":"ACME"}'
description: Deprecated - The context labels.
example:
category: garden > garden-tools > chainsaws
brand: ACME
custom:
type: object
additionalProperties:
type: object
description: Custom context values under context.custom. Use this for context mapping.
example:
fitmentProducts:
- sku_123
- sku_456
description: Custom context values under context.custom. Use this for context mapping.
example:
fitmentProducts:
- sku_123
- sku_456
description: Contextual information about the query.
DateRangeFacetModel_V2ProductView:
required:
- field
- values
type: object
description: Date range facet.
example:
facetId: year
field: year
displayNames:
- value: Year
language: en
- value: Année
language: fr
values:
- state: idle
preventAutoSelect: false
start: 2023/10/01@00:00:00
end: 2023/10/31@23:59:59
endInclusive: true
- state: idle
preventAutoSelect: true
start: 2023/11/01@00:00:00
end: 2023/11/30@23:59:59
endInclusive: false
- state: selected
preventAutoSelect: true
start: 2023/12/01@00:00:00
end: 2023/12/31@23:59:59
endInclusive: true
numberOfValues: 3
preventAutoSelect: false
sortCriteria: score
isFieldExpanded: true
type: dateRange
generateAutomaticRanges: true
allOf:
- $ref: '#/components/schemas/RequestFacetBaseObject_V2ProductView'
- type: object
properties:
values:
minItems: 1
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
$ref: '#/components/schemas/DateRangeValueModel_V2ProductView'
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
sortCriteria:
type: string
description: The criterion to use for sorting returned facet values.
enum:
- score
- alphanumericNatural
- alphanumeric
- occurrences
generateAutomaticRanges:
type: boolean
description: Whether to automatically generate range values for this facet.
freezeCurrentValues:
type: boolean
description: Should always be set to `false` except when selecting/unselecting facet values. See [here](https://docs.coveo.com/en/3199/build-a-search-ui/implement-facets#toggle-facet-values)
for more guidance.
isFieldExpanded:
type: boolean
description: The value provided is only copied back in the `isFieldExpanded` property of the response. It does
not affect the behaviour of the Commerce Service in any way.
DateRangeValueModel_V2ProductView:
required:
- end
- start
type: object
properties:
state:
type: string
description: The current facet value state in the search interface.
enum:
- idle
- selected
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
start:
minLength: 1
type: string
description: The value to start the range at.
end:
minLength: 1
type: string
description: The value to end the range at. Must be greater (or later) than the start value.
endInclusive:
type: boolean
description: Whether to include the end value in the range.
description: The values displayed by the facet in the search interface at the moment of the request.
HierarchicalFacetModel_V2ProductView:
required:
- field
- values
type: object
description: Hierarchical (tree-like) facet.
example:
facetId: ec_category
field: ec_category
displayNames:
- value: Category
language: en
- value: Catégorie
language: fr
values:
- state: selected
preventAutoSelect: true
value: Canoes & Kayaks
children:
- state: selected
preventAutoSelect: true
value: Kayaks
children:
- state: selected
preventAutoSelect: true
value: Folding Kayaks
- state: idle
preventAutoSelect: true
value: Sea Kayaks
- state: selected
preventAutoSelect: false
value: Canoes
numberOfValues: 5
preventAutoSelect: true
sortCriteria: score
isFieldExpanded: true
type: hierarchical
delimitingCharacter: '|'
basePath:
- Boats
filterByBasePath: true
allOf:
- $ref: '#/components/schemas/RequestFacetBaseObject_V2ProductView'
- type: object
properties:
values:
minItems: 1
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
$ref: '#/components/schemas/HierarchicalValueModel_V2ProductView'
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
sortCriteria:
type: string
description: The criterion to use for sorting returned facet values.
enum:
- score
- alphanumericNatural
- alphanumeric
- occurrences
delimitingCharacter:
type: string
description: The character to use to split field values into a hierarchical sequence.
filterByBasePath:
type: boolean
description: Whether to use basePath as a filter for the results.
retrieveCount:
type: object
properties:
empty:
type: boolean
present:
type: boolean
asInt:
type: integer
format: int32
description: The maximum number of children to retrieve for this hierarchical facet values.
isFieldExpanded:
type: boolean
description: The value provided is only copied back in the `isFieldExpanded` property of the response. It does
not affect the behaviour of the Commerce Service in any way.
HierarchicalValueModel_V2ProductView:
required:
- value
type: object
properties:
state:
type: string
description: The current facet value state in the search interface.
enum:
- idle
- selected
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
value:
minLength: 1
type: string
description: This represents a single path segment.
children:
type: array
description: The children of this hierarchical facet value.
items:
$ref: '#/components/schemas/HierarchicalValueModel_V2ProductView'
retrieveCount:
type: integer
description: The maximum number of children to retrieve for this hierarchical facet value. Ignored if retrieveChildren
is false.
format: int32
description: The values displayed by the facet in the search interface at the moment of the request.
LegacyFacetOptions_V2ProductView:
type: object
properties:
freezeFacetOrder:
type: boolean
description: 'Default: `false`
Whether facets should be returned in the same order in which they were requested.'
description: Facet Options for legacy (v1) facets.
ListingRequestModel_V2ProductView:
required:
- context
- country
- currency
- language
- trackingId
type: object
properties:
trackingId:
minLength: 1
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
language:
minLength: 1
type: string
description: An ISO 639-1 language code.
example: en
country:
minLength: 1
type: string
description: An ISO 3166-1 alpha-2 country code.
example: US
currency:
minLength: 1
type: string
description: An ISO 4217 currency code.
example: USD
clientId:
type: string
description: A GUID which represents the current client.\n\nIf your implementation uses the Atomic or Headless libraries,
then the [client ID](https://docs.coveo.com/en/masb0234/) is generated automatically in client-side code.\n\nIf
you have a custom Coveo implementation, you will have to generate a [UUID v4]()-formatted
GUID. You will need to send this ID in every request that is sent to the Commerce API.\n\nCoveo Machine Learning
models may use this information to provide contextually relevant output.
example: 58bb4b98-1daa-4767-8c15-90a0ea67645c
facets:
type: array
description: The facet operations to perform on the query. Note that this parameter is ignored in the '/productSuggest'
endpoint.
example:
- field: ec_category
type: regular
values:
- value: shoes
state: idle
items:
oneOf:
- $ref: '#/components/schemas/DateRangeFacetModel_V2ProductView'
- $ref: '#/components/schemas/HierarchicalFacetModel_V2ProductView'
- $ref: '#/components/schemas/NumericalRangeFacetModel_V2ProductView'
- $ref: '#/components/schemas/RegularFacetModel_V2ProductView'
page:
minimum: 0
type: integer
description: The page of products to request.
format: int32
example: 7
perPage:
maximum: 1000
minimum: 1
type: integer
description: The number of products per page. Note that a value greater than 100 may be rejected in the future.
format: int32
example: 30
sort:
oneOf:
- $ref: '#/components/schemas/SortByFieldsRequestResponseModel_V2ProductView'
- $ref: '#/components/schemas/SortByRelevanceRequestResponseModel_V2ProductView'
debug:
type: boolean
description: Whether to include the execution report on a successful response.
example: true
context:
$ref: '#/components/schemas/ContextModel_V2ProductView'
legacyFacetOptions:
$ref: '#/components/schemas/LegacyFacetOptions_V2ProductView'
enableResults:
type: boolean
description: Enable spotlight content in the results. When enabled, the products list in the response will always
be empty and the results list should be used instead.
description: The listing query to be executed.
NumericalRangeFacetModel_V2ProductView:
required:
- field
- values
type: object
description: Numerical range facet.
example:
facetId: ec_price
field: ec_price
displayNames:
- value: Price
language: en
- value: Prix
language: fr
values:
- state: idle
preventAutoSelect: true
start: '0'
end: '999'
endInclusive: 'true'
- state: selected
preventAutoSelect: true
start: '1000'
end: '2000'
endInclusive: 'false'
- state: selected
preventAutoSelect: true
start: '2001'
end: '3000'
endInclusive: 'false'
numberOfValues: 3
preventAutoSelect: true
sortCriteria: score
isFieldExpanded: true
type: numericalRange
allOf:
- $ref: '#/components/schemas/RequestFacetBaseObject_V2ProductView'
- type: object
properties:
values:
minItems: 1
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
$ref: '#/components/schemas/NumericalRangeValueModel_V2ProductView'
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
sortCriteria:
type: string
description: The criterion to use for sorting returned facet values.
enum:
- score
- alphanumericNatural
- alphanumeric
- occurrences
interval:
type: string
description: Determines the range interval type. Default is `continuous`.
default: continuous
enum:
- continuous
- discrete
- even
- equiprobable
domain:
$ref: '#/components/schemas/RangeDomain_V2ProductView'
freezeCurrentValues:
type: boolean
description: Should always be set to `false` except when selecting/unselecting facet values. See [here](https://docs.coveo.com/en/3199/build-a-search-ui/implement-facets#toggle-facet-values)
for more guidance.
isFieldExpanded:
type: boolean
description: The value provided is only copied back in the `isFieldExpanded` property of the response. It does
not affect the behaviour of the Commerce Service in any way.
NumericalRangeValueModel_V2ProductView:
required:
- end
- start
type: object
properties:
state:
type: string
description: The current facet value state in the search interface.
enum:
- idle
- selected
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
start:
type: number
description: The value to start the range at.
end:
type: number
description: The value to end the range at. Must be greater (or later) than the start value.
endInclusive:
type: boolean
description: Whether to include the end value in the range. It should typically be set to the value last received
in the `endInclusive` property of the facet response.
description: The values displayed by the facet in the search interface at the moment of the request.
RangeDomain_V2ProductView:
required:
- max
- min
type: object
properties:
min:
minimum: 0
type: integer
format: int32
max:
maximum: 1000000
type: integer
format: int32
increment:
maximum: 1000000
minimum: 0
type: integer
format: int32
description: Limits the range values to the specified domain.
RegularFacetModel_V2ProductView:
required:
- field
- values
type: object
description: Regular (single string value) facet.
example:
facetId: ec_brand
field: ec_brand
displayNames:
- value: Brand
language: en
- value: Marque
language: fr
values:
- state: selected
preventAutoSelect: false
value: Aqua Sports
- state: idle
preventAutoSelect: false
value: Aqua Marina
- state: idle
preventAutoSelect: false
value: HO Sports
numberOfValues: 3
preventAutoSelect: false
sortCriteria: score
isFieldExpanded: true
type: regular
customOrder:
- string
allOf:
- $ref: '#/components/schemas/RequestFacetBaseObject_V2ProductView'
- type: object
properties:
values:
minItems: 1
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
$ref: '#/components/schemas/RegularValueModel_V2ProductView'
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
sortCriteria:
type: string
description: The criterion to use for sorting returned facet values.
enum:
- score
- alphanumericNatural
- alphanumeric
- occurrences
customOrder:
type: array
description: A custom sort order for the facet values.
items:
type: string
freezeCurrentValues:
type: boolean
description: Should always be set to `false` except when selecting/unselecting facet values. See [here](https://docs.coveo.com/en/3199/build-a-search-ui/implement-facets#toggle-facet-values)
for more guidance.
resultsMustMatch:
type: string
description: Specifies how a result must match the selected values.
default: atLeastOneValue
enum:
- atLeastOneValue
- allValues
isFieldExpanded:
type: boolean
description: The value provided is only copied back in the `isFieldExpanded` property of the response. It does
not affect the behaviour of the Commerce Service in any way.
RegularValueModel_V2ProductView:
required:
- value
type: object
properties:
state:
type: string
description: The current facet value state in the search interface.
enum:
- idle
- selected
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
value:
minLength: 1
type: string
description: The facet value name.
description: The values displayed by the facet in the search interface at the moment of the request.
RequestFacetBaseObject_V2ProductView:
required:
- field
- values
type: object
properties:
facetId:
type: string
description: Name of the field to execute the facet search request against.
example: color
field:
minLength: 1
type: string
description: The facet field name.
example: ec_brand
displayName:
type: string
description: The facet display name.
example: Brand
values:
minItems: 1
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
type: object
description: The values displayed by the facet in the search interface at the moment of the request.
numberOfValues:
type: object
properties:
empty:
type: boolean
present:
type: boolean
asInt:
type: integer
format: int32
description: 'The maximum number of facet values to fetch. It should typically be set to the value last received
in the `numberOfValues` property of the facet response.
An exception to this guideline is the case where the last response had
`moreValuesAvailable=true` and the user asks to see more values for this facet. In this case,
the front-end is expected to send a value greater than the `numberOfValues` that it last received
in the response. This ensures that more values are fetched from the index.
When not provided, the default number of values configured for this facet is used.
'
type:
type: string
description: 'One of: `regular`, `dateRange`, `numericalRange`, `hierarchical`. For more information, see the [facet
types](https://docs.coveo.com/en/p3oa0420#facet-types) documentation.'
enum:
- regular
- dateRange
- numericalRange
- hierarchical
- regular
description: The facet operations to perform on the query. Note that this parameter is ignored in the '/productSuggest'
endpoint.
example:
- field: ec_category
type: regular
values:
- value: shoes
state: idle
discriminator:
propertyName: type
SortByFieldRequestResponseModel_V2ProductView:
required:
- field
type: object
properties:
field:
minLength: 1
type: string
description: The name of a field to sort by.
direction:
type: string
description: 'Sort order:
Default: `ascending`
- `asc` - Ascending, from A to Z
- `desc` - Descending,
from Z to A
'
enum:
- asc
- desc
displayName:
type: string
description: The display name of a field.
description: Defines the fields and, optionally, their sort order.
SortByFieldsRequestResponseModel_V2ProductView:
required:
- fields
type: object
allOf:
- $ref: '#/components/schemas/AbstractSortRequestResponseModel_V2ProductView'
- type: object
properties:
fields:
minItems: 1
type: array
description: Defines the fields and, optionally, their sort order.
items:
$ref: '#/components/schemas/SortByFieldRequestResponseModel_V2ProductView'
SortByRelevanceRequestResponseModel_V2ProductView:
type: object
allOf:
- $ref: '#/components/schemas/AbstractSortRequestResponseModel_V2ProductView'
AbstractFacetResultObject_V2ProductView:
required:
- type
type: object
properties:
facetId:
type: string
field:
type: string
displayName:
type: string
values:
type: array
items:
type: object
numberOfValues:
type: integer
description: 'The number of values that were requested to the index for this facet. When the facet
is part of the request and the `numberOfValues` request parameter is not null, the returned value
will be equal to the value found in the request. Otherwise, the returned value will be equal to
the default number of values configured for this facet.
Note: This value can be greater than the number of values returned in the `values` array.
'
format: int32
type:
type: string
description: The available facets. Note that this array will always be empty in the '/productSuggest' endpoint.
discriminator:
propertyName: type
DateRangeFacetResultValue_V2ProductView:
type: object
properties:
state:
type: string
enum:
- idle
- selected
numberOfResults:
type: integer
format: int64
isAutoSelected:
type: boolean
isSuggested:
type: boolean
moreValuesAvailable:
type: boolean
start:
type: string
end:
type: string
endInclusive:
type: boolean
DateRangeFacetResult_V2ProductView:
type: object
allOf:
- $ref: '#/components/schemas/AbstractFacetResultObject_V2ProductView'
- type: object
properties:
values:
type: array
items:
$ref: '#/components/schemas/DateRangeFacetResultValue_V2ProductView'
moreValuesAvailable:
type: boolean
fromAutoSelect:
type: boolean
isFieldExpanded:
type: boolean
description: 'The value received in the `isFieldExpanded` property of the request. If the facet was
not part of the request, `false` is returned.
'
HierarchicalFacetResultValue_V2ProductView:
type: object
properties:
state:
type: string
enum:
- idle
- selected
numberOfResults:
type: integer
format: int64
isAutoSelected:
type: boolean
isSuggested:
type: boolean
moreValuesAvailable:
type: boolean
description: Whether additional facet values matching the request are available.
value:
type: string
description: This represents a single path segment.
path:
type: array
items:
type: string
isLeafValue:
type: boolean
children:
type: array
description: The children of this hierarchical facet value.
items:
$ref: '#/components/schemas/HierarchicalFacetResultValue_V2ProductView'
HierarchicalFacetResult_V2ProductView:
type: object
allOf:
- $ref: '#/components/schemas/AbstractFacetResultObject_V2ProductView'
- type: object
properties:
values:
type: array
items:
$ref: '#/components/schemas/HierarchicalFacetResultValue_V2ProductView'
delimitingCharacter:
type: string
moreValuesAvailable:
type: boolean
fromAutoSelect:
type: boolean
isFieldExpanded:
type: boolean
description: 'The value received in the `isFieldExpanded` property of the request. If the facet was
not part of the request, `false` is returned.
'
ListingResponseModel_V2ProductView:
type: object
properties:
responseId:
type: string
description: The unique identifier of the API response. It can be attached to any subsequent impression or click
event to attribute them to the request.
format: uuid
example: 123e4567-e89b-12d3-a456-426614174000
products:
type: array
description: The subset of products returned by the query.
items:
oneOf:
- $ref: '#/components/schemas/Product_V2ProductView'
- $ref: '#/components/schemas/ChildProduct_V2ProductView'
- $ref: '#/components/schemas/ProductForPreview_V2ProductView'
results:
type: array
description: List of results including products and spotlight content
items:
oneOf:
- $ref: '#/components/schemas/ChildProduct_V2ProductView'
- $ref: '#/components/schemas/ProductForPreview_V2ProductView'
- $ref: '#/components/schemas/Product_V2ProductView'
- $ref: '#/components/schemas/SpotlightContentModel_V2ProductView'
facets:
type: array
description: The available facets. Note that this array will always be empty in the '/productSuggest' endpoint.
items:
oneOf:
- $ref: '#/components/schemas/DateRangeFacetResult_V2ProductView'
- $ref: '#/components/schemas/HierarchicalFacetResult_V2ProductView'
- $ref: '#/components/schemas/NumericalRangeFacetResult_V2ProductView'
- $ref: '#/components/schemas/RegularFacetResult_V2ProductView'
pagination:
$ref: '#/components/schemas/PaginationResponseModel_V2ProductView'
sort:
$ref: '#/components/schemas/SortResponseModel_V2ProductView'
triggers:
type: array
description: The actions for the client to perform based on the Trigger statements defined.
example:
- type: redirect
content: https://www.example.com
items:
$ref: '#/components/schemas/TriggerModel_V2ProductView'
NumericalRangeFacetResultValue_V2ProductView:
type: object
properties:
state:
type: string
enum:
- idle
- selected
numberOfResults:
type: integer
format: int64
isAutoSelected:
type: boolean
isSuggested:
type: boolean
moreValuesAvailable:
type: boolean
start:
type: number
end:
type: number
endInclusive:
type: boolean
NumericalRangeFacetResult_V2ProductView:
type: object
allOf:
- $ref: '#/components/schemas/AbstractFacetResultObject_V2ProductView'
- type: object
properties:
values:
type: array
items:
$ref: '#/components/schemas/NumericalRangeFacetResultValue_V2ProductView'
moreValuesAvailable:
type: boolean
fromAutoSelect:
type: boolean
domain:
$ref: '#/components/schemas/RangeDomain_V2ProductView'
interval:
type: string
enum:
- continuous
- discrete
- even
- equiprobable
isFieldExpanded:
type: boolean
description: 'The value received in the `isFieldExpanded` property of the request. If the facet was
not part of the request, `false` is returned.
'
RegularFacetResultValue_V2ProductView:
type: object
properties:
state:
type: string
enum:
- idle
- selected
numberOfResults:
type: integer
format: int64
isAutoSelected:
type: boolean
isSuggested:
type: boolean
moreValuesAvailable:
type: boolean
value:
type: string
RegularFacetResult_V2ProductView:
type: object
allOf:
- $ref: '#/components/schemas/AbstractFacetResultObject_V2ProductView'
- type: object
properties:
values:
type: array
items:
$ref: '#/components/schemas/RegularFacetResultValue_V2ProductView'
moreValuesAvailable:
type: boolean
fromAutoSelect:
type: boolean
isFieldExpanded:
type: boolean
description: 'The value received in the `isFieldExpanded` property of the request. If the facet was
not part of the request, `false` is returned.
'
Result_V2ProductView:
required:
- resultType
type: object
properties:
resultType:
type: string
description: List of results including products and spotlight content
discriminator:
propertyName: resultType
SortResponseModel_V2ProductView:
type: object
properties:
appliedSort:
oneOf:
- $ref: '#/components/schemas/SortByFieldsRequestResponseModel_V2ProductView'
- $ref: '#/components/schemas/SortByRelevanceRequestResponseModel_V2ProductView'
availableSorts:
type: array
description: The list of available sorting methods.
example:
- sortCriteria: relevance
- sortCriteria: fields
fields:
- field: ec_price
direction: desc
displayName: Price
items:
oneOf:
- $ref: '#/components/schemas/SortByFieldsRequestResponseModel_V2ProductView'
- $ref: '#/components/schemas/SortByRelevanceRequestResponseModel_V2ProductView'
description: The applied and available sort options for the query.
example:
appliedSort:
sortCriteria: fields
fields:
- field: ec_brand
direction: asc
displayName: Brand
availableSorts:
- sortCriteria: relevance
- sortCriteria: fields
fields:
- field: ec_price
direction: desc
displayName: Price
SpotlightContentModel_V2ProductView:
required:
- clickUri
- desktopImage
type: object
description: Spotlight Content
allOf:
- $ref: '#/components/schemas/Result_V2ProductView'
- type: object
properties:
id:
type: string
description: The unique identifier of the spotlight content
format: uuid
readOnly: true
example: 123e4567-e89b-12d3-a456-426614174000
name:
maxLength: 255
minLength: 1
type: string
description: The name of the spotlight content
example: Summer Sale
description:
maxLength: 255
minLength: 1
type: string
description: The description of the spotlight content
example: Get up to 50% off on summer items
clickUri:
maxLength: 1024
minLength: 1
type: string
description: The click URI for the spotlight content
example: https://example.com/summer-sale
desktopImage:
maxLength: 1024
minLength: 1
type: string
description: The desktop image URL for the spotlight content
example: https://example.com/images/summer-sale-desktop.jpg
mobileImage:
maxLength: 1024
minLength: 1
type: string
description: The mobile image URL for the spotlight content
example: https://example.com/images/summer-sale-mobile.jpg
nameFontColor:
type: string
description: The font color for the name text in the format `#RRGGBB`.
example: '#000000'
descriptionFontColor:
type: string
description: The font color for the description text in the format `#RRGGBB`.
example: '#000000'
altText:
maxLength: 255
minLength: 1
type: string
description: The alt text for the spotlight content image for accessibility
example: Summer sale promotional banner
AbstractSortRequestResponseModel:
type: object
properties:
sortCriteria:
type: string
description: The criterion to use for sorting the results.
enum:
- relevance
- fields
description: Determines the order in which to retrieve the results.
example:
- sortCriteria: fields
fields:
- field: ec_price
direction: asc
displayNames:
- value: Price
language: en
- value: Prix
language: fr
discriminator:
propertyName: sortCriteria
default: relevance
DateRangeFacetModel:
required:
- field
- values
type: object
description: Date range facet.
example:
facetId: year
field: year
displayNames:
- value: Year
language: en
- value: Année
language: fr
values:
- state: idle
preventAutoSelect: false
start: 2023/10/01@00:00:00
end: 2023/10/31@23:59:59
endInclusive: true
- state: idle
preventAutoSelect: true
start: 2023/11/01@00:00:00
end: 2023/11/30@23:59:59
endInclusive: false
- state: selected
preventAutoSelect: true
start: 2023/12/01@00:00:00
end: 2023/12/31@23:59:59
endInclusive: true
numberOfValues: 3
preventAutoSelect: false
sortCriteria: score
isFieldExpanded: true
type: dateRange
generateAutomaticRanges: true
allOf:
- $ref: '#/components/schemas/RequestFacetBaseObject'
- type: object
properties:
values:
minItems: 1
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
$ref: '#/components/schemas/DateRangeValueModel'
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
sortCriteria:
type: string
description: The criterion to use for sorting returned facet values.
enum:
- score
- alphanumericNatural
- alphanumeric
- occurrences
generateAutomaticRanges:
type: boolean
description: Whether to automatically generate range values for this facet.
freezeCurrentValues:
type: boolean
description: Should always be set to `false` except when selecting/unselecting facet values. See [here](https://docs.coveo.com/en/3199/build-a-search-ui/implement-facets#toggle-facet-values)
for more guidance.
isFieldExpanded:
type: boolean
description: The value provided is only copied back in the `isFieldExpanded` property of the response. It does
not affect the behaviour of the Commerce Service in any way.
DateRangeValueModel:
required:
- end
- start
type: object
properties:
state:
type: string
description: The current facet value state in the search interface.
enum:
- idle
- selected
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
start:
minLength: 1
type: string
description: The value to start the range at.
end:
minLength: 1
type: string
description: The value to end the range at. Must be greater (or later) than the start value.
endInclusive:
type: boolean
description: Whether to include the end value in the range.
description: The values displayed by the facet in the search interface at the moment of the request.
FacetSearchRequestModel:
required:
- context
- country
- currency
- language
- query
- trackingId
type: object
properties:
facetId:
type: string
description: Name of the field to execute the facet search request against.
example: color
facetQuery:
type: string
description: Should be set to the text entered by the end-user in the facet search box, to which one or more wildcard
characters (*) may be added.
example: blue
numberOfValues:
type: integer
description: The maximum number of facet values to fetch when performing facet search
format: int32
example: 10
ignorePaths:
type: array
description: Paths to ignore when searching for hierarchical values.
example:
- Accessories
items:
type: string
description: Paths to ignore when searching for hierarchical values.
example: '["Accessories"]'
trackingId:
minLength: 1
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
language:
minLength: 1
type: string
description: An ISO 639-1 language code.
example: en
country:
minLength: 1
type: string
description: An ISO 3166-1 alpha-2 country code.
example: US
currency:
minLength: 1
type: string
description: An ISO 4217 currency code.
example: USD
clientId:
type: string
description: A GUID which represents the current client.\n\nIf your implementation uses the Atomic or Headless libraries,
then the [client ID](https://docs.coveo.com/en/masb0234/) is generated automatically in client-side code.\n\nIf
you have a custom Coveo implementation, you will have to generate a [UUID v4]()-formatted
GUID. You will need to send this ID in every request that is sent to the Commerce API.\n\nCoveo Machine Learning
models may use this information to provide contextually relevant output.
example: 58bb4b98-1daa-4767-8c15-90a0ea67645c
facets:
type: array
description: The facet operations to perform on the query. Note that this parameter is ignored in the '/productSuggest'
endpoint.
example:
- field: ec_category
type: regular
values:
- value: shoes
state: idle
items:
oneOf:
- $ref: '#/components/schemas/DateRangeFacetModel'
- $ref: '#/components/schemas/HierarchicalFacetModel'
- $ref: '#/components/schemas/NumericalRangeFacetModel'
- $ref: '#/components/schemas/RegularFacetModel'
page:
minimum: 0
type: integer
description: The page of products to request.
format: int32
example: 7
perPage:
maximum: 1000
minimum: 1
type: integer
description: The number of products per page. Note that a value greater than 100 may be rejected in the future.
format: int32
example: 30
sort:
oneOf:
- $ref: '#/components/schemas/SortByFieldsRequestResponseModel'
- $ref: '#/components/schemas/SortByRelevanceRequestResponseModel'
debug:
type: boolean
description: Whether to include the execution report on a successful response.
example: true
query:
type: string
description: The query expression, typically the keywords entered by the end user in a search box.
example: blue shoes
context:
$ref: '#/components/schemas/ContextModel'
legacyFacetOptions:
$ref: '#/components/schemas/LegacyFacetOptions'
enableResults:
type: boolean
description: Enable spotlight content in the results. When enabled, the products list in the response will always
be empty and the results list should be used instead.
description: The facet query to be executed.
HierarchicalFacetModel:
required:
- field
- values
type: object
description: Hierarchical (tree-like) facet.
example:
facetId: ec_category
field: ec_category
displayNames:
- value: Category
language: en
- value: Catégorie
language: fr
values:
- state: selected
preventAutoSelect: true
value: Canoes & Kayaks
children:
- state: selected
preventAutoSelect: true
value: Kayaks
children:
- state: selected
preventAutoSelect: true
value: Folding Kayaks
- state: idle
preventAutoSelect: true
value: Sea Kayaks
- state: selected
preventAutoSelect: false
value: Canoes
numberOfValues: 5
preventAutoSelect: true
sortCriteria: score
isFieldExpanded: true
type: hierarchical
delimitingCharacter: '|'
basePath:
- Boats
filterByBasePath: true
allOf:
- $ref: '#/components/schemas/RequestFacetBaseObject'
- type: object
properties:
values:
minItems: 1
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
$ref: '#/components/schemas/HierarchicalValueModel'
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
sortCriteria:
type: string
description: The criterion to use for sorting returned facet values.
enum:
- score
- alphanumericNatural
- alphanumeric
- occurrences
delimitingCharacter:
type: string
description: The character to use to split field values into a hierarchical sequence.
filterByBasePath:
type: boolean
description: Whether to use basePath as a filter for the results.
retrieveCount:
type: object
properties:
empty:
type: boolean
present:
type: boolean
asInt:
type: integer
format: int32
description: The maximum number of children to retrieve for this hierarchical facet values.
isFieldExpanded:
type: boolean
description: The value provided is only copied back in the `isFieldExpanded` property of the response. It does
not affect the behaviour of the Commerce Service in any way.
HierarchicalValueModel:
required:
- value
type: object
properties:
state:
type: string
description: The current facet value state in the search interface.
enum:
- idle
- selected
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
value:
minLength: 1
type: string
description: This represents a single path segment.
children:
type: array
description: The children of this hierarchical facet value.
items:
$ref: '#/components/schemas/HierarchicalValueModel'
retrieveCount:
type: integer
description: The maximum number of children to retrieve for this hierarchical facet value. Ignored if retrieveChildren
is false.
format: int32
description: The values displayed by the facet in the search interface at the moment of the request.
LegacyFacetOptions:
type: object
properties:
freezeFacetOrder:
type: boolean
description: 'Default: `false`
Whether facets should be returned in the same order in which they were requested.'
description: Facet Options for legacy (v1) facets.
NumericalRangeFacetModel:
required:
- field
- values
type: object
description: Numerical range facet.
example:
facetId: ec_price
field: ec_price
displayNames:
- value: Price
language: en
- value: Prix
language: fr
values:
- state: idle
preventAutoSelect: true
start: '0'
end: '999'
endInclusive: 'true'
- state: selected
preventAutoSelect: true
start: '1000'
end: '2000'
endInclusive: 'false'
- state: selected
preventAutoSelect: true
start: '2001'
end: '3000'
endInclusive: 'false'
numberOfValues: 3
preventAutoSelect: true
sortCriteria: score
isFieldExpanded: true
type: numericalRange
allOf:
- $ref: '#/components/schemas/RequestFacetBaseObject'
- type: object
properties:
values:
minItems: 1
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
$ref: '#/components/schemas/NumericalRangeValueModel'
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
sortCriteria:
type: string
description: The criterion to use for sorting returned facet values.
enum:
- score
- alphanumericNatural
- alphanumeric
- occurrences
interval:
type: string
description: Determines the range interval type. Default is `continuous`.
default: continuous
enum:
- continuous
- discrete
- even
- equiprobable
domain:
$ref: '#/components/schemas/RangeDomain'
freezeCurrentValues:
type: boolean
description: Should always be set to `false` except when selecting/unselecting facet values. See [here](https://docs.coveo.com/en/3199/build-a-search-ui/implement-facets#toggle-facet-values)
for more guidance.
isFieldExpanded:
type: boolean
description: The value provided is only copied back in the `isFieldExpanded` property of the response. It does
not affect the behaviour of the Commerce Service in any way.
NumericalRangeValueModel:
required:
- end
- start
type: object
properties:
state:
type: string
description: The current facet value state in the search interface.
enum:
- idle
- selected
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
start:
type: number
description: The value to start the range at.
end:
type: number
description: The value to end the range at. Must be greater (or later) than the start value.
endInclusive:
type: boolean
description: Whether to include the end value in the range. It should typically be set to the value last received
in the `endInclusive` property of the facet response.
description: The values displayed by the facet in the search interface at the moment of the request.
RegularFacetModel:
required:
- field
- values
type: object
description: Regular (single string value) facet.
example:
facetId: ec_brand
field: ec_brand
displayNames:
- value: Brand
language: en
- value: Marque
language: fr
values:
- state: selected
preventAutoSelect: false
value: Aqua Sports
- state: idle
preventAutoSelect: false
value: Aqua Marina
- state: idle
preventAutoSelect: false
value: HO Sports
numberOfValues: 3
preventAutoSelect: false
sortCriteria: score
isFieldExpanded: true
type: regular
customOrder:
- string
allOf:
- $ref: '#/components/schemas/RequestFacetBaseObject'
- type: object
properties:
values:
minItems: 1
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
$ref: '#/components/schemas/RegularValueModel'
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
sortCriteria:
type: string
description: The criterion to use for sorting returned facet values.
enum:
- score
- alphanumericNatural
- alphanumeric
- occurrences
customOrder:
type: array
description: A custom sort order for the facet values.
items:
type: string
freezeCurrentValues:
type: boolean
description: Should always be set to `false` except when selecting/unselecting facet values. See [here](https://docs.coveo.com/en/3199/build-a-search-ui/implement-facets#toggle-facet-values)
for more guidance.
resultsMustMatch:
type: string
description: Specifies how a result must match the selected values.
default: atLeastOneValue
enum:
- atLeastOneValue
- allValues
isFieldExpanded:
type: boolean
description: The value provided is only copied back in the `isFieldExpanded` property of the response. It does
not affect the behaviour of the Commerce Service in any way.
RegularValueModel:
required:
- value
type: object
properties:
state:
type: string
description: The current facet value state in the search interface.
enum:
- idle
- selected
preventAutoSelect:
type: boolean
description: Whether to prevent Coveo ML from automatically selecting facet values.
value:
minLength: 1
type: string
description: The facet value name.
description: The values displayed by the facet in the search interface at the moment of the request.
RequestFacetBaseObject:
required:
- field
- values
type: object
properties:
facetId:
type: string
description: Name of the field to execute the facet search request against.
example: color
field:
minLength: 1
type: string
description: The facet field name.
example: ec_brand
displayName:
type: string
description: The facet display name.
example: Brand
values:
minItems: 1
type: array
description: The values displayed by the facet in the search interface at the moment of the request.
items:
type: object
description: The values displayed by the facet in the search interface at the moment of the request.
numberOfValues:
type: object
properties:
empty:
type: boolean
present:
type: boolean
asInt:
type: integer
format: int32
description: 'The maximum number of facet values to fetch. It should typically be set to the value last received
in the `numberOfValues` property of the facet response.
An exception to this guideline is the case where the last response had
`moreValuesAvailable=true` and the user asks to see more values for this facet. In this case,
the front-end is expected to send a value greater than the `numberOfValues` that it last received
in the response. This ensures that more values are fetched from the index.
When not provided, the default number of values configured for this facet is used.
'
type:
type: string
description: 'One of: `regular`, `dateRange`, `numericalRange`, `hierarchical`. For more information, see the [facet
types](https://docs.coveo.com/en/p3oa0420#facet-types) documentation.'
enum:
- regular
- dateRange
- numericalRange
- hierarchical
- regular
description: The facet operations to perform on the query. Note that this parameter is ignored in the '/productSuggest'
endpoint.
example:
- field: ec_category
type: regular
values:
- value: shoes
state: idle
discriminator:
propertyName: type
SortByFieldRequestResponseModel:
required:
- field
type: object
properties:
field:
minLength: 1
type: string
description: The name of a field to sort by.
direction:
type: string
description: 'Sort order:
Default: `ascending`
- `asc` - Ascending, from A to Z
- `desc` - Descending,
from Z to A
'
enum:
- asc
- desc
displayName:
type: string
description: The display name of a field.
description: Defines the fields and, optionally, their sort order.
SortByFieldsRequestResponseModel:
required:
- fields
type: object
allOf:
- $ref: '#/components/schemas/AbstractSortRequestResponseModel'
- type: object
properties:
fields:
minItems: 1
type: array
description: Defines the fields and, optionally, their sort order.
items:
$ref: '#/components/schemas/SortByFieldRequestResponseModel'
SortByRelevanceRequestResponseModel:
type: object
allOf:
- $ref: '#/components/schemas/AbstractSortRequestResponseModel'
FacetSearchResponseModel:
type: object
properties:
values:
type: array
description: The returned facet values.
items:
$ref: '#/components/schemas/FacetValuesModel'
moreValuesAvailable:
type: boolean
description: Whether additional facet values matching the request are available.
FacetValuesModel:
type: object
properties:
displayValue:
type: string
description: Custom display name.
rawValue:
type: string
description: Facet value.
path:
type: array
description: Base path of the facet value.
items:
type: string
description: Base path of the facet value.
count:
type: integer
description: Estimated number of products matching the query.
format: int32
description: The returned facet values.
PaginatedResponseFacetFieldModel:
type: object
properties:
pagination:
$ref: '#/components/schemas/Pagination'
items:
type: array
items:
oneOf:
- $ref: '#/components/schemas/ContinuousFacetFieldModel'
- $ref: '#/components/schemas/HierarchicalFacetFieldModel'
- $ref: '#/components/schemas/NumericalRangesFacetFieldModel'
- $ref: '#/components/schemas/RegularFacetFieldModel'
Pagination:
type: object
properties:
page:
type: integer
format: int32
perPage:
type: integer
format: int32
totalItems:
type: integer
format: int32
totalPages:
type: integer
format: int32
CommercePageModelSynonymModel:
required:
- items
- totalEntries
- totalPages
type: object
properties:
items:
type: array
description: The retrieved page of items.
items:
$ref: '#/components/schemas/SynonymModel'
totalEntries:
type: integer
description: The total number of results that match the query.
format: int64
totalPages:
type: integer
description: The total number of pages of items available.
format: int32
description: Page
CommercePageModelSlotConfigurationModel:
required:
- items
- totalEntries
- totalPages
type: object
properties:
items:
type: array
description: The retrieved page of items.
items:
$ref: '#/components/schemas/SlotConfigurationModel'
totalEntries:
type: integer
description: The total number of results that match the query.
format: int64
totalPages:
type: integer
description: The total number of pages of items available.
format: int32
description: Page
SlotStrategiesModel:
type: object
properties:
seedType:
type: string
description: The seed type for the slot.
enum:
- unseeded
- product
- cart
- purchased
strategies:
type: array
description: The strategies for the slot.
items:
$ref: '#/components/schemas/StrategiesModel'
StrategiesModel:
type: object
properties:
strategy:
type: string
description: The [strategy](https://docs.coveo.com/en/3132/glossary/product-recommendations) to use for recommendations.
example: popular_bought
enum:
- bought_together
- popular_bought
- popular_viewed
- viewed_together
seed:
type: string
description: 'The seed number for the [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/). One
of: unseeded, single, multi.'
example: unseeded
enum:
- unseeded
- single
- multi
description: The strategies for the slot.
CommercePageModelSlotConfigurationNameModel:
required:
- items
- totalEntries
- totalPages
type: object
properties:
items:
type: array
description: The retrieved page of items.
items:
$ref: '#/components/schemas/SlotConfigurationNameModel'
totalEntries:
type: integer
description: The total number of results that match the query.
format: int64
totalPages:
type: integer
description: The total number of pages of items available.
format: int32
description: Page
SlotConfigurationNameModel:
required:
- name
type: object
properties:
id:
type: string
description: The unique identifier of the configuration (search or listing) this rule belongs to.
format: uuid
readOnly: true
example: 644e1dd7-2a7f-18fb-b8ed-ed78c3f92c2b
name:
maxLength: 255
minLength: 1
type: string
description: A unique name for the [slot configuration](https://docs.coveo.com/en/o9b80563/glossary/recommendation-slot/).
example: Homepage Primary.
description: The retrieved page of items.
CommercePageModelPublicListingPageResponseModel:
required:
- items
- totalEntries
- totalPages
type: object
properties:
items:
type: array
description: The retrieved page of items.
items:
$ref: '#/components/schemas/PublicListingPageResponseModel'
totalEntries:
type: integer
description: The total number of results that match the query.
format: int64
totalPages:
type: integer
description: The total number of pages of items available.
format: int32
description: Page
CommercePageModelListingConfigurationModel:
required:
- items
- totalEntries
- totalPages
type: object
properties:
items:
type: array
description: The retrieved page of items.
items:
$ref: '#/components/schemas/ListingConfigurationModel'
totalEntries:
type: integer
description: The total number of results that match the query.
format: int64
totalPages:
type: integer
description: The total number of pages of items available.
format: int32
description: Page
FilterRuleItem:
required:
- action
type: object
allOf:
- $ref: '#/components/schemas/RuleItemModel'
- type: object
properties:
filters:
type: array
description: A list of filters.
example:
- fieldName: price
operator: isExactly
value:
type: decimal
value: 99.99
- fieldName: item_count
operator: isBetween
value:
type: range
range:
from: 1000
to: 3000
items:
$ref: '#/components/schemas/QueryFilterModel'
action:
type: string
description: Whether the rule is an include or an exclude.
example: include
enum:
- include
- exclude
name:
type: string
description: The name of the rule.
example: 'Pin #1 Short Open-Front Sweater for Women/Boost blue surfboards/Hide green t-shirts'
id:
type: string
format: uuid
readOnly: true
essential:
type: boolean
description: Indicates if the rule is essential to the listing page; the essential rule is added during page creation.
updatedBy:
type: string
description: The user who last updated the rule.
readOnly: true
example: user@coveo.com
updatedAt:
type: string
description: The date and time at which the rule was last updated.
format: date-time
readOnly: true
locales:
type: array
description: The list of locales the rule applies to. When empty, the rule applies to all locales.
example:
- language: en
country: US
currency: USD
items:
$ref: '#/components/schemas/RuleLocaleModel'
PaginatedRuleItems:
required:
- items
- totalEntries
- totalPages
type: object
properties:
items:
type: array
description: The retrieved page of items.
items:
oneOf:
- $ref: '#/components/schemas/FilterRuleItem'
- $ref: '#/components/schemas/PinRuleItem'
- $ref: '#/components/schemas/RankingRuleItem'
totalEntries:
type: integer
description: The total number of results that match the query.
format: int64
totalPages:
type: integer
description: The total number of pages of items available.
format: int32
PinRuleItem:
type: object
allOf:
- $ref: '#/components/schemas/RuleItemModel'
- type: object
properties:
rankByPermanentId:
type: array
description: A map of product permanent IDs to their desired rank.
example:
'123456789': 1
'987654321': 2
items:
type: object
additionalProperties:
type: integer
format: int32
action:
type: string
description: Whether the rule is a pin.
example: pin
enum:
- pin
name:
type: string
description: The name of the rule.
example: 'Pin #1 Short Open-Front Sweater for Women/Boost blue surfboards/Hide green t-shirts'
id:
type: string
format: uuid
readOnly: true
essential:
type: boolean
description: Indicates if the rule is essential to the listing page; the essential rule is added during page creation.
updatedBy:
type: string
description: The user who last updated the rule.
readOnly: true
example: user@coveo.com
updatedAt:
type: string
description: The date and time at which the rule was last updated.
format: date-time
readOnly: true
locales:
type: array
description: The list of locales the rule applies to. When empty, the rule applies to all locales.
example:
- language: en
country: US
currency: USD
items:
$ref: '#/components/schemas/RuleLocaleModel'
RankingRuleItem:
required:
- action
type: object
allOf:
- $ref: '#/components/schemas/RuleItemModel'
- type: object
properties:
filters:
type: array
description: A list of filters.
example:
- fieldName: price
operator: isExactly
value:
type: decimal
value: 99.99
- fieldName: item_count
operator: isBetween
value:
type: range
range:
from: 1000
to: 3000
items:
$ref: '#/components/schemas/QueryFilterModel'
value:
maximum: 1000
minimum: 0
type: integer
description: The scale at which the rule should be applied.
format: int32
example: 250
action:
type: string
description: Whether the rule is a boost or a bury.
example: boost
enum:
- boost
- bury
name:
type: string
description: The name of the rule.
example: 'Pin #1 Short Open-Front Sweater for Women/Boost blue surfboards/Hide green t-shirts'
id:
type: string
format: uuid
readOnly: true
essential:
type: boolean
description: Indicates if the rule is essential to the listing page; the essential rule is added during page creation.
updatedBy:
type: string
description: The user who last updated the rule.
readOnly: true
example: user@coveo.com
updatedAt:
type: string
description: The date and time at which the rule was last updated.
format: date-time
readOnly: true
locales:
type: array
description: The list of locales the rule applies to. When empty, the rule applies to all locales.
example:
- language: en
country: US
currency: USD
items:
$ref: '#/components/schemas/RuleLocaleModel'
RuleItemModel:
type: object
properties:
trackingId:
type: string
description: The unique identifier of the tracking target.
example: acmecorporation_ca
configurationId:
type: string
description: The unique identifier of the configuration (search or listing) this rule belongs to.
format: uuid
example: 644e1dd7-2a7f-18fb-b8ed-ed78c3f92c2b
scope:
type: string
description: 'Rule scope to return. One of: [specific, global]. Returns all if not specified.'
example: specific
enum:
- global
- specific
conditions:
type: array
description: Conditions under which the rule is applied.
example:
- operator: isExactly
values:
- mens shoes
items:
$ref: '#/components/schemas/SearchConditionModel'
configurationName:
type: string
description: Name of the configuration this rule is applied to.
example: Surf With Us This Year
configurationType:
type: string
description: Type of configuration this rule is applied to.
example: listing
enum:
- listing
- search
scheduleStartDate:
type: string
description: The start date of the Schedule.
format: date-time
scheduleEndDate:
type: string
description: The end date of the Schedule.
format: date-time
type:
type: string
description: Type of the rule returned.
example: '[filter, pin, ranking]'
enum:
- filter
- pin
- ranking
description: The retrieved page of items.
discriminator:
propertyName: type
CommercePageModelListingConfigurationNameModel:
required:
- items
- totalEntries
- totalPages
type: object
properties:
items:
type: array
description: The retrieved page of items.
items:
$ref: '#/components/schemas/ListingConfigurationNameModel'
totalEntries:
type: integer
description: The total number of results that match the query.
format: int64
totalPages:
type: integer
description: The total number of pages of items available.
format: int32
description: Page
ListingConfigurationNameModel:
required:
- name
- url
type: object
properties:
id:
type: string
description: The unique identifier of the listing configuration.
format: uuid
readOnly: true
example: 644e1dd7-2a7f-18fb-b8ed-ed78c3f92c2b
name:
maxLength: 255
minLength: 1
type: string
description: A unique name for the listing configuration.
example: ACME Corp Summer Trends
url:
maxLength: 1024
minLength: 1
type: string
description: URL associated to a listing configuration used for pattern matching.
description: The retrieved page of items.
securitySchemes:
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://platform.cloud.coveo.com/oauth/authorize
tokenUrl: https://platform.cloud.coveo.com/oauth/token
scopes:
full: required