External lists data entities
Intelligent Recommendations allows you to curate manually authored item lists. This list is useful, for example, in a cold-start scenario, where you don't have enough user interactions data to generate meaningful recommendations. Another scenario is for creating promotional lists, such as for a “back to school” sale, or "Editor's picks".
In any case, item availabilities are always respected. Any item that isn't considered available when the recommendation API is called isn't returned as part of the response.
The following data entities are part of the external lists data entities:
External recommendations lists
Data entity name: Reco_ExternalRecommendationsLists
Description: External lists of recommendations
Attributes:
| Name | Data type | Mandatory | Default value | Invalid value behavior | Comments |
|---|---|---|---|---|---|
| ListName | String(64) | Yes | Trim Value | Unique list identifier, also used when querying for the list. Length limited to 64 characters. | |
| Title | String(256) | Yes | Trim Value | Length limited to 256 characters. | |
| ListAvailabilityStartDate | DateTime | No | 0001-01-01T00:00:00.000Z | Drop entry | See Required data entities per recommendations scenario for DateTime values. |
| ListAvailabilityEndDate | DateTime | No | 9999-12-31T23:59:59.999Z | Drop entry | See Required data entities per recommendations scenario for DateTime values. |
Guidelines:
This data entity is for future use.
ListName attribute has the following restrictions:
- Set of allowed characters: A-Z, a-z, 0-9, _, -, ~, ..
- It's case-insensitive.
- Existing RecoListName values are reserved and can't be used as ListName values. See full list of reserved names on the Enrichment data entities page.
- Using the list availability start and end dates, you can determine the availability of the list, which Intelligent Recommendations can serve only between these specified dates.
Sample data:
Headers appear for convenience only and shouldn't be part of the actual data.
| ListName | Title | ListAvailabilityStartDate | ListAvailabilityEndDate |
|---|---|---|---|
| SummerSale2020 | Best summer items for 2020 | 2020-07-01T00:00:00.000Z | 2020-08-31T23:59:59.999Z |
External recommendations items
Data entity name: Reco_ExternalRecommendationsItems
Description: Items for the external lists of recommendations
Attributes:
| Name | Data type | Mandatory | Default value | Invalid value behavior | Comments |
|---|---|---|---|---|---|
| ListName | String(64) | Yes | Trim Value | Unique list identifier, which is also used when querying for the list. Length limited to 64 characters. You can view the table of ListNames here. | |
| ItemId | String(16) | Yes | Drop entry | See Required data entities per recommendations scenario for itemId. |
|
| ItemVariantId | String(16) | No | Drop entry | See Required data entities per recommendations scenario for itemVariantId. |
|
| Rank | Int | Yes | Drop entry | The position order you want each item to appear. |
Guidelines:
This data entity is for future use.
See ListName guidelines in data entity Reco_ExternalRecommendationsLists.
Intelligent Recommendations doesn't guarantee the internal ordering between multiple items that were assigned with the same rank in the same list.
In the case that the same item or item variant appears in a list more than once, its highest ranking is used, and all other entries are ignored.
For each ListName value in this data entity, there must be a corresponding entry with the same ListName value in the Reco_ExternalRecommendationsLists data entity; otherwise, the entry is ignored.
Sample data:
Headers appear for convenience only and shouldn't be part of the actual data.
| ListName | ItemId | ItemVariantId | Rank |
|---|---|---|---|
| SummerSale2020 | Item2 | 1 | |
| SummerSale2020 | Item3 | Item3Var1 | 2 |
| SummerSale2020 | Item1 | Item1Var2 | 3 |
See also
Data contract overview
Data entities mapping table
Catalog data entities
Image to item mapping data entities
Interactions data entities
Reco configuration data entities
Opted-out users data entities
Recommendations enrichment data entities
Intelligent Recommendations API
Quick start guide: Set up and run Intelligent Recommendations with sample data