Configuring Product Catalog

Overview

Connecting an up-to-date product catalog allows you to find and tag content with your own products, making it shoppable across different experiences like Like2Buy, Showroom, Reveal, and Galleries. You can connect your catalog through an eCommerce platform provider like Shopify or provide access to a catalog in one of the common supported formats like a Google Product feed.

Custom catalog formats are also supported for eligible tiers. They will be verified by our technical team and are subject to an additional cost.

If you are on Shopify, you can connect your feed easiest using our API integration. For that skip to the corresponding guide:

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.

CATALOG SETUP

This section will walk through supported catalog format and required fields and catalog localization requirements for any custom product catalogs.

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 Community 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

FieldRequiredTypeDescription
titleyesstringProduct name.
idyesstringUnique 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 idyesstringIdentifier for a collection of products on a Product page, typically this is your Bazaarvoice Product ID.
linkyesstringLink 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_linkyesstringLink to an image of the product. Must be a valid URL. Prefer the best quality image available.
GTINyesstringGlobal 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 Community for more information.

FieldRequiredTypeDescription
item_group_idno (but highly encouraged)stringUnique identifier to group product variants. Use this field to group products that vary by dimensions like size, color, material, etc.
colorno (but highly encouraged)stringColor of your product.

Note: this is one field used to group products. See here for more details on style.
sizeno (but encouraged)stringSize of your product.
materialno (but encouraged)stringMaterial of your product.

Note: this is one field used to group products. See here for more details on style.
priceno (but encouraged)stringPrice of the product, including the currency.

Recommended format is " ".

Examples: "12.34 USD", "15.00 GBP"
product_typeno (but encouraged)stringUse 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.
gendernostringThe gender for which your product is intended.
descriptionnostringShort 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.

Connect Your Product Catalog

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 OptionRequirements
URL HTTP / HTTPS LinkProvide a static link to download your product catalog (cannot redirect to another URL).
FTP and SFTPYou 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.


What’s Next

Please check out the errors and FAQs for catalog configuration on the following link.