Implement a Product Catalog

A product catalog is required for Monetate's recommendations and badging add-ons. Uploading a product catalog has the added benefit of allowing you to target products in the WHO settings of an experience by hierarchy, category, or product attribute that you've specified within the product catalog. Monetate highly recommends that you implement a product catalog because doing so unlocks additional capabilities within the platform.

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

Uploading a Product Catalog

You can upload a product catalog three ways to the Monetate platform:

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

File Format Requirements

The product catalog file must be in one of these formats:

All CSV product catalog files should adhere to the following requirements:

  • Each field must have a header.
  • Every entry uses quotation marks (") around each field for accurate parsing of data. These quotation marks are especially important for fields with line breaks, quotation marks, or commas. See Comma Escaping within Product Catalog Specification for more information.
  • A double quotation mark (") included in a field must be represented by two double quotation marks.
  • Character encoding must be UTF-8.

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

Product Catalog Values

AttributeRequiredData Type & ExampleDescription
item_group_idYesString (for example, AB12345)

50-character maximum
ID for a group of products that come in different versions; use the product ID collected in your Web integration where possible
idYesString (for example, A2B4)

50-character maximum
A product's unique identifier; use the product's SKU collected in your Web integration where possible
titleYesString (for example, Men's Pique Polo Shirt)A product's name, which displays in recommendations
image_linkYesString (for example, http:// www.example.com/image1.jpg)The URL of a product's main image
linkYesString (for example, http:// www.example.com/asp/sp.asp?cat= 12&id=1030)A product's landing page URL
descriptionYesString (for example, Red, 100% cotton, large men's t-shirt)A product's description
priceYesNumber (for example, 15.00)A product's price
product_typeYesComma-delimited string (for example, Clothing, Women, Sale)Separate multiple product types with a comma

Don't use a comma within a submitted product_type value because Monetate interprets it as separating 2 product types (for example, if you submit House, Garden & Kitchen, the value House is interpreted as a separate product_type from Garden & Kitchen)
additional_image_linkOptionalString (for example, http:// www.example.com/image1.jpg)The URL of an additional image for a product
adultOptionalBoolean (for example, yes)Indicate a product includes sexually suggestive content
age_groupOptionalString (for example, infant)A product's targeted demographic
availabilityOptionalString (for example, in stock)A product's availability
availability_dateOptionalString (datetime) (for example, 2016-09-30T12:10:45.000145Z)The date a preordered product becomes available for delivery
brandOptionalString (for example, YourBrand)A product's brand name
colorOptionalString (for example, black)A product's color
conditionOptionalString (for example, new)A product's condition
energy_efficiency_classOptionalString (for example, A+)A product's energy label
expiration_dateOptionalString (datetime) (for example, 2016-09-30T12:10:45.000145Z)The date on which a product expires
genderOptionalString (for example, Unisex)A product's targeted gender
google_product_categoryOptionalGoogle formatted string (for example, 2271 or Apparel & Accessories > Clothing > Dresses)The category of the item based on the Google product taxonomy; enables advanced analysis of your data by Monetate in the future

If this field's value doesn't match the Google taxonomy, then this field is ignored
is_bundleOptionalBoolean (for example, yes)Indicates that the product is a custom group of different products featuring one main product
loyalty_pointsOptionalString (for example, 100)The number and type of loyalty points a customer receives when buying a product
materialOptionalString (for example, leather)A product's fabric or material
mobile_linkOptionalString (for example, http://www.m.example.com/asp/sp.asp?cat=12&id=1030)A product's mobile-optimized landing page when you have a different URL for mobile and desktop traffic
mpnOptionalString (for example, MO12345NETATE)A product's manufacturer part number (MPN)
multipackOptionalNumber (for example, 6)The number of identical products sold within a multipack
patternOptionalString (for example, striped)A product's pattern
promotion_idOptionalString (for example, ABC123)An identifier that allows to you match products to promotions
sale_priceOptionalNumber (for example, 15.00)A product's sale price
sale_price_effective_date_beginOptionalString (datetime) (for example, 2016-09-30T12:10:45.000145Z)The date on which the product's sale price starts
sale_price_effective_date_endOptionalString (datetime) (for example, 2016-09-30T12:10:45.000145Z)The date on which the product's sale price ends
shippingOptionalString (for example, 15.00)A product's shipping cost
shipping_heightOptionalString (for example, 20 in)A product's height
shipping_labelOptionalString (for example, perishable)Label assigned to a product for shipping
shipping_lengthOptionalString (for example, 20 in)A product's length
shipping_weightOptionalString (for example, 3 kg)A product's weight
shipping_widthOptionalString (for example, 20 in)A product's width
sizeOptionalString (for example, XL)A product's size
size_typeOptionalString (for example, maternity)A product's cut
taxOptionalString (for example, US:CA:5.00:y)A product's sales tax rate in percent

Comma Escaping

Any value that contains a comma (,) must be escaped for a product catalog to pass validation. You must wrap the entire value in double quotation marks ("), such as with the value "Philadelphia, Pennsylvania". You can escape a single row at a time and do not need to do the full column.

Custom Columns

Monetate also accepts data contained within custom columns, also called custom fields. For example, you can send product ratings within a custom customer_rating column. Sending additional product data can, for example, enhance filters that you create in recommendation strategies.

You must define custom columns when creating the product catalog schema. Not only do you input the column name but also define the type of data it contains.

File Upload Validation Errors

If Monetate detects an issue while processing a product catalog file that you've uploaded, it displays one of the following errors.

Error TypeDescription
Wrong File TypeThe product catalog file is in an unsupported file format
Improper File EncodingThe file doesn't use UTF-8 encoding and must be reformatted
Missing Column HeadersOne or more column headers defined in the schema file are missing; column headers must match in both files
Duplicate Column HeadersOne or more column headers appears more than once in the catalog file
Row value doesn't match its data typeThe data in a row doesn't match the expected data type
System ErrorMonetate had an unexpected error while processing the file; submit a support ticket using the Monetate Technical Support portal (support.monetate.com) to resolve the issue
Extra Columns ProvidedThe file contains columns that aren't in the schema; columns in both files must match