Product Catalog Specification

Monetate's product catalog specification is loosely based on Google's product data specification.

Catalog Count

You can upload as many product catalogs as you want under a single account as long as they share product IDs (item_group_id) and categories (product_type) across each one. All categories across catalogs within an account must be in the same language. If you share a single tag across multiple domains (for example, multi-brand), then you must supply a single product catalog.

Required Attributes

This table contains all the columns, or attributes, that must appear in a product catalog file that you upload along with the type of data it must contain.

Attribute	Data Type	Example	Description
item_group_id	String	AB-12345_678	Identifier for a group of products that come in different versions; the value of this attribute must match the product ID (PID) passed in your integration Note: The value can only contain a maximum of 50 alphanumeric characters, ampersands, colons, hyphens, underscores, spaces, or periods.
id	String	A2B4_SM	A product's unique identifier; the value of this attribute must match the product SKU if you're passing SKUs in your integration Note: The value can only contain a maximum of 50 alphanumeric characters, ampersands, colons, hyphens, underscores, spaces, or periods.
title	String	Men's Pique Polo Shirt	A product's name, which appears in the recommendations
image_link	String	http://www.example.com/image1.png	The URL for a product's main image
link	String	http://www.example.com/asp/sp.asp?cat=12&id=1030	The URL for a product's landing page
description	String	"Red, 100% cotton, large men's t-shirt"	A product's description
price	Number	15.98	A product's price
product_type	Comma-separated string	"Clothing > Women > Dresses,Clothing > Women > Special Occasion"	The full path of the category to which the product belongs, with a comma separating each category path, if applicable, and a double quotation mark at the beginning and at the end of the entire string to escape it. See Comma Escaping in this documentation for more information. Note: Ensure that you include a meaningful value for this attribute for each product. Passing NULL, Not available, or some other value that isn't the product's category path can cause various Monetate functions that use this data to not perform as you anticipate.

Optional Attributes

This table contains the attributes you can include in addition to the required attributes in a product catalog file that you upload, along with the type of data each optional attribute must contain.

Attribute	Data Type	Example	Description
additional_image_link	String	https://www.example.com/view2.png	The URL for an additional image for a product
adult	Boolean	yes	Indicates if a product contains nudity or sexually suggestive content
age_group	String	infant	A product's target demographic
availability	String	in stock	A product's availability Note: This attribute is required if you're using Personalized Search. If the value for this attribute is preorder or backorder, then you must include the availability_date attribute as well.
availability_date	Datetime	2022-09-30T12:10:45.000145Z	The date a preordered product becomes available for delivery Note: You must include this attribute in any product catalog that you use with the Newest recommendation algorithm. See Recommendation Algorithms for more information.
brand	String	MyBrand	A product's brand name
color	String	red	A product's color
condition	String	refurbished	A product's condition
energy_efficiency_class	String	A+	A product's energy label
expiration_date	Datetime	2022-09-30T12:10:45.000145Z	The date on which a product should stop appearing
gender	String	unisex	A product's target gender
google_product_category	String or number	Furniture > Chairs or 443	The full category path or numerical category ID for a product as defined in the Google product taxonomy Note: Including this attribute and a supported value enables advanced analysis of the product catalog data. If you don't use a Google-defined value, then it's ignored. See Google's definition of this attribute for the supported values.
is_bundle	Boolean	yes	Indicates if a product contains multiple different products featuring one main product
loyalty_points	String	100	The number and type of loyalty points a customer receives when buying a product
material	String	silk	A product's fabric or material
mobile_link	String	https://m.example.com/23/id=0312	A product's mobile-optimized detail page when you have a different URL for mobile and desktop traffic
mpn	String	MO12345NETATE	A product's manufacturer part number (MPN) as assigned by a manufacturer
multipack	Number	6	The number of identical products sold within a multipack
pattern	String	striped	A product's pattern or graphic print
promotion_id	String	BOGO22	An identifier that allows to you match products to promotions
quantity	Number	42	The inventory count of a product
sale_price	Number	14.49	A product's sale price
sale_price_effective_date_begin	Datetime	2022-09-30T12:10:45.000145Z	The date on which a product's sale price, defined in sale_price, starts
sale_price_effective_date_end	Datetime	2022-10-30T12:10:45.000145Z	The date on which a product's sale price, defined in sale_price, ends
shipping	String	5.99	A product's shipping cost
shipping_label	String	perishable	A label assigned to a product for calculating shipping costs
shipping_height	String	20 in	A product's height used to calculate the shipping cost by dimensional weight, as measured in inches (in) or centimeters (cm)
shipping_length	String	20 in	A product's length used to calculate the shipping cost by dimensional weight, as measured in inches (in) or centimeters (cm)
shipping_width	String	20 in	A product's width used to calculate the shipping cost by dimensional weight, as measured in inches (in) or centimeters (cm)
shipping_weight	String	3 lb	A product's weight used to calculate the shipping cost by dimensional weight, as measured in imperial units (lb or oz) or metric units (g or kg)
size	String	XL	A product's size
size_type	String	maternity	A product's cut
tax	String	US:CA:5.75:y	A product's sales tax rate in percent (5.75), with the optional subattributes of country (US), region or state (CA or postal code, or Boolean value of tax charged on shipping (y) appended using a colon between each

Custom Fields

You can include data not defined in the Monetate product catalog specification. For example, you may want to send additional data to enhance recommendation strategies with different filters or to render recommendations with additional information, such as ratings. You can submit this data by including custom fields, or columns, in a product catalog file.

You must define each custom field and the type of data it contains when you create the product catalog dataset schema.

You can use comma-separated values in a custom field by selecting Comma Separated String for the field when creating the schema. Monetate then considers the value within the field as a list of values that are separated by commas. Fields with this data type are subject to additional rules as described in the Escaping Comma-Separated Strings section of this documentation.

Custom Fields in the User Interface

Custom field headers don't appear in the dataset attribute search section of the platform at this time. Custom fields are available when you're setting up recommendations and adding filters.

File Format

A product catalog file must be in the CSV or TSV format.

Each field must have a header.

The file must use UTF-8 character encoding without a byte order mark (BOM).

Download this CSV file to view an example of a product catalog file with all the required attributes: Sample Product Catalog (CSV).

You can use this sample as a template for your own product catalog files.

Comma Escaping

For a product catalog file to pass validation and for the platform to correctly parse a value that contains a comma and to correctly parse comma-separated strings, you must use comma escaping, which involves using sets of double quotation marks to define individual values. You must also escape quotation marks that are natively part of a value.

Escaping Single Values

If a value for an attribute includes a comma, then you must escape the comma in that value by placing a double quotation mark (") at the beginning of the value and a double quotation mark at the end. The quotation marks are necessary to signal that the comma within the value is not a separator.

Consider this example. A CSV file contains the value Philadelphia, PA for an attribute, but that value isn't contained—escaped—within opening and closing double quotation mark. When the file is processed, Philadelphia is treated as one value and PA is treated as another. Therefore, the correct way to submit the value is "Philadelphia, PA".

If a value contains double quotation marks that are natively part of the value, then you must place the entire value in a set of double quotation marks and escape each quotation mark inside the value by doubling it. For example, a product's description is Feed Me Right "Meow" ceramic cat food bowl. When you submit this information as a value in the description attribute, you must put the entire text in double quotation mark, and then double the quotation mark that are inside the value: "Feed Me Right ""Meow"" ceramic cat food bowl". If you don't escape the quotation marks within the description and escape the entire description, then the value won't parse correctly.

Escaping Comma-Separated Strings

When Monetate processes a CSV file, it parses the data twice. In the first round, it separates the file into cells. In the second round, it separates cells marked as containing comma-separated strings into subvalues. For this reason, you must put two sets of quotation marks around a value that contains a comma when it's in a comma-separated string and then put the full string in quotation marks.

Consider this example. A retailer defines a product with the following three product types:

• Office Supplies > Mailing, Packing & Shipping > Packing Materials > Packing Papers
• Bulk Products
• Seasonal Discounted Offerings > December Discounts

For Monetate to correctly interpret the three product types in this comma-separated string, the retailer must do the following:

1. Place two sets of quotation marks around the first product type: ""Office Supplies > Mailing, Packing & Shipping > Packing Materials > Packing Papers""
2. Put the entire string in quotation marks so it's considered one value: """Office Supplies > Mailing, Packing & Shipping > Packing Materials > Packing Papers"",Bulk Products,Seasonal Discounted Offerings > December Discounts"

Even if only one product type appears in the comma-separated string and it includes a comma, then you must put two sets of quotation marks to signify the presence of the comma and apply a third set of quotation marks around the whole string.

For example, the product type is Office Supplies > Mailing, Packing & Shipping > Packing Materials > Packing Papers. For it to be parsed correctly, the string must appear in the file as follows: """Office Supplies > Mailing, Packing & Shipping > Packing Materials > Packing Papers""".

Escaping Quotation Marks

The same rules apply if the string natively includes one or more double quotation marks. You place two sets of quotation marks around the native quotation mark, and then you place the entire string in quotation marks.

For example, a retailer defines a product with three product types:

• Bulk Powders, Liquids, and Components
• Seasonal Discounted Offerings > December
• 4" Fasteners, Steel

For Monetate to correctly interpret the three product types in this comma-separated string, the retailer must do the following:

1. Place a double quotation mark at the beginning of the entire product_type string and one at the end because the entire string is in a CSV file and contains commas separating each of the three product types: "Bulk Products, Liquids, and Components,Seasonal Discounted Offerings > December,4" Fasteners, Steel".
2. Escape the two product types in the string that natively contain commas by putting two sets of quotation marks around each of the two values: """Bulk Products, Liquids, and Components"",Seasonal Discounted Offerings > December,""4" Fasteners, Steel""".
3. Escape the quotation mark native to the 4" Fasteners, Steel product type: """Bulk Products, Liquids, and Components"",Seasonal Discounted Offerings > December,""4"""" Fasteners, Steel""".

Placed in the context of a CSV file, the product's entry would appear much like this:

id,item_group_id,title,product_type
sku1234,pid2345,"Wood Screws #10 x 4, 100 pcs","""Bulk Products, Liquids, and Components"",Seasonal Discounted Offerings > December,""4"""" Fasteners, Steel"""

If you're unsure if you've escaped native commas and quotation marks appropriately in your final string, "parse" that string as Monetate would.

1. Split the final string into its constituent parts.

   "
   ""Bulk Products, Liquids, and Components"",
   Seasonal Discounted Offerings > December,
   ""4"""" Fasteners, Steel""
   "

2. Remove the outermost enclosing double quotation marks.

   ""Bulk Products, Liquids, and Components"",
   Seasonal Discounted Offerings > December,
   ""4"""" Fasteners, Steel""
   

3. Strip away one "layer" of the escaping by removing one set of quotation marks from any doubled sets of quotation marks.

   "Bulk Products, Liquids, and Components",
   Seasonal Discounted Offerings > December,
   "4"" Fasteners, Steel"
   

4. Repeat the previous step as many times as necessary to strip away each remaining set of double quotation marks until only the original product types remain.

   Bulk Products, Liquids, and Components,
   Seasonal Discounted Offerings > December,
   4" Fasteners, Steel
   

The Monetate platform's parsing rules for comma and quotation marks are the same as the standards set forth in RFC 4180: Common Format and MIME Type for Comma-Separated Values (CSV) Files published by the Internet Engineering Task Force (IETF). Refer to this publication for the exact definitions and standards.

Escaping Values for Updates via the Data API

When updating a product catalog dataset via the Data API, you swap the CSV file for JSON strings. When escaping values in JSON, you use \" in place of the sets of double quotation marks you would use to escape values in a CSV.

Consider the product type example used in Escaping Quotation Marks:

• Bulk Powders, Liquids, and Components
• Seasonal Discounted Offerings > December
• 4" Fasteners, Steel

To update a product catalog with these three values for one product, the JSON string would be as follows:

{
  ...
  "product_type": "\"Bulk Products, Liquids, and Components\",Seasonal Discounted Offerings > December,\"4\"\" Fasteners, Steel\""
  ...
}

Refer to the Data API reference in the Monetate Developer Hub for more information about updating a product catalog using this option.