Integrating your product or content feeds allows us to include relevant recommendations in your messages. Multiple options are available to import your catalog data into Blueshift.

Using Feeds

To setup a catalog using Feeds, navigate to Catalog tab and click the +Catalog button to add a feed.


Pick the appropriate feed type, complete all required fields and click Validate.

  • Enter a unique feed/catalog name
  • Choose E-Commerce as Feed Type
  • Pick the appropriate feed upload method. You can upload files via HTTP/FTP/Direct file upload/S3 bucket/SFTP. Provide additional information based on the option that you choose. For example, if you choose S3, we need S3 access key, secret access key, bucket name, and the region. Similarly, if you want to us to pick files from an FTP location, in addition to the URL of the server where you host the files and the port on which FTP service is running, we need credentials to access files on that location. 
  • Select upload frequency. Your options are:
    • Only once
    • Weekly
    • Daily
    • Hourly

    In addition, you can specify Update Time. You can use this option to let our platform know whether:

    • It should import files from the S3 location instantly
    • Or it should start the import at a date and time that you specify (for weekly, daily, and hourly imports). In addition, you can also specify when our platform should stop importing the files based on the setting that you specify in the End option. 

Things to check before uploading a file

  • Be sure to delete any empty columns
  • File must be UTF-8 encoded csv
  • At the very least, we need product id, product name, product url (http or https), image url (http or https) and category. However, we also recommend sending us brand, in/out of stock and other custom fields you may want to use in segmentation and messaging
  • We support multiple catalogs. However, product ids must be unique within and across all catalogs
  • You can set rules in the catalog settings to set a product as out_of_stock or in_stock by mapping your 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". We will use them to automatically set a product to out_of_stock if the current_date does not fall within that range.
  • We use INSERT/UPDATE logic to INSERT new products and UPDATE existing products as identified by SKU/product_ID.
  • Please use true or false (lower case) for boolean values.
  • Please 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 product_id field must not have more than 64 characters.
  • The title of the product must not have more than 255 characters.
  • The URL that you provide in the image field must not have more than 500 characters.
  • The URL that you provide in the web_url field must not have more than 500 characters. 


In the next screen, you will need to map your catalog attributes to Blueshift defined attributes. Attributes that cannot be mapped to our standard ones will be loaded as custom attributes.


You will receive an email confirmation once the catalog has been uploaded including processed and failed records.

Screen_Shot_2018-03-30_at_6.05.28_PM.png 4d266a6-SampleCatalogSku.png

Using the Catalog API

Use the catalog API for the following actions:

Create Catalog

You can create a new catalog from the API by using the create catalog API end-point.

Inputs “name”: Catalog name (string)
Output On successful create, returns the catalog’s unique identifier.

Sample call


curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"catalog" : {"name" : "ACME Item Catalog"}}' -u <USER API KEY>:

Sample Response


{"catalog_uuid":"<CATALOG UUID>"}


Add Items to a catalog

You can add multiple items to a catalog in batches of 100 items at a time, by using the add item to catalog API end-point.

  • "catalog uuid": Use the catalog uuid as returned from the create a catalog api end-point
  • Array of products
Output On success, returns “ok”.


curl -v -H "Accept: application/json" -H "Content-type: application/json" -X PUT -u <USER API KEY>:<CATALOG UUID>.json -d '
    "catalog": {
        "products": [
                "brand": "Nike",
                "category": [
                    "Home > Shoes",
                    "Home > Shoes > Running"
                "image": "http://server/path/image.jpg",
                "msrp": "47",
                "price": "37.99",
                "product_id": "189909",
                "availability": "in stock",
                "tags": [
                "title": "Nike Jordan Running Shoes in Blue",
                "web_link": "http://server/path/product.html".
"latitude": "37.792805",
"longitude": "-122.401444",

"location_tag": "Points of Interest > USA > California > San Francisco > San Francisco Downtown"
}, { "brand": "Reebok", "category": [ "Home", "Home > Shoes", "Home > Shoes > Sports" ], "image": "http://server/path/image2.jpg", "msrp": "47", "price": "37.99", "product_id": "189910", "availability": "in stock", "tags": [ "basketball" ], "title": "Reebok Basketball Shoes", "web_link": "http://server/path/product2.html" } ] } }'

Catalog Attributes 

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

Required fields

Attribute Description Example
product_id Unique identifier of item, should be unique across all your catalog's. 123345_abcd
title Title of the item Iphone 7
web_link URL for item on your website (http or https)
image Image Link (http or https)
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"
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.  Please 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
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, ans so on.

Considerations for Category field 

The Category field is an important signal for computing affinities and popular recommendations at different levels of your product groupings. Consult your Blueshift Success Manager for guidance in choosing 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.

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"]

When uploaded correctly, the category is displayed on the dashboard when you view the individual product details.

For example:be230b7-sample_category_shown_on_blueshift_product_detail_page.png

Excluding unavailable items

You cannot delete items from a catalog. Deletion of catalog items is not allowed so as to maintain a historical record of the item.

Use the following fields to determine when the product is available or not. You can then use the options in the recommendation studio to exclude “out of stock” items.

  • If the end_date is not current or
  • If the availability is set to "out of stock"
Was this article helpful?
0 out of 0 found this helpful



Please sign in to leave a comment.