Product catalog feed

Produc<span class="dxhe-searchHI">c</span>atalog feed

This product catalog feed is used to map Bazaarvoice user-generated content such as reviews and ratings to your relevant products and categories.

Bazaarvoice accepts the following feed file formats:

  • XML (recommended) - The XML product catalog feed must follow a specific structure. Use the Product Feed Generator tool as a starting point for creating your XML-based product catalog feed. Refer to the instructions below.

  • CSV or TXT - If creating an XML feed is difficult, you can send your catalog feed in a flat file format (CSV or TXT). However, these formats are only supported for single-locale implementations.

    Note
     If you are using the TXT format, always validate it with the Engagement Manager.

Why is product catalog data so important?

The product catalog feed powers the following:

  • Content—Review requests (formerly post-interaction email or PIE), notifications, and review submission pages must pull in content such as IDs, names, URLs of brands, categories, and product information.
  • Syndication—Because retailers and brands often use different identifiers and metadata to describe the same product, an accurate product catalog enables Bazaarvoice to match products offered by brands and retailers, and then share or "syndicate" user-generated content (UGC) based on product matches.
  • Reports and Insights—the quality of data available from your product catalog directly impacts generated and . Make sure your product catalog is up-to-date. Refer to Integration health for more information.

Product catalog data

Bazaarvoice supports the following ways to provide your product catalog data:

  • XML-based feed file—Provide a single structured XML based feed that includes all of your catalog data. The majority of PRR clients currently provide catalog data via a single XML based feed file.

    Note
     Bazaarvoice accepts flat file formats like CSV and TXT as alternatives to XML feeds. If you are using the TXT format, always validate it with the Engagement Manager.

  • Dynamic Catalog Collection (DCC)—Enables Bazaarvoice to collect and consume product catalog data using JavaScript tag placed on your product display pages. When shoppers visit a product display page, the JavaScript event automatically passes catalog data to Bazaarvoice for consumption.

Implement XML feed step-by-step instructions

Complete the following steps to create an XML feed and upload it to Bazaarvoice:

Step 1: Create an XML product feed

Step 2: Check the elements and attributes

Step 3: Validate product feeds

Step 4: Upload product feeds

Step 5: Check the feed status

Step 6 : Send incremental XML feeds (Recommended)

Step 1: Create an XML product feed

Your technical team must provide Bazaarvoice with an XML based, production-ready data feed of your products and product categories. The XML product catalog feed must follow a specific structure.

Structure your product catalog feed

Use the Product Feed Generator tool as a starting point for creating your outline product catalog feed. You can copy and paste the markup from the generator to your text editor.

  • Check the feed to make sure that the first line of your feed adheres to the following format:

    Copy Code
    Code
    <?xml version="1.0" encoding="utf-8"?>

    The standard character-encoding scheme, such as UTF-8 or Windows-1252, must match the scheme that you use for any special characters in the feed.

  • Check that your XML-based product catalog feed begins with a root node of Feed. For example:

    Copy Code
    Code
    <Feed xmlns="http://www.bazaarvoice.com/xs/PRR/ProductFeed/14.7" name="CLIENT" incremental="false" extractDate="2019-11-04T00:00:00">


    Attribute Value
    xmlns http://www.bazaarvoice.com/xs/PRR/ProductFeed/14.7. This is product feed XML schema you use to define the structure of your feed.
    name Client name which is the name of your company (for example, looneytunes)
    incremental If you are sending a data feed that contains your entire product catalog, set this value to false.

    If the number of products in your catalog exceeds 750,000, set this value to true and send incremental feeds with no more than 750,000 products in each feed.

    extractDate Populate this value automatically with a timestamp that identifies the date and time at which the data that constitutes the feed was extracted from your database. This value must be presented in XML's dateTime format.

  • The XML product catalog feed must follow a specific structure. Use this product feed XML schema to define the detailed structure and contents of your feed.

    Note
    Version 14.3+ of the schema does not enforce length or numerical constraints on UPCs, EANs, and ISBNs. Any string in one of these fields is treated as valid by the product schema. Values in the UPC, EAN, and ISBN fields are validated during the catalog import process, however, and only valid values are stored.
Caution
If you don't have a value for a particular field, delete the field from your feed. Having blank fields will prevent your feed from being imported.

Example XML product catalog feed

The following example shows the general structure of a product catalog feed.

Copy Code
XML
<?xml version="1.0" encoding="utf-8"?> 
<Feed xmlns="http://www.bazaarvoice.com/xs/PRR/ProductFeed/14.7" name="CLIENT" incremental="false" extractDate="2019-11-04T00:00:00.000000">
        <Brands>
            <Brand>...</Brand>
        </Brands>
        <Categories>
            <Category>...</Category>
        </Categories>
        <Products>
            <Product>...</Product>
        </Products>
    </Feed>
  • Categories, brands, and their associated content appear as children elements under the Feed element and within parent Categories and Brands elements, respectively.
  • Each product in the product catalog features its own Product element within a parent Products element under the root Feed.
  • Product-related metadata like ProductPageUrl appears as children elements under the appropriate product.
Tip
Refer to this detailed XML product catalog example file. It shows the feed structure and the complete syntax for all globally unique identifiers required by Bazaarvoice.

Step 2: Check the elements and attributes

You must use the appropriate elements and attributes to describe your feed, brand, category, and product information. Refer to the following tables for child elements and attributes for Feed, Brand, Category, and Product elements.

Attributes associated with the 'Feed' element

The following table identifies the attributes that are associated with a data feed's required, top-level Feed element (also described in previous section).

Attribute Value
xmlns http://www.bazaarvoice.com/xs/PRR/ProductFeed/14.7
name Client name which is the name of your company.
incremental If you are sending a data feed that contains your entire product catalog, set this value to false.

If the number of products in your catalog exceeds 750,000, set this value to true and send incremental feeds with no more than 750,000 products in each feed.

extractDate Populate this value automatically with a timestamp that identifies the date and time at which the data that constitutes the feed was extracted from your database. This value must be presented in XML's dateTime format.


Caution
Important: The casing provided for the <ExternalId>  element in the product catalog cannot be modified once it is set. Clients consuming catalog data from Content Exports feed are advised to implement a case-insensitive ingestion process to maintain consistency 

Children elements associated with the 'Brand' element

The following table identifies the required children elements that are associated with a data feed's Brand element.

Element Value
ExternalId

Unique brand ID, which is not case-sensitive.

  • It can contain only alphanumeric characters and the following special characters: asterisk (*), hyphen (-), period (.), and underscore (_).
  • If your brand IDs contain invalid characters, replace them with an alternate character, such as an underscore.
  • This format is used in the data feed only and is not surfaced to end users.
  • Ensure that the ID is a stable ID that will not change for the same logical brand, even if the name of the brand changes.
Name Name of the brand; visible to end users.

Children elements associated with the 'Category' element

The category structure in your data feed affects several aspects of your Bazaarvoice implementation. Tags can be assigned to categories, which allow contributors to highlight specific product attributes when submitting content.

For example, an electronics retailer could create the following tags for the "headphones" product category: perfect fit, poor fit, stylish, good sound quality, and poor sound quality.

The tags appear as check boxes on the content submission form and can also appear on product category or product display pages. A reviewer can select the appropriate tags when submitting content, and shoppers can filter products within a category to see only the ones where ratings include the matching tags.

Categories also populate the category picker, which impacts how people at your organization can filter user-generated content in reports, etc. For example, a well-defined category structure can help a Merchandiser see reviews only for the product categories they care about.

Avoid using false categories like Sale because they do not truly categorize products.

The following table identifies the children elements that are associated with a data feed's Category element.

Element Value Required
Name Name of the category or subcategory; visible to end users. Yes
ExternalId

Unique category or subcategory ID, which is not case-sensitive.

  • It can contain only alphanumeric characters and the following special characters: asterisk (*), hyphen (-), period (.), and underscore (_).
  • If your category IDs contain invalid characters, replace them with an alternate character, such as an underscore.
  • This format is used in the data feed only and is not surfaced to end users.
  • Ensure that the ID is a stable ID that will not change for the same logical category, even if the name of the category changes.
Yes
CategoryPageUrl Unique, uncorrupted URL for the category or subcategory. Do not include extraneous query string parameters that you might use for tracking and partnership codes. Yes
CategoryPageUrls

Contains a <CategoryPageUrl> element for each locale in a multilingual implementation. Each <CategoryPageUrl> element features a locale attribute of type String.

No
ParentExternalId Parent category's ID of the subcategory in question. No
ImageUrl URL for the category image, which is usually hosted on your website or a content delivery network (CDN). Spaces are not allowed in the ImageURL node. No
ImageUrls

Contains an <ImageUrl> element for each locale in a multilingual implementation. Each <ImageUrl> element features a locale attribute of type String.

No

Children elements associated with the 'Product' element

The following table identifies common children elements that are associated with a data feed's Product element. For a complete list of available elements, consult the data feed schema.

Element Value Required
ExternalId

Unique and not case-sensitive.

  • Product family-level ID that can contain only alphanumeric characters and the following special characters: asterisk (*), hyphen (-), period (.), and underscore (_).
  • If your product IDs contain invalid characters, replace them with an alternate character, such as an underscore. If a product has its own page, that page is the product ID.
  • The product ID is not necessarily the stock keeping unit (SKU) ID, as Bazaarvoice does not collect separate content for different styles of product.
  • This format is used in the data feed only and is not surfaced to end users.
Yes
Name Name of the product; visible to end users. Yes
CategoryExternalId Category ID or subcategory ID within your store catalog to which the product belongs. Yes
ProductPageUrl Unique, uncorrupted URL for the product page. Do not include extraneous query string parameters that you might use for tracking and partnership codes. Yes
ImageUrl Unique URL for the product image. The optimal but slightly flexible display size is 100 pixels x 100 pixels. Thumbnail images are recommended. Spaces are not allowed in the ImageURL node. Yes
EANs Contains at least one child <EAN> element. No, unless including <EAN> elements
EAN European Article Number, which is used worldwide for marking retail goods; can be a string of digits either 8 or 13 characters long. No
ManufacturerPartNumbers Contains at least one child <ManufacturerPartNumber> element. No, unless including <ManufacturerPartNumber> elements
ManufacturerPartNumber Manufacturer-specific part number that can contain letters, numerals, and characters. No
UPCs Contains at least one child <UPC> element. No, unless including <UPC> elements
UPC Universal Product Code, which is the 6- or 12-digit bar code used for standard retail packaging in the United States. The UPC must contain numerals only, with no letters or characters. Further, spaces and hyphens disrupt syndication matching and must be removed. No
ISBNs Contains at least one child <ISBN> element. No, unless including <ISBN> elements
ISBN International Standard Book Number, which is a unique identifier for books and which is intended for commercial use. The number is either 10 or 13 digits long and consists of four or five parts. The different sections of the number can be of different lengths and are usually separated by hyphens (-) or tildes (~). Spaces and hyphens disrupt syndication matching and must be removed. No
Names

Contains a child <Name> element for each locale in a multilingual implementation. Each <Name> element features a locale attribute of type String.

No
Description Description of the product. To help products with few or short reviews contribute a significant amount of content to the SEO-optimized landing pages, it is recommended that product descriptions be at least three sentences or 300 characters in length. If you store descriptive information about your products across multiple elements, concatenate your elements into the Description element.

No HTML elements are recognized within the Description element.

No
Descriptions

Contains a child <Description> element for each locale in a multilingual implementation. Each <Description> element features a locale attribute of type String.

No
BrandExternalId Brand ID of the product. No
ProductPageUrls

Contains a child <ProductPageUrl> element for each locale in a multilingual implementation. Each <ProductPageUrl> element features a locale attribute of type String.

No
ImageUrls

Contains a <ImageUrl> element for each locale in a multilingual implementation. Each <ImageUrl> element features a locale attribute of type String.

No
ModelNumber Unique referencing code that businesses use to identify a part that a particular industry uses. The model number can contain letters, numerals, and other characters. No

If an element is not required but you maintain it for your products, include it in the data feed.

Step 3: Validate product feeds

Your feed needs well-formed XML that works with the following Bazaarvoice XML schema:

http://www.bazaarvoice.com/xs/PRR/ProductFeed/14.7

Validate your feed against the schema before uploading it to Bazaarvoice using a feed validation tool. There are a number of free feed validation tools available online, for example, XMLBeans.

The feed validation tool will help you to view the following information:

  • Import status
  • Errors and warnings related to data feeds that you have dropped into the /import-inbox directory and that have been processed by the automatic importer
  • Ad-hoc imports on staging that use the "Invoke one-time import" link. These need to be removed.

Step 4: Upload product feeds

Bazaarvoice recommends updating your product catalog feed daily to reflect any changes made to your product catalog.

Note
Bazaarvoice also recommends you upload it to the SFTP location that stores the feed until it's picked up by Bazaarvoice's automatic import process.
Add an extra level of security to your data by supplying a public **Secure Socket Shell (SSH)** key using SSH passwordless entry. This process relies on a private key that resides with you, paired with a public key used by a Bazaarvoice SFTP server.

Contact Bazaarvoice Support if you want to set up this key-based authentication method.

Before you go live

Upload your feed to the /import-inbox directory on the SFTP staging server .

Note
Once uploaded, Bazaarvoice automatically begins importing the feed at 2 AM Central Time (CST: UTC-6 or CDT: UTC-5). Although Bazaarvoice may not finish importing your feed until later the same day due to the import process!

You can also trigger an import manually. Complete the following steps to manually import the feed:

  1. Sign in to the Bazaarvoice Portal.
    If you can't sign in, contact     Bazaarvoice Support for assistance. Learn more about Portal permissions and user accounts.
  2. From the navigation bar, select More > Product Catalog.
  3. Select the Feed tab.
  4. Your product feed is validated as part of the import process in the Bazaarvoice Portal.
    • To view a summary of your product feed validation, select the Validate Product Feed tab. A summary of the 10 most recent feed import attempts is displayed.
    • To view any associated errors and warnings, select the Import ID. This allows you review these issues and their effects in more detail.​

  5. If you want to view products from your catalog that are receiving content but not appearing in your catalog feed, select the Incomplete Feeds tab. These products aren’t appearing in your feed as they were added after you formed your main feed, for example, as part of a sampling campaign. To make these products appear in your feed, update and reupload it in the Bazaarvoice Portal.

After you go live

Upload your feed to the /import-inbox directory on the SFTP production server .

Note
Bazaarvoice's production feed import process automatically picks up files in this folder on a nightly basis.

You cannot manually trigger an import to the production server.

SFTP connection values

Upload the XML feed file to the /import-inbox directory of the SFTP server.

  • If your data is hosted in the US, use the following URLs:
    • Staging server: sftp-stg.bazaarvoice.com
    • Production server sftp.bazaarvoice.com
  • If your data is hosted in Europe, use the following URLs:
    • Staging server sftp7-stg.bazaarvoice.com
    • Production server sftp7.bazaarvoice.com

Step 5: Check the feed status

After uploading a feed to the SFTP server, you can view the import summary (error or warning count) of the feed.

Checking the import summary helps you to correct errors before the next import.

To view the import summary

  1. Sign in to the Bazaarvoice Portal.
    If you can't sign in, contact Bazaarvoice Support for assistance. Learn more about Portal permissions and user accounts.
  2. From the navigation bar, select More > Product Catalog.
  3. Select the Feed tab.

  4. Select the Incomplete Feeds tab to view products from your catalog that are receiving content but not appearing in your catalog feed. These products aren’t appearing in your feed as they were added after you formed your main feed, for example, as part of a sampling campaign. To make these products appear in your feed, update and reupload it in the Bazaarvoice Portal.

Note
You should upload only well-formed feeds to the server. In the Validate Product Feed page, select the Import ID  to view any associated errors and warnings, This allows you review these issues and their effects in more detail.

Step 6: Send incremental product feeds (Recommended) 

To ensure the fastest updates to your catalog, use incremental feeds along with periodic full feeds. It is not recommended to submit a full feed regularly, as it significantly increases your system load, along with network traffic and import time. If you need to upload a daily feed, consider the recommended approach: Incremental XML feed files.

To reduce file size, you can send incremental feeds that include newly added and updated products, categories, and brands, including items that have been removed.

Incremental feeds differ from standard XML feeds in the following ways:

  • The root Feed element contains an incremental attribute that is set to true
  • The removed attribute that is associated with the applicable Product, Category, and Brand elements is set to true

The following example shows an incremental product feed.

Copy Code
XML
<Feed name="ExampleClient" incremental="true" extractDate="2019-08-31T08:02:00-05:00">
    <Categories>
        <Category>
            <ExternalId>1-8</ExternalId>
            <Name> How my pet makes me a champion </Name>
            <ParentExternalId>1-16</ParentExternalId>
            <CategoryPageUrl>
            http://www.client.com/Content/ContentNoNAV.aspx?PC=heartofchampion
            </CategoryPageUrl>
        </Category>
        <Category>
            <ExternalId>1-9</ExternalId>
            <Name> Why my pet is a champion </Name>
            <ParentExternalId>1-16</ParentExternalId>
            <CategoryPageUrl>
            http://www.client.com/Content/ContentNoNAV.aspx?PC=heartofchampion
            </CategoryPageUrl>
        </Category>
        <Category removed="true">
            <ExternalId>1-6</ExternalId>
            <Name> Naughty </Name>
            <CategoryPageUrl>
            http://www.client.com/Content/ContentNoNAV.aspx?PC=naughtynicecontest
            </CategoryPageUrl>
        </Category>
        <Category removed="true">
            <ExternalId>1-7</ExternalId>
            <Name> Nice </Name>
            <CategoryPageUrl>
            http://www.client.com/Content/ContentNoNAV.aspx?PC=naughtynicecontest
            </CategoryPageUrl>
        </Category>
    </Categories>
</Feed>

In this example, the following element defines the feed as an incremental product feed:

<Feed name="ExampleClient" incremental="true" extractDate="2019-08-31T08:02:00-05:00”>

Further, the following element specifies the removal of the relevant category:

<Category removed="true">

Example feeds

To assist with your implementation, refer to Bazaarvoice's Ratings & Reviews knowledge base for the following example feeds and formats: