Product/Content Catalog

Elizabeth

October 11, 2017 00:29

Integrating your product or content feed(s) allows us to include relevant recommendations in your messages. Multiple options are available:

1 - Feeds: JSON or CSV via FTP/HTTP/S3 Bucket
2 - Catalog API
3 - Catalog Attributes

1. Feeds

To setup a catalog using Feeds, please 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. Note, you may need to provide additional information depending on the option
Select upload frequency (hourly, daily, weekly, monthly)

**Things to check before uploading 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"

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

2. Catalog API

The catalog API allows the following actions:

Create Catalog
Add Item To Catalog

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

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

Sample Response

JSON

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

Add Item To Catalog

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

Inputs:

"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

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X PUT -u <USER API KEY>: https://api.getblueshift.com/api/v1/catalogs/<CATALOG UUID>.json -d '
{
    "catalog": {
        "products": [
            {
                "brand": "Nike",
                "category": [
                    "Home",
                    "Home > Shoes",
                    "Home > Shoes > Running"
                ],
                "image": "http://server/path/image.jpg",
                "msrp": "47",
                "price": "37.99",
                "product_id": "189909",
                "stock": "in stock",
                "tags": [
                    "running",
                    "athlete"
                ],
                "title": "Nike Jordan Running Shoes in Blue",
                "web_link": "http://server/path/product.html"
            },
           {
                "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"
            }
        ]
    }
}'

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)	http://www.apple.com/iphone-7
image	Image Link (http or https)	http://www.apple.com/iphone-7.jpg
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	Apple
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.
latitude/longitude	Latitude/Longitude denoting location	37.792805, -122.401444 for San Francisco Downtown

Custom fields

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

Example: color, gender etc

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.

1. Category

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:
For csv upload, you can denote multiple levels using a delimiter and can specify the delimiter when uploading the file. The delimiter is ">" in the below example.
Ex: "Travel > Europe > Italy"

Api Upload:
For API upload, you will denote multiple levels using an array of strings.
Ex: ["Travel","Travel > Europe","Travel > Europe > Italy"]

If it's uploaded correctly, the category should show up like this on our dashboard when you see individual product details.

Ex:

2. Excluding Unavailable Items

We use the following fields to determine when the product is available or not. This helps us to exclude out of stock products to customers.

If the end_date is not current or
If the availability is set to "out of stock"