Text feed file

You can provide your catalog data using a text feed. These are files, commonly referred to as CSV or flat files, where a delimiter such as a comma, tab, or pipe separates each data column. The primary benefit of this product feed type is that it is relatively easy for clients with smaller catalogs to manually create. However, there are also several limitations, which are described in the following section.

When to use a text feed for product catalogs

Bazaarvoice supports receiving catalog data in a text file. Though this format can be used to provide the main catalog feed, Bazaarvoice recommends that you use the text format for supplemental feed files only because the text format has the following limitations:

• Lack of localization—You cannot provide localized catalog attributes such as product name, category name, and URLs.
• Simple category hierarchy—Though the text format supports category information, only non-localized category names can be provided in a text file. Unique category identifiers cannot be sent to Bazaarvoice in a text file; if they are, downstream issues may occur if category names change over time for any reason.
• Strict limitations on field values—You must adhere to the following rules when creating a text feed:
  • Do not include instances of a delimiter (commas, pipes, or tabs) within the field values, such as Name or Description.
  • Do not use double-quotes around field values.
  • Avoid including leading and trailing spaces in field values because they will be included with the value when stored in the Bazaarvoice database.

If any of these limitations apply, consider using an XML feed instead.

Create a text product catalog feed

Complete the steps in this section to provide catalog data to Bazaarvoice in the form of a text file.

Step 1: Create and format the text file

Watch this video to learn how to create a product feed file (.txt) using Microsoft Excel. If you require a descriptive transcript for this video, you can access this directly in our Wistia platform. 

The following sections detail the exact specifications of the Bazaarvoice text feed file.

File attributes

The file must be formatted as follows:

File Attribute	Description
Header	It must appear as the first line in the file and start with `//`. This line specifies the value(s) for catalog import processing modes. See the Catalog Import Modes table for a list of processing modes and their corresponding values. Include a header for specific scenarios when using multiple catalog sources, such as when using a text file or flat file  as your main feed in conjunction with multiple catalog feed sources. Here is an example: //catalogMode=COMPLETE
Delimiter	Use one of the following delimiters to separate columns: Comma Pipe (I) Tab
Column Header Row	Required to describe the values provided in the file. The file must include at least two columns. Refer to Column definitions for a list of headers and values that can be included in the file.
File extension	You can use any file extension when naming the feed file because Bazaarvoice automatically detects the file type. However, Bazaarvoice recommends using common extensions, such as .csv, .tsv, or .txt.  Note: File extensions are not case sensitive.

Catalog import modes

The following catalog import processing modes describe how the catalog import process consumes catalog data from catalog sources such as product feeds. The following table summarizes the logic for each value of each Catalog import mode.

Default catalog processing modes

Columns definitions

The following columns are supported in the text file. Note that column names are not case sensitive.

Column Name	Value	Required
ExternalId	Unique product ID that can contain only alphanumeric characters, hyphens (-), and underscores (_). If the external product ID contains an invalid character, replace it with an alternate character, such as an underscore. The ID is case insensitive, so you cannot use IDs that match except for case. This format is used in the data feed only and is not visible to end users.	Yes
Name	Name of the product, which is visible to end users.	No
Description	Description of the product. A description is only used within the optional Facebook Ratings & Reviews or Questions & Answers app. Bazaarvoice recommends that product descriptions be at least three sentences or 300 characters long.	No
Brand	The name of the brand to which the product belongs. Note: If BrandExternalId is not specified in addition to Brand, a brand external ID is created even if a brand external ID was specified in a feed or created in the past.	Recommended
BrandExternalId	ID of the brand to which the product belongs.	Recommended
Category	The product's category name. You can associate each product with a single parent product category entity in your product catalog. The maximum allowed category depth is 20 levels. A single category cannot have a chain of parent-to-child relationships that exceeds a total hierarchy depth of 20.	Recommended
CategoryExternalId	Category ID for the product. Note: If CategoryExternalId is not specified in addition to Category, a category external ID is created even if a category external ID was specified in a feed or created in the past.	Recommended
ProductUrl	Unique, uncorrupted URL for a product page. Do not include extraneous query string parameters that you might use for tracking and partnership codes. If the URL contains a reserved (special) character, you must URL-encode the character. For example, use &amp for an ampersand, use %20 for a space, or use %5B and %5D for square brackets ([ ]).	Yes
ImageUrl	Unique URL for the product image. The optimal but slightly flexible display size is 600 x 600 pixels. If the URL contains a reserved (special) character, you must URL-encode the character. For example, use &amp for an ampersand, use %20 for a space, or use %5B and %5D for square brackets ([ ]). Note: If Ratings & Reviews is deployed on an HTTPS site, you must provide image URLs at an HTTPS location in your product catalog. If you do not, your customers will see a mixed content warning.	Yes
ModelNumber	Unique referencing code that businesses use to identify a part that a particular industry uses. Each model number can contain letters, numerals, and other characters.	No; if included, one per product
ManufacturerPartNumber	Manufacturer-specific part number (MPN). Part numbers can contain letters, numerals, and characters.	Recommended
EAN	European Article Numbers (EAN), which is used worldwide for marking retail goods. An EAN must be a string of eight numerals or 13 numerals (no letters or other characters are allowed). Remove spaces and hyphens because they disrupt syndication matching. Note: Bazaarvoice does not enforce length or numerical constraints on EANs. Values are validated during the catalog import process, however, and only valid values are stored.	Either EANs, UPCs, or ISBNs is required. If included, you can specify an unlimited number of child elements. Syndication matching improves if you specify multiple values.
UPC	Universal Product Code (UPC), which is a 6- or 12-digit bar code used for standard retail packaging in the United States. A UPC can contain numerals only, with no letters or other characters. Remove spaces and hyphens because they disrupt syndication matching. Note: Bazaarvoice does not enforce length or numerical constraints on EANs. Values are validated during the catalog import process, however, and only valid values are stored.	Either EANs, UPCs, or ISBNs is required. If included, you can specify an unlimited number of child elements. Syndication matching improves if you specify multiple values.
ISBN	International Standard Book Number (ISBN), which is a 10- or 13-character value used predominantly for media products such as books, music, and videos. The last character provides a checksum that helps validate the product identifier. Most ISBNs are composed only of digits, except for some 10-character ISBN values that use an X for the checksum.	Either EANs, UPCs, or ISBNs is required. If included, you can specify an unlimited number of child elements. Syndication matching improves if you specify multiple values.
GTIN	Global Trade Item Number (GTIN), which is a globally unique number used to identify trade items, products, or services. Bazaarvoice auto-detects the type of value provided in the GTIN field and stores it as the appropriate UPC, EAN, or ISBN value in the Bazaarvoice database. Note: The product catalog supports GTINs up to 13 characters. Bazaarvoice does not enforce length or numerical constraints on GTINs. Values are validated during the catalog import process, however, and only valid values are stored.	No
BV_FE_Family	The product family name to which the product belongs. Bazaarvoice recommends that you exclude special characters from product family names.	No
BV_FE_Expand	The product bundle name, to enable a product to display all content about family components on the product bundle's page.	No
Inactive	Marks the product inactive if a yes or true value is specified in this column. Note: If the product does not exist in the database and is marked inactive, it is not added to the database.	No
Custom_<attributeName>	Custom attributes enable you to define additional product-specific information and to report on product-specific information.	No

Character encoding and special characters

Save your file as UTF-8 without a byte order mark (BOM). Accented and special characters break if the file is saved in another encoding, such as Windows-1252 — é becomes é.

Some common causes for special character breaking are:

• Exporting from Excel using "CSV" instead of "CSV UTF-8"
• A source system that defaults to Windows-1252 or ISO-8859-1
• A BOM at the start of the file, which can corrupt the first column header

Do not use HTML entities or escape sequences in delimited files. Write special characters as literal text (Café, not Café) — they are submitted exactly as they appear.

Product attributes with multiple values

If a product has more than one value for an attribute, you should provide all values if possible to maximize the value of the Bazaarvoice network. For example, a shirt may have different SKUs in your catalog system, one for each color or size variant. Bazaarvoice supports multiple values for the following product attributes:

• UPC
• EAN
• ISBN
• GTIN
• ManufacturerPartNumber
• ModelNumber

To provide multiple values for an attribute, you can

• Combine values into a single column and separate the values using spaces. Here is an example:

  ExternalId | UPC  
  
  
  123 | 123000000001         
  
  
  456 | 456000000001 456000000002 456000000003
  
  
  788 | 789000000001 789000000002
  

• Repeat the product in the file, providing a different value on each line. Here is an example:

  ExternalId, UPC
  
  
  123,123000000001
  
  
  456,456000000001
  
  
  456,456000000002
  
  
  789,789000000001
  
  
  789,789000000002
  
  
  789,789000000003
  

Define feed upload type

Each feed file indicates whether it is full or incremental, though this is done differently depending on the feed format:

• XML feed files: Use the incremental attribute in the <Feed> element. Refer to Example feed elements for a sample file. 
• Text feed files: Specify a file header.

Step 2: Upload the feed

Bazaarvoice recommends that you upload an updated product feed whenever changes are made to your product catalog as reflected by your website. It is imperative that you provide Bazaarvoice with matching updates as your product catalog changes on your live site.

Note: If you are attempting to provide product catalog data using multiple sources, contact Bazaarvoice to enable this functionality before uploading the feed file.

Watch this video to learn how to access the Bazaarvoice SFTP server and upload your feed files. If you require a descriptive transcript for this video, you can access this directly in our Wistia platform. 

You can add another 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. If you want to set up this key-based authentication method, contact Bazaarvoice support for information and assistance.

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

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

Be sure to connect to SFTP using port 22. Contact Bazaarvoice Support if you do not know your SFTP credentials or where your data is hosted.

After you upload a product feed to an SFTP server, 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.

Guidelines for uploading text feed files

Although Bazaarvoice accepts flat (CSV or TXT) formats, XML is the preferred format. It supports localization, has a rich category hierarchy configuration, as well as other features.

• Use supplemental feed files to provide updated or missing data from the main XML feed.
• We recommend that you upload supplemental flat files (CSV or TXT) weekly.
• Don’t provide your primary catalog data using a text file (due to its format limitations).

Feed processing timeline

After XML feeds are uploaded, they are processed from 2 AM Central Time (CST: UTC-6 or CDT: UTC-5). Bazaarvoice may not finish importing the feed until later the same day and, even if the feed is updated in good time, syndication to retailers may still take up to one week.

This means that if you have a product launch at 9 AM on Friday but the XML feed is updated at 2 AM the same day, the system may not recognise the product ID in your email list. As a result, emails may fail to send and Write a review links may be broken.

Note: To make sure products are available for the product launch, make sure they’re added to XML feeds 24 hours before you expect to start seeing reviews come in.

Step 3: Check the feed status

After uploading a feed to the staging or production SFTP server, you can view the import summary and error or warning count of the feed. Checking the import summary enables you to correct errors before the next import, so you can ensure you provide a valid feed for the next import.

View the import summary in the Portal for your staging or production server by selecting More > Product Catalog > Feed. If your feed returns an error or warning, select the Import ID for detailed information.

Resolve incomplete feeds

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.

Example text feeds

The following example is a simple comma-separated value (CSV) file that provides supplemental EAN catalog data:

ExternalId, EAN
123,0123000000001
456,0456000000001
456,0456000000002
789,0789000000001
789,0789000000002
789,0789000000003

Here is an example of a CSV file that can be used as the primary feed for product catalog data:

//catalogMode=COMPLETE
ExternalId, UPC    
123,123000000001
456,456000000001
456,456000000002
789,789000000001
789,789000000002
789,789000000003