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:

Shopify catalog connection 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:

Comma-Separated Values (.CSV or .TXT)
Tab-Separated Values (.TSV or .TXT)
Semicolon-Separated Values (.SSV or .TXT)
XML, ATOM or RSS type (.XML)
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

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 the 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 Community 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 here 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 here for more details on style.
price	no (but encouraged)	string	Price of the product, including the currency. Recommended format is " ". 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.

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