External lists data entities

  • Article

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