Catalog Attributes

You can upload catalogs into Blueshift in the form of CSV, JSON, or XL files. When you upload catalogs, you must include the required fields. There are also recommended fields and custom fields that you can include.

Data format

You must include the following required fields:
- item_id (product_id)
- item_title (title)
- item_url (web_link or product url)
- main_image (image url)
- category
Recommended fields: We also recommend that you include brand, in/out of stock and other custom fields you may want to use in segmentation and messaging.
You can set rules in the catalog settings to set a product as out_of_stock or in_stock by mapping the column to the Availability field.
Alternatively, for each product, you can set "start_date" and "end_date" fields in the file. The expected format is ISO8601 for these two fields. Ex: "2017-08-08", "2017-08-08T17:42:32Z". Blueshift uses these fields to automatically set a product to out_of_stock if the current_date does not fall within that range.
Use true or false (lower case) for boolean values.
Use snake case where possible, as it's much easier to use it in the templates.
Ex: "Release_Year" instead of "Release Year"
The value of the item_id (product_id) field must not have more than 64 characters.
The item_title (title) of the product must not have more than 255 characters.
The URL that you provide in the main_image (image) field must not have more than 500 characters.
The URL that you provide in the item_url (web_url) field must not have more than 500 characters.

Other considerations

Blueshift uses INSERT/UPDATE logic to INSERT new products and UPDATE existing products as identified by SKU/product_ID.
If you are uploading using CSV files, ensure that you delete any empty columns.
Files must be UTF-8 encoded CSV.
Blueshift supports multiple catalogs as along as the product ids are unique within and across all catalogs.

Required fields

Attribute	Description	Example
item_id or product_id	Unique identifier of item, should be unique across all your catalog's. Maps to item_id when you set up the import task. The item_id is case sensitive and must not have more than 64 characters.	123345_abcd
item_title or title	Title of the item. Maps to item_title when you set up the import task. The item_title must not have more than 255 characters.	Iphone 7
item_url or web_link	URL for item on your website (http or https). Maps to item_url when you set up the import task. The item_url must not have more than 500 characters.	http://www.apple.com/iphone-7
main_image or image	Image Link (http or https). Maps to main_image when you set up the import task. The main_image URL must not have more than 500 characters.	http://www.apple.com/iphone-7.jpg
category	Logical grouping of items. The grouping can be hierarchical with any number of levels. This is very important field and many of the recommendation schemes use this grouping to compute trending and popular products. Ensure that your category attribute is populated correctly.	Travel > Europe > Italy

Recommended fields

Attribute	Description	Example
parent_sku	Ties all variants or child items together. You can use parent sku to ensure you recommend only one variant in your recommendations. For example, only one color of the same dress, instead of multiple colors.	12345_abcd
price	Selling/Discounted Price. Used for computing price drop alerts	290
msrp	MSRP	350
brand	Brand of the item	Nike
start_date	Indicates active/inactive status. Should be in ISO 8601 format. This is used to determine product recency, like recommending new arrivals.	2017-06-09T15:28:33Z
end_date	Indicates active/inactive status. Should be in ISO 8601 format. This field is used to recommend ending soon products if present	2017-07-09T15:28:33Z
availability	Indicates item status. Used for excluding out of stock products in recommendations. Also used for computing back in stock alerts when a product goes out of stock and comes back in stock.	"in stock" or "out of stock"
tags	An array of strings denoting grouping of similar products into collections or groups. The array can be used for recommending similar items based on text similarity.	["genre:sci-fi", "cuisine:italian", "keyword1"]
latitude	Latitude that denotes location	37.792805 for San Francisco Downtown
longitude	Longitude that denotes location	-122.401444 for San Francisco Downtown
location_tag	Tag to indicate location to its maximum possible detail that is available. This is a single string.	Points of Interest > USA > NY > New York > Times Square

For more information, see Products and catalogs on our developer portal.

Custom fields

You can also upload other relevant attributes you would like to include for segmentation and content personalization.

For example, color, gender, and so on.

Considerations for Category field

The Category field is an important field for computing affinities and popular recommendations at different levels of your product groupings. Consult your Blueshift Success Manager for guidance in selecting the appropriate format.

We recommend that you provide multiple levels (at least 2) for better recommendations. The format is bit different for API and for CSV upload. When uploaded correctly, the category is displayed on the dashboard when you view the individual product details.

File Upload

When using a CSV file for upload, you can denote multiple levels by using a delimiter and can specify the delimiter when uploading the file.

For example, "Travel > Europe > Italy" where the delimiter is ">".

API Upload

For API upload, you can denote multiple levels using an array of strings.

For example, ["Travel","Travel > Europe","Travel > Europe > Italy"]

Note

The category field must be in string format. The category separator or delimiter denotes multiple levels for categories in the CSV file. Use ">" as the delimiter and ensure that you define it when you set up the import task. if the category field is in Array or Object format, you will not be able to use the catalog items in recommendations.

Examples

Here is an example of a catalog CSV file.

MovieCatalog.csv

id,movie_id,original_title,homepage,genre,runtime,original_language,poster_path,overview

524434,tt9032400,Eternals,https://www.marvel.com/movies/the-eternals,English>Action>Fantasy,156,en,https://image.tmdb.org/t/p/original//b6qUu00iIIkXX13szFy7d0CyNcg.jpg,"The Eternals are a team of ancient aliens who have been living on Earth in secret for thousands of years. When an unexpected tragedy forces them out of the shadows, they are forced to reunite against mankind’s most ancient enemy, the Deviants."

438695,tt6467266,Sing 2,https://www.illumination.com/movie/sing-2/,English>Animation>Family,110,en,https://image.tmdb.org/t/p/original//aWeKITRFbbwY8txG5uCj4rMCfSP.jpg,"Buster and his new cast now have their sights set on debuting a new show at the Crystal Tower Theater in glamorous Redshore City. But with no connections, he and his singers must sneak into the Crystal Entertainment offices, run by the ruthless wolf mogul Jimmy Crystal, where the gang pitches the ridiculous idea of casting the lion rock legend Clay Calloway in their show. Buster must embark on a quest to find the now-isolated Clay and persuade him to return to the stage."

634649,tt10872600,Spider-Man: No Way Home,https://www.spidermannowayhome.movie,English>Action>Fantasy,148,en,https://image.tmdb.org/t/p/original//1g0dhYtq4irTY1GPXvft6k4YLjm.jpg,"Peter Parker is unmasked and no longer able to separate his normal life from the high-stakes of being a super-hero. When he asks for help from Doctor Strange the stakes become even more dangerous, forcing him to discover what it truly means to be Spider-Man."

Here is an example of a catalog JSON file.

MovieCatalog.json


  [
  {
    "id": 524434,
    "movie_id": "tt9032400",
    "original_title": "Eternals",
    "homepage": "https://www.marvel.com/movies/the-eternals",
    "genre": "English>Action>Fantasy",
    "runtime": 156,
    "original_language": "en",
    "poster_path": "https://image.tmdb.org/t/p/original//b6qUu00iIIkXX13szFy7d0CyNcg.jpg",
    "overview": "The Eternals are a team of ancient aliens who have been living on Earth in secret for thousands of years. When an unexpected tragedy forces them out of the shadows, they are forced to reunite against mankind’s most ancient enemy, the Deviants."
  },
  {
    "id": 438695,
    "movie_id": "tt6467266",
    "original_title": "Sing 2",
    "homepage": "https://www.illumination.com/movie/sing-2/",
    "genre": "English>Animation>Family",
    "runtime": 110,
    "original_language": "en",
    "poster_path": "https://image.tmdb.org/t/p/original//aWeKITRFbbwY8txG5uCj4rMCfSP.jpg",
    "overview": "Buster and his new cast now have their sights set on debuting a new show at the Crystal Tower Theater in glamorous Redshore City. But with no connections, he and his singers must sneak into the Crystal Entertainment offices, run by the ruthless wolf mogul Jimmy Crystal, where the gang pitches the ridiculous idea of casting the lion rock legend Clay Calloway in their show. Buster must embark on a quest to find the now-isolated Clay and persuade him to return to the stage."
  },
  {
    "id": 634649,
    "movie_id": "tt10872600",
    "original_title": "Spider-Man: No Way Home",
    "homepage": "https://www.spidermannowayhome.movie",
    "genre": "English>Action>Fantasy",
    "runtime": 148,
    "original_language": "en",
    "poster_path": "https://image.tmdb.org/t/p/original//1g0dhYtq4irTY1GPXvft6k4YLjm.jpg",
    "overview": "Peter Parker is unmasked and no longer able to separate his normal life from the high-stakes of being a super-hero. When he asks for help from Doctor Strange the stakes become even more dangerous, forcing him to discover what it truly means to be Spider-Man."
  }
  ]