Skip to main content
Skip table of contents

Catalog Feed

The catalog feed is a structured list of products and categories. This feed keeps your product information current in Emplifi Ratings & Reviews. The catalog is a FIFO, not a nightly cron job.

Providing the catalog feed

You can provide your catalog feed to Emplifi Ratings & Reviews by manually uploading the file, supplying the file's URL or FTP location, or setting up an automated collection via the TurnTo API for Emplifi Ratings & Reviews.

Manual File Upload

Feeds uploaded through the Ratings & Review Portal have a 250 MB file size limit. Larger feed files should be delivered via FTP or through the API.

Steps:

  1. In Emplifi Ratings & Reviews, click Settings → Feeds → Upload Feed.

  2. From the Feed Type dropdown menu, select TurnTo Catalog.

  3. (Optional) Select an encoding.

  4. Choose your file, and then select Validate Only.

Upload File by URL or FTP

Steps:

  1. In Emplifi Ratings & Reviews, click Settings → Manage Site.

  2. Check the Catalog Feed Pull Enabled checkbox.

  3. From the Catalog Feed Type dropdown menu, select TurnTo Tab-delimited.

  4. (Optional) From the Catalog Feed Encoding dropdown, select an encoding.

  5. Click Add catalog url, enter the file URL or FTP location, and click Save.

  6. Scroll to the bottom of the page and click Update to save your changes.

To deliver via the TurnTo API for Emplifi Ratings & Reviews, see Automating Feeds with the TurnTo API for Emplifi Ratings & Reviews.

TurnTo catalog feed format

Emplifi Ratings & Reviews can work with multiple feed formats. However, using the TurnTo feed format avoids the need for data transformation and gets you up and running the fastest.

Ensure that your feed file adheres to these formatting requirements:

  • The feed must be a tab-delimited text file.

  • The first row of the tab-delimited file must include at least the required headers, in any order.

  • For syndicating outside of Emplifi Ratings & Reviews, you must provide at least one of: MPN, UPC, ISBN, EAN, JAN. Provide as many of these fields as you can.

    • For syndicating to partner sites using Bazaarvoice's CGC platform, you must provide UPC or EAN.

    • For Google Shopping Feed syndication, Google recommends submitting brand, MPN, and GTIN (one of UPC, ISBN, EAN, or JAN) to help boost ad performance and help users find your products. To see requirements or to contact Google for help, see Google's document about unique product identifiers.

Supported data field

Header

Header Required

Value Required

Description

SKU

Yes

Yes

The unique identifier for the item in your catalog. This should be an identifier for the item on the product page. Read more about variant SKUs.

When the historical order feed or JavaScript order feed transmits an order for an item, it should use the same SKU as your catalog feed.

Prohibited Characters
Do not include the following characters in your SKU values: / # \ > < & = % ! . +

TITLE

Yes

Yes

The name of the product or item.

ITEMURL

Yes

Yes

The URL of the item on your site. We support both relative and absolute link URLs.

IMAGEURL

Yes

No

The URL of the image of your catalog item to display in the widgets and in emails. Although it's not required, we highly recommend that you include it in the feed.

PRICE

Yes

No

Formatted as ####.##. This field is not required, but it is highly recommended because Emplifi Ratings & Reviews selects items for review solicitation emails (RSEs) based on price. For this to work, you must include a price value in your catalog. RSEs prioritize items by price based on the catalog feed, not the order data. If there's no value in the catalog feed, items to be sent in RSEs are picked at random.

CURRENCY

Yes

No

Defaults to USD.

CATEGORY

Yes

No

The name of the category that this item belongs to. An item can only belong to one category. If you will be specifying a category path, include the CATEGORY header (because the header is required) but leave the value blank. Instead, define your categories in the CATEGORYPATHJSON field.

Read more about
Categories in the Catalog Feed.

ACTIVE

No

No

Boolean value (1 or 0, Y or N). Defaults to 1, which means the listing is active.

CATEGORYPATHJSON

No

No

To pass Emplifi Ratings & Reviews a category path for this product, include a JSON array of category objects in the order of most general to most specific.

Required fields for each object in the array:

  • id

    (warning) IDs must be unique. Do not use name as id.

  • name

Optional field for each object in the array:

INSTOCK

No

No

Boolean value (1 or 0, Y or N). Defaults to 1, which means the item is in stock.

VIRTUALPARENTCODE

No

No

An arbitrary string used to group products. For example, if your catalog has a row for each color variant of an item, those variants can be grouped in Ratings & Reviews as similar items by setting this column to the same value for all of them. When a question is asked about one variant, it will automatically appear in the Q&A widget on each of the other variant pages as a question about a similar item.
To learn more, see Virtual parent-code (VPC) and members.

ISCATEGORY

No

No

Boolean value (1 or 0, Y or N). Defaults to 0, which means the row is not a category. Used to specify whether this row describes a category or an orderable item.

MEMBERS

No

No

If this product is a bundle of other products, specify the SKUs of the members (comma-delimited). To learn more, see Members.

BRAND

No

No

The product's brand name. If used together with MPN, this field uniquely identifies the product.

MPN

No

No

(Manufacturer part number) The string that uniquely identifies the product to its manufacturer. If used together with BRAND, this field uniquely identifies the product across the entire catalog.

You can specify more than one value by comma-separating multiple MPNs. This is useful when your feed contains only parent products but you'd like to pass MPNs for child (variant) products, such as different sizes of a shirt.

UPC

No

No

(Universal Product Code) A unique, 12-digit identifier for commercial products that's usually associated with a barcode printed on retail merchandise. Used mainly in North America.

You can specify more than one value by comma-separating multiple UPCs. This is useful when your feed contains only parent products but you'd like to pass UPCs for child (variant) products, such as different sizes of a shirt.

ISBN

No

No

(International Standard Book Number) A unique numerical identifier for commercial books published since 1970 that can be found on the back of the book along with the barcode.

EAN

No

No

(European Article Number) A unique numerical identifier for commercial products that's usually associated with a barcode printed on retail merchandise. Used mainly outside of North America.

JAN

No

No

(Japanese Article Number) A unique numerical identifier for commercial products that's usually associated with a barcode printed on retail merchandise. Used in Japan.

ASIN

No

No

(Amazon Standard Identification Number) Uniquely identifies each product sold on http://amazon.com.

MOBILEITEMURL

No

No

The URL of the item on your mobile site.

LOCALEDATA

No

No

A JSON field that allows the specification of locale specific product titles and urls. In order to be utilized, the locale must be setup for the site. Valid locales include both the language and country code. For example, "fr_CA" has "fr" for French and "CA" for Canada.

If LOCALEDATA is specified, 'title' and 'itemUrl' are required, but 'mobileItemUrl' is not required. The following JSON example demonstrates the format:

{"fr_CA": {"title": "Bleu Chemise", "itemUrl": "https://domain.com/pathToFrenchProductPage", "mobileItemUrl": "https://domain.com/pathToMobileFrenchProductPage"}}

Example using two locales:

{"fr_CA": {"title": "Bleu Chemise", "itemUrl": "https://domain.com/pathToFrenchProductPage", "mobileItemUrl": "https://domain.com/pathToMobileFrenchProductPage"}, "de_DE": {"title": "Blau Hemd", "itemUrl": "https://domain.com/pathToGermanProductPage", "mobileItemUrl": "https://domain.com/pathToMobileGermanProductPage"}}

TurnTo feed format examples

For your reference, the following are sample catalog feed files in the TurnTo format:

NONE
SKU	TITLE	ITEMURL	IMAGEURL	PRICE	CURRENCY	CATEGORY	CATEGORYPATHJSON	MPN	BRAND	UPC
SKU1	Product Title 1	https://www.domain.com/SKU1	https://www.domain.com/images/SKU1.png
SKU2	Product Title 2	https://www.domain.com/SKU2	https://www.domain.com/images/SKU2.png
SKU3	Product Title 3	https://www.domain.com/SKU3	https://www.domain.com/images/SKU3.png
NONE
SKU	IMAGEURL	TITLE	PRICE	CURRENCY	ACTIVE	ITEMURL	CATEGORY	KEYWORDS	INSTOCK	VIRTUALPARENTCODE	CATEGORYPATHJSON	MEMBERS	BRAND	MPN	ISBN	UPC	EAN	JAN	ASIN	MOBILEITEMURL	LOCALEDATA
195	https://domain.com/product_images/195.jpg	Blue Shirt 	14	USD	Y	https://domain.com/en_US/195.html			Y	195	[{"id":"collections","name":"Collections","url":"https://domain.com/en_US/collections"},{"id":"shirt-collection","name":"Shirt Collection","url":"https://domain.com/en_US/shirt-collection"}]		MyBrand			846733254966				https://domain.com/en_US/195.html	{"fr_CA": {"title": "Bleu Chemise", "itemUrl": "https://domain.com/pathToFrenchProductPage", "mobileItemUrl": "https://domain.com/pathToMobileFrenchProductPage"}, "en_DE": {"title": "Blau Hemd", "itemUrl": "https://domain.com/pathToGermanProductPage", "mobileItemUrl": "https://domain.com/pathToMobileGermanProductPage"}}

Other accepted feed formats

We can work with additional feed formats. However, using the TurnTo feed format avoids the need for data transformation and gets you up and running the fastest.

  • Yahoo objinfo.xml

  • Google Products search XML (Atom 1.0 version) with Google's own namespace extension

  • Google Products search XML (RSS 2.0 version) with Google's own namespace extension

  • Google Products tab-delimited

  • Bazaarvoice Product Feed

Virtual parent code (VPC) and members

The VIRTUALPARENTCODE field and the MEMBERS field both create an association between individual products. So what’s the difference between these fields? And when should you use one instead of the other?

Virtual parent code

Use VIRTUALPARENTCODE to associate items together. The virtual parent code is not an identifier for an actual product. It creates a "sibling" relation between products that have the same virtual parent code.

Example: paperback, hardcover, and ebook variations of a book. Each variation is related to the other variations because the content of the books is the same.

The VIRTUALPARENTCODE field contains a string that you define as the unique way to identify a set of associated products.

Here’s an example of how to use the VIRTUALPARENTCODE field (several fields omitted for simplicity):

SKU

TITLE

VIRTUALPARENTCODE

45722

Selling Llamas Online (paperback)

5a2c28-llama

45723

Selling Llamas Online (hardcover)

5a2c28-llama

65270

Selling Llamas Online (ebook)

5a2c28-llama

Example: Virtual parent code in tab-delimited format

NONE
SKU	TITLE	VIRTUALPARENTCODE
45722	Selling Llamas Online (paperback)	5a2c28-llama
45723	Selling Llamas Online (hardcover)	5a2c28-llama
65270	Selling Llamas Online (ebook)	5a2c28-llama

How virtual parent codes impact your installation

Reviews and questions for each "sibling" product (any product that shares the same virtual parent code) can display as related content in each of the other siblings' review and Q&A widgets.

In the book example, the VIRTUALPARENTCODE field creates the following "related content" relationships:

image-20240226-123540.png

Members

Use MEMBERS when a product SKU includes one or more products that are also listed under their own SKUs.

Example: a camera kit. All of the pieces can be sold individually, but the kit has its own SKU, title, price, product image, etc.

The MEMBERS field contains a comma-separated set of the SKUs that this item contains.

Here’s an example of how to use the MEMBERS field (several fields omitted for simplicity):

SKU

TITLE

MEMBERS

99674

Camera Kit

78515, 95178, 98254

78515

Digital SLR Camera

95178

Camera Carrying Case

98254

50mm Lens

Example: Members in tab-delimited format

NONE
SKU	TITLE	MEMBERS
99674	Camera Kit	78515, 95178, 98254
78515	Digital SLR Camera
95178	Camera Carrying Case
98254	50mm Lens

How members impact your installation

Reviews and questions for the bundle can display as related content in the individual members' review and Q&A widgets. Reviews and questions for each member product can display as related content in the bundle product’s review and Q&A widgets.

In the camera kit example, the MEMBERS field creates the following "related content" relationships:

image-20240226-123814.png

The MEMBERS field does not create any relationship between the individual bundle members. In other words, they don’t become "sibling" products.

Variant SKUs

Consider a shirt that comes in three possible colors: red, green, or blue. You want reviews for the shirt to be shown together, regardless of the color. You have to decide how to represent that shirt within your Ratings & Reviews catalog feed. You have two options: use a SKU for each variant and relate them through the VIRTUALPARENTCODE field, or use a master SKU for all variants. This section explains each option, along with pros and cons.

Use a SKU for each variant

If you want each variant in your original catalog to have its own entry in your Emplifi Ratings & Reviews product catalog feed, you can relate variant items together by including an identical VIRTUALPARENTCODE value for all variants. Your variants likely already have a code from your originating system that ties them together. Use that code in the VIRTUALPARENTCODE field.

  • Pros
    In this scenario, the t-shirt's red, green, and blue color variants each have their own SKUs in your original catalog: SHIRT83-RED, SHIRT83-GREEN, and SHIRT83-BLUE. Since you created a catalog entry for each variant, you should include a row in your catalog feed for each of the three colors. On each row, you should also include a value in the VIRTUALPARENTCODE field that ties the variants together, such as SHIRT83. Note that in this example SHIRT83 is not a SKU in your Emplifi Ratings & Reviews product catalog feed.

  • Cons
    Requires more detailed understanding of how Emplifi Ratings & Reviews widgets function. For example, reviews do not post at the virtual parent code level. Reviews post at the SKU level, which in this case is specific to the variant rather than the product. The Review List widget can list all variants' reviews combined ("mixed in"), or list just this SKU's reviews and then show other variants' reviews in a separate "Reviews for Similar Products" area.

Example: One catalog entry for each color of a t-shirt
In this scenario, the t-shirt's red, green, and blue color variants each have their own SKUs in your original catalog: SHIRT83-RED, SHIRT83-GREEN, and SHIRT83-BLUE. Since you created a catalog entry for each variant, you should include a row in your catalog feed for each of the three colors. On each row, you should also include a value in the VIRTUALPARENTCODE field that ties the variants together, such as SHIRT83. Note that in this example SHIRT83 is not a SKU in your Emplifi Ratings & Reviews product catalog feed.

Use a master SKU

If you want to collapse a set of variants from your original product catalog into a single item in your Emplifi Ratings & Reviews product catalog feed, you can use a "master" SKU that represents all of the variants. You can include variants in the single catalog entry by listing variant UPCs in the UPC field.

  • Pros
    Since one SKU covers all of the variants for a product, all of the variants' reviews, questions and answers, and visual content for that product are automatically included on the product detail page.

  • Cons
    You lose variant-level details. For example, all variants are represented by one default product image, which may not match the variant purchased but will still be used in the review solicitation email. Similarly, the Checkout Comment modal shows the default (in this case, "master") title and default (again, "master") image rather than a title and image for a specific variant.

Example: One catalog entry for all colors of a t-shirt
In this scenario, the t-shirt's red, green, and blue color variants each has its own SKU in your original catalog: SHIRT83-RED, SHIRT83-GREEN, and SHIRT83-BLUE. To combine these SKUs into a single product listing, use only one entry in the catalog feed for all three variant items. The one entry uses a "master" SKU that represents all colors of the shirt, such as SHIRT83.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.