Integrating your product or content feeds allows Blueshift to include relevant and up to date recommendations in your messages. Blueshift supports multiple ways of importing catalogs. You can upload catalogs into Blueshift in the form of CSV, JSON, or Excel files.

When you upload catalogs, you must include the required fields. There are also recommended fields and custom fields that you can include.

Import methods

You can send catalog data to Blueshift using any of the following methods:

data_catalogs_dec23.png

Upload CSV from UI Upload catalog data using a CSV file, Excel file, or JSON format.
Feeds via SFTP Upload catalog data using a CSV file, Excel file, or JSON format, from a location using SFTP.
Feeds via HTTP URL Upload catalog data using a CSV file, Excel file, or JSON format, from your preferred location using an HTTP URL
From Amazon S3 Upload catalog data using a CSV file, Excel file, or JSON format saved in an Amazon S3 bucket.
From Snowflake

With the integration of Blueshift and Snowflake, you can import catalog data into your Blueshift account very easily.

Before you can import data from Snowflake you must set up integration of Blueshift with Snowflake and configure at least one adapter.

API Use the Create Catalog API to add a catalog to Blueshift. You can also use the Add items to a catalog API to add items to an existing catalog.

Data types supported

Blueshift supports the following data types:

  • String
  • Integer
  • Date
  • Decimal
  • Boolean data types
  • Array
  • Object (via Snowflake only)

Considerations

Consider the following points about importing catalogs into Blueshift:

  • Blueshift uses INSERT/UPDATE logic to INSERT new products and UPDATE existing products as identified by SKU/product_ID.
  • Attributes with data type as Boolean cannot be set to a NULL or blank value and must be set as either true or false (lower case). If you require an attribute to have a blank value, use the String data type instead of a Boolean data type.
  • Dates must be in ISO8601 format. For example, 1980-05-19T15:22:01-07:00. 
    • Dates can be converted in an Excel file by using a function to add (=A2+TIME(8,0,0) ) or subtract hours (=A2-TIME(8,0,0)) so the time is represented in the UTC time. Replace A2 with the cell of the date you are converting. Please note that this is good for one time uploads as it does not take into account daylight savings for ongoing file uploads. For example: yyyy-mm-ddThh:mm:ss-05:00 for Eastern (Est) timezone. Converting time = A2,5,0,0 will add 5 hours to the time converting EST timezome to UTC.
    • You can also format the date in Excel using custom format to convert the date to ISO8601 format yyyy-mm-ddThh:mm:ss+/-00:00. Replace +/-00:00 with the time zone offset for your timezone.
  • We recommend that you use snake case for catalog attribute names where possible, as it's much easier to use it in the templates.
    For example, "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 

Catalog fields

You must include the following required fields when you upload catalogs:

  • 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.

Custom fields: You can upload other relevant attributes you would like to include for segmentation and content personalization. For example, color, gender, and so on.

Important: Blueshift supports multiple catalogs as long 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 catalogs. 

  • 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.
  • When you pass the product_ids in your events, the values that you pass should exactly match the product_id in the catalog.
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 a 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.

For more information, see Considerations for the category field.

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. This is used to determine product recency, like recommending new arrivals.

Should be in ISO 8601 format. 

2017-06-09T15:28:33Z
end_date

Indicates active/inactive status. This field is used to recommend ending soon products if present.

Should be in ISO 8601 format. 

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

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 a 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.

Out of stock

You can use any of the following ways to set the availability of items. If you are using recommendations, the availability of items is used to exclude out of stock products. The availability is also used for computing back in stock alerts when a product goes out of stock and comes back in stock.

  • 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 the start_date and end_date fields in the catalog file. Blueshift uses these fields to automatically set a product to out_of_stock if the current_date does not fall within that range. The date must be in ISO8601 format . Ex: "2017-08-08", "2017-08-08T17:42:32Z". 

File for data upload

Catalog data can be uploaded in the following formats:

  • CSV
  • JSON
  • XML

Considerations for CSV files:

  • If you are uploading using CSV files, ensure that you delete any empty columns.
  • Files must be UTF-8 encoded CSV.

When you create a task, you can click Download Sample CSV to get the sample data file.

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."
  }
  ]
  
Was this article helpful?
1 out of 1 found this helpful

Comments

0 comments

Please sign in to leave a comment.