Import catalog data

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 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".
• Ensure that event names do not contain periods, are not numeric, and the event name does not have more than 64 characters.
• 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.
• Only uppercase letters, lowercase letters, digits, hyphens, underscores, and whitespace are accepted for attribute names. For example, user's_device is an invalid name, but user_device, is a valid name. 

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

Recommended fields

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.

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.

Here is an example of a catalog JSON file.

  [
  {
    "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."
  }
  ]