Configuring Product Catalog

Definitions

Below are some common terms used when describing product catalogs:

• Product – Typically represented by a single Product Details Page (PDP). A product may have multiple options / configurations such as size, color, or material.
• Item / Variant – A specific configuration of a product that has multiple options / variations. This is typically what’s actually purchased. For example, for a shirt that comes in several sizes and colors, the medium red option is a variant.
• Product Feed – Another term used for product catalog.
• Style – Social Commerce’s grouping of product variants that have the same Grouping ID, color, and material. In the Social Commerce dashboard, products appear in the search dropdown for tagging by style.
• Acquire – Used to describe when we download / fetch your catalog file from the location you provide (see section below for options to connect your catalog).
• Availability – Product attribute that says whether or not your product can be purchased right now. Typical values include “in stock,” “out of stock,” and “preorder.”
• Expire – Used to describe what happens when a product is no longer in your catalog file. For example, when you remove a product from your catalog, Social Commerce expires that product so it can no longer be tagged in the dashboard and it will appear as out of stock on any touchpoints.
• Field / Column – Product attributes in your product catalog file. For example, “Title” may be a field or column in your catalog file.
• Group / Grouping – see section below for Item Grouping ID definition.

Supported Schemas and File Formats

We currently support the following product catalog schemas:

• Google product catalog schema (specified here)
• PepperJam/eBay product catalog schema
• Custom schema – may be add’l cost

The Google product catalog schema is Social Commerce’s preferred format because it provides rich data about your products in an easily ingestible format. Not only does it provide the required fields listed below, but the Google product catalog schema also provides many of the optional fields that will let you get the most from the Social Commerce platform.

We support UTF-8 and ASCII-encoded files of the following formats:

1. Comma-Separated Values (.CSV or .TXT)
2. Tab-Separated Values (.TSV or .TXT)
3. Semicolon-Separated Values (.SSV or .TXT)
4. XML, ATOM or RSS type (.XML)
5. Any of the above formats compressed in a zip or gzip file

To download an example product catalog file, please click one of the following links: tab-separated (.txt), ATOM 1.0 (.xml), or RSS 2.0 (.xml).

Your product catalog file (specifically XML) must be flat; we do not accept catalogs with relationships between different elements of the file. Each “product” element must fully contain all its information. For example, when denoting your product categories, you cannot reference a number that is denoted in a ‘categories’ section listed at the end of the file. Additionally, product data cannot be nested and we do not support multiple UPCs per product.

Before you change your schema (such as add or remove color, category, or other fields), please reach out to support@bazaarvoice.com to ensure there is no data loss.

Required and Optional Fields

The fields your product catalog contains are the key to powering your Social Commerce experience. Each field in your product catalog provides more information about each product. You can search against any and all of the fields you provide in your product catalog. Product metadata, like category, powers experiences like Galleries, Showroom, and Intelligent Product Tagging.

Required

Field	Required	Type	Description
title	yes	string	Product name.
id	yes	string	Unique identifier for each product. Use the Product SKU if available. Should match identifier when adding to cart. Must match across localized catalogs (see section below for more details)
external id	yes	string	Identifier for a collection of products on a Product page, typically this is your Bazaarvoice Product ID.
link	yes	string	Link to your site where the product can be purchased (Product Details Page). Must be a valid URL starting with http or https. Prefer direct canonical links, no redirects. Note: you can control the tracking parameters on these URLs from within the Social Commerce app when product tagging content.
image_link	yes	string	Link to an image of the product. Must be a valid url. Prefer best quality image available.
GTIN	yes	string	Global Trade Item Number (GTIN) is the number that uniquely identifies a product. Several different types of ID numbers (including UPC and EAN) are considered a GTIN.  Learn more

 

Optional

These fields are not required, but are highly encouraged. These additional attributes help Social Commerce better understand, group/categorize, and associate your products like you do. This is not an exhaustive list – please reach out to support@bazaarvoice.com for more information.

Field	Required	Type	Description
item_group_id	no (but highly encouraged)	string	Unique identifier to group product variants. Use this field to group products that vary by dimensions like size, color, material, etc.
color	no (but highly encouraged)	string	Color of your product. Note: this is one field used to group products. See section below for more details on style.
size	no (but encouraged)	string	Size of your product.
material	no (but encouraged)	string	Material of your product. Note: this is one field used to group products. See section below for more details on style.
price	no (but encouraged)	string	Price of the product, including the currency. Recommended format is “<amount> <currency code>”. Examples: “12.34 USD”, “15.00 GBP”
product_type	no (but encouraged)	string	Use this field to include a secondary category that contains your own product category classification or to provide a second level of category filtering. This field can also be used for filtering on category snippets
gender	no	string	The gender for which your product is intended.
description	no	string	Short text describing the product. Should match description on Product Details Page (PDP).

Localization Requirements

Social Commerce is able to ingest multiple localized catalogs in addition to a primary “Default Catalog” used for product tagging. Any of your product catalogs can be the primary catalog, but the default catalog cannot be changed after initial setup. When Social Commerce renders the product information on-site, the correct product metadata is pulled from the associated language catalog automatically.

Please note that you cannot have localized catalogs and multiple default catalogs connected simultaneously. We will set a default catalog “i.e. en-US or en-GB”, and the localized catalogs will be matched as long as they have a unique identifier that connects across the locales.

By default, we do not support localization for Shopify feeds. For any discussions of localization, please reach out to your Client Solutions Manager or Account Manager for further custom options.

Requirements for localized catalogs:

• The catalogs’ filename must include the language and country locale (e.g., “productcatalog_en_US.txt”)
• Locale name must match country codes list here (note: United Kingdom is en-GB, and en-EU is not a valid feed locale. You will need to provide a different option from the list above.)
• There needs to be a unique identifier for that product across locales (e.g., in catalog A, product X has the id “1234AC.” In catalog B, product Q has the id “1234AC.” Product X and Q are the same product, but in two different catalogs)
• All products must be listed in the default catalog. If a product is not in the default catalog, it will not be taggable in Social Commerce
• Ensure that all of the items in the default catalog are also in the regional catalog. If you tag an item from the default catalog that isn’t available in the localized catalog, we will display the product from the default catalog. (e.g. if a catalog tagged from en-GB isn’t available in the fr-FR catalog, we will return the en-GB product URL)

URL Crawler

In the Social Commerce dashboard, you can use URLs to product tag media. When you use a URL to tag a piece of media, Social Commerce’s crawler will scrape the HTML of that page to gather information such as title and image. The crawler will also grab the canonical URL and attempt to resolve that to a product in your catalog.

The crawler needs to be able to access the page in order to scrape it for information. Social Commerce’s crawler uses Amazon Web Services or Rackspace which you may have blocked. You can give the crawler access to your site by whitelisting the IP addresses the crawler uses. The IP addresses are:

IPv4: 162.242.254.108
IPv6: 2001:4802:7802:103:be76:4eff:fe20:bba7

Without access, the crawler cannot scrape a URL, so that URL cannot be resolved back to a product in your catalog. In experiences like Showroom, a URL tag will not have any information from your catalog, such as availability, price, or brand. If the URL is not resolved back to a product in your catalog, it will not show up in Galleries.

Options to Connect

Regardless of how you connect your catalog, your catalog must have a static file path. We do not support dynamic file paths, e.g. with dates or numbers appended.

Connection Option	Requirements
URL HTTP / HTTPS Link	Provide a static link to download your product catalog (cannot redirect to another URL).
FTP and SFTP	You must provide the following: hostname of your FTP server (ex. ftp.test.com) username to access your FTP location password

Connecting via Google Docs

If you don’t have access to an FTP/SFTP, or have the ability to generate your own live HTTPS link, you can generate a catalog via Google Docs. Ensure you’ve followed the steps within the catalog setup section and included the required fields. Afterwards, create a public URL in Google Docs using the steps below:

• Using a google doc spreadsheet as a feed is supported, provided the following criteria are fulfilled
• Link sharing must be enabled, and the sheet must be set to “Anyone with the link” can access.
  • To set a sheet to “Anyone with the link,” navigate to the sheet, then click File > Share > Advanced. Under “Who Has Access” click Change, then select “Anyone with the link”
• The feed ingestion URL must be correctly formatted to export as a CSV file and must be published.
  • You can publish by going to File > Publish To The Web, selecting a sheet and .csv, then click Publish.
  • On the next screen, you will be given a URL. This should be used as the ingestion source.

Catalog Update Cadence

By default, product catalogs are updated every 6 hours. If you need to make any adjustments to your catalog refresh time, please reach out to your Client Solutions Managers with any specific details.

Ready to Connect?

If you’re ready to connect your catalog, reach out to your Client Solutions Manager to get started.

Warnings and Errors on the Catalog Health page

The Catalog Health page in the Social Commerce dashboard lets you see important information about your catalog: when your catalog was last successfully acquired, how many products were ingested, and any warnings or errors with your catalog. Below explains the errors you might see, what they mean, and how to fix them:

Error	Description	How to fix
Failure – Could not download	We were unable to access your catalog at the given location. This could be because your catalog file has moved, it was temporarily unavailable, or the file name has changed.	Make sure you can access the file at the location listed on the Catalog Health page. If any details about location or name have changed, or you need further help investigating, please contact support@bazaarvoice.com
Failure – Bad file formatting	Your catalog file has changed formats and we cannot understand it. This could be because your file is missing fields it had before or the file structure is incorrect.	Check your catalog file for any formatting errors. For XML, this may be missing opening or closing tags. For CSV, SSV, or TSV, this may be missing commas, tabs, or spaces it had before. Also ensure none of your fields’ have been removed or renamed. Contact support@bazaarvoice.com if you need help investigating.
Needs Attention	Your catalog contained a large amount of products with errors. Products with errors are not available within Social Commerce and cannot be tagged in the dashboard.	Use the Export Errors button on the Catalog Health page to download a full list of errors and warnings for each problematic product. See the table below for details about each possible error.

 

The Catalog Error Report is a downloadable file from the Catalog Health pages that details each error or warning we encountered when ingesting your product catalog. If a product has an error, it is not available within Social Commerce and cannot be tagged in the dashboard. If a product has a warning, the product is still available in Social Commerce and can be tagged, but it is missing important information that may affect your dashboard or touchpoint experiences:

Name	Type	Description	How to fix
Image – Primary image failed	Error	We were unable to find and/or process the image at the given URL.	Make sure the URL is valid and links to the right product image. If the URL works and the image can be downloaded, contact support@bazaarvoice.com for assistance.
Parsing – Row failed to parse	Error	This row in your catalog file was unable to be parsed. This can be caused by unsupported characters or the XML being malformed (such as missing a closing tag). This error generally happens when the file has been corrupted.	Check your catalog file to see if it has been corrupted. If the file seems correct, look at the XML and see if there are missing tags. For more information about unsupported characters in XML, see this StackOverflow thread. For further assistance, contact support@bazaarvoice.com.
Required Field – Missing	Error	One of the required fields was missing for this product.	Check to see if the item in question has all the required fields. Some required fields may be mapped from other fields in your product catalog by the Social Commerce Support team when they setup your catalog. Contact support@bazaarvoice.com if any field names have changed or for further assistance.
Unknown Error	Error	An error occurred during processing.	Contact support@bazaarvoice.com for further assistance.
Image – Primary image skipped	Warning	This image was skipped because it doesn’t look like it includes a product. We may have determined this is a placeholder image for many products or a result of rate-limiting our service, such as a CAPTCHA image.	Make sure the URL is valid and links to the right product image. Contact support@bazaarvoice.com for further assistance.
Image – Extra image failed	Warning	Similar to “Image – Primary image failed,” we were unable to find and/or process an additional image for this product at the given URL.	Make sure the URL is valid and links to the right product image. If the URL works and the image can be downloaded, contact support@bazaarvoice.com for assistance.
External Item ID – Missing	Warning	This item is missing an external item ID. This is the unique ID your company uses to identify this product (may also be referred to as SKU). Missing this ID may impact this item’s availability in your touchpoint experiences, specifically PDP Galleries.	Make sure this item has all the required fields. Contact support@bazaarvoice.com for further assistance.
Group ID – Missing	Warning	Your catalog was not setup with grouping IDs or is now missing them. For more information about grouping ID, see section above	Ensure that none of your field names have changed or been removed. Contact support@bazaarvoice.com for further assistance.
Item URL – Crawling failed	Warning	We were unable to crawl the given product URL to get necessary information. THis could be due to your site flagging Social Commerce as a bot (and blocking it), or the URL is invalid. For more information about crawling URLs, see section above	If your domain is flagging Social Commerce as a bot, see section above for more information. Contact support@bazaarvoice.com for further assistance.

 

Can't find products when tagging

• Check the file you’re pushing to Social Commerce (via a delivery method above) to make sure the product is included there
• Ensure the product has all required fields (id, title, description, URL, image URL)
• Ensure URLs lead to working webpages
• If your file contains your product and all required fields, please reach out to support@bazaarvoice.com for assistance
• Check the Catalog Health page to ensure your catalog is up-to-date, has processed recently, and doesn’t have any errors. If your catalog has errors, click Export Errors to get a report explaining which products failed and why. If your catalog is healthy and you can’t find the product, reach out to support@bazaarvoice.com for assistance.

Products grouped incorrectly when tagging

• Social Commerce groups product variants together by their Grouping ID, color, and material into a style. If a set of products has the same values for these attributes, they will be grouped into the same style
• Products appear in the search dropdown for tagging by style. If you make a change to your product catalog schema, such as adding or removing color, material, or other product field, the style of products changes. This can affect how products are grouped when tagging
• If you need to make modifications to how your products appear when searching, please reach out to support@bazaarvoice.com to ensure a clean transition

How often does Social Commerce pull my catalog file?

By default, Social Commerce updates your catalog every 6 hours.

My product is no longer available (out of stock, out of season, unavailable, etc.). How should I update my product catalog?

• “Out of Stock” products should be kept in your catalog if they will be purchasable at some point again. Use the availability field (or equivalent in your product catalog) to denote out-of-stock. Products marked out of stock are still taggable in the dashboard.
• When you remove a product from your catalog, Social Commerce expires that product and removes it from being taggable in our webapp. When you put a previously-expired item back in your catalog, it will be made available for product tagging and show up in on-site and off-site experiences.

I want to make changes to my products... what now?

• If you need to update any fields which make up a style (like Grouping ID, color, or material) or you need to make schema changes, please reach out to support@bazaarvoice.com for assistance. This will ensure a smooth transition of your products in Social Commerce’s systems
• If you use an on-site gallery and change the “external ID” for your products, please contact support@bazaarvoice.com to ensure that we update and map your catalog appropriately
• For all other product changes (titles, URLs, availability, etc), simply update the product catalog file you send Social Commerce with the new information and the product information will be automatically updated

Why do I get a "There are no product recommendations" warning when creating a Showroom?

• Recommendations in Showroom are powered by the products you’ve tagged in a piece of media with your product catalog. If you only have URL tags and haven’t tagged using your product catalog, you won’t get any product recommendations. Learn more about how to productize an image
• If you are a Trending Products customer and only use URL tags, you will see trending products in Showroom instead of product recommendations. Filters are not available for trending products.

How do I enable filters for Showroom?

• Showroom filters are based on the information provided in your product catalog.
• To filter by brand, the products tagged must have the brand information provided in your product catalog. You will then be able to filter Showroom to any of the brands of products tagged in that piece of media.
• To filter by products with a sale price, you must have price and sale price available in your catalog and any one product must qualify as on sale (where sale price is less than price for that given item). You can use the on sale filter in any Showroom, even if the products tagged in the media you are using to create your Showroom are not discounted/marked on sale.

How do I connect my catalog if I'm using an eCommerce platform like Shopify or Magento?

We support automatic catalog ingestion through Shopify in the dashboard (for a single store only). If you use Shopify, please review our catalog connection guides:
https://support.bazaarvoice.com/s/article/Setting-up-a-Product-Catalog-via-Shopify?language=en_US