Legacy Product Feed Specification: XML

This product catalog/feed type is deprecated. Unless you are a Monetate client still using the legacy product specification, refer to the current product catalog specification.

If you have any questions about your product feed or any custom requirements, submit a support ticket using the Monetate Technical Support portal (support.monetate.com).

See Receiving Feed-Parsing Error Notifications in Upload a Product Feed for the steps to receive emails from Monetate informing you of feed-parsing errors.

Format Requirements

The specifications in this document are only relevant for feeds formatted as XML files. For feeds formatted as CSV files, see Product Feed Specifications: CSV. For feeds formatted as TSV files, see Product Feed Specifications: TSV.

If you adhere to these guidelines for XML product feeds, you can validate a feed using the feed validator available in Monetate. Once the feed passes, you can upload it for processing. If you have any questions about product feeds and any custom requirements, submit a support ticket using the Monetate Technical Support portal (support.monetate.com).

All XML feed files should adhere to the following requirements:

  • XML files must be version 1.0.
  • Character encoding must be UTF-8 without HTML escaping.
  • Every product in a feed must be surrounded by an opening <product> tag and a closing </product> tag.

Monetate natively supports UTF-8 characters up to the Specials Unicode block. To encode characters beyond this type, you should use HTML encoding. For more information about the Specials block, refer to the Specials PDF from The Unicode Consortium (unicode.org).

Fields

The information in this section describes the required and optional fields for a product feed file.

Any information that you include in a product feed must match the values that you collect on your site through the addCartRows, addPurchaseRows, addProducts, and addProductDetails method calls.

Product ID

Header

product_id

Required

Yes

Specifications

  • Must match what Monetate collects on product detail and search pages
  • Typically not a SKU but a higher-level identifier that identifies groups of products before further refinement based on size or color
  • Maximum length of 32 characters
  • Only alphanumeric (a–z, A–Z, or 0–9), forward slash (/), underscore (_), dash (-), and period (.) characters are acceptable

Examples

  • <product_id>1135813</product_id>
  • <product_id>AAABBCCDD</product_id>
  • <product_id>AbZ190-430_mm/89.pid</product_id>

Product Name

Header

product_name

Required

Yes

Specifications

Maximum length of 128 characters

Examples

  • <product_name>Deluxe Stereo Headphones</product_name>
  • <product_name>Portable Music Player</product_name>
  • <product_name>Electric Shaving Kit</product_name>

Category Name

Header

category_name

Required

Yes

Specifications

  • Used for targeting product categories in experiences
  • No predetermined categories set by Monetate, so each category is defined within its own container
  • Maximum length of 128 characters per individual category name
  • Unlimited number of categories per product
  • Multiple names must be separated with a pipe (|) without a space before and after the pipe

Examples

Single category example

<categories>
  <category>
    <category_id>cid1</category_id>
    <category_name>category 1</category_name>
  </category>
</categories>

Multiple category example

<categories>
  <category>
    <category_id>cid1</category_id>
    <category_name>category 1</category_name>
  </category>
  <category>
    <category_id>cid2</category_id>
    <category_name>category 2</category_name>
  </category>
</categories>

Price

Header

price

Required

Yes

Specifications

  • Current price of the product in decimal format
  • For retail or strikethrough price, use alt_price
  • No support for pricing beyond active price and alternate price

Examples

  • <price>33.50</price>
  • <price>100.00</price>
  • <price>0.50</price>

Product URL

Header

url

Required

Yes

Specifications

  • Full URL to the product detail page
  • Should include both the scheme and host portions of the URL

Examples

  • <url>http://www.monetate.com/products/123</url>
  • <url>http://www.monetate.com/running_shoe.html</url>
  • <url>http://www.monetate.com/products/diving_watch.htm</url>

Product Image URL

Header

product_image_url

Required

Yes

Specifications

  • Full URL to a product image
  • Should include both the scheme and host portions of the URL

Examples

  • <product_image_url>http://www.monetate.com/images/products/123.jpg</product_image_url>
  • <product_image_url>http://www.monetate.com/images/house.png</product_image_url>
  • <product_image_url>http://www.monetate.com/example.gif>

Product Description

Header

product_description

Required

No

Specifications

Description of the product with a maximum length of 1,024 characters

Examples

  • <product_description>A lovely example of modern elegance and style</product_description>
  • <product_description>Red</product_description>
  • <product_description>The latest electronics craze—this stereo is all the rage!</product_description>

Alternate Price

Header

alt_price

Required

No

Specifications

  • An alternate price for display purposes only
  • Must be in decimal format

Examples

  • <alt_price>33.50</alt_price>
  • <alt_price>100.00</alt_price>
  • <alt_price>0.50</alt_price>

Category ID

Header

category_id

Required

No

If you don't intend to include or exclude product categories from Visual Search results or if you don't intend to use Visual Search at all, you can remove category_id from product feeds. If you have questions, submit a support ticket using the Monetate Technical Support portal (support.monetate.com).

Specifications

  • Maximum length of 128 characters
  • Only alphanumeric (a–z, A–Z, or 0–9) characters are acceptable
  • Category ID must be unique per category name

Examples

Single category example

<categories>
  <category>
    <category_id>cid1</category_id>
    <category_name>category 1</category_name>
  </category>
</categories>

Multiple category example

<categories>
  <category>
    <category_id>cid1</category_id>
    <category_name>category 1</category_name>
  </category>
  <category>
    <category_id>cid2</category_id>
    <category_name>category 2</category_name>
  </category>
</categories>

Availability

Header

availability

Required

No

Specifications

  • Denotes whether an item is in stock or out of stock
  • Out-of-stock items are excluded from endcaps
  • Acceptable values include In Stock and Out of Stock
  • Other values such as Presale may be used but are equivalent to Out of Stock

Examples

  • <availability>In Stock</availability>
  • <availability>Out of Stock</availability>
  • <availability>Presale</availability>

Category Names and Category IDs

The way that category_name and category_id work together is as follows.

<product> 
  <product_id>AA329</product_id>
  <categories>
    <category>
      <category_id>c1</category_id>
      <category_name>chair</category_name>
    </category>
    <category>        
      <category_id>f3</category_id>
      <category_name>furniture</category_name>
    </category>   
    <category>
      <category_id>w99</category_id>
      <category_name>wood</category_name>
    </category>
  </categories> 
</product>

catalog_category

category_id category_name
c1 chair
f3 furniture
w99 wood

catalog_product_category

product_id category_id
AA329 c1
AA329 f3
AA329 w99

Product IDs and SKU

The way that product_id and sku work together is as follows.

<product> 
  <product_id>xyz888</product_id>
  <categories>
    <category>
      <category_id>f1</category_id>
      <category_id>f3</category_id>
    </category>
  </categories> 
  <skus>
    <sku>1135813</sku>
    <sku>223234</sku>
  </skus>
</product>

product_id_sku

product_id sku
xyz888 1135813
xyz888 223234

product_category

product_id category_id
xyz888 f1
xyz888 f3

Example with Minimum Required Fields

<?xml version="1.0" encoding="utf-8"?>
<catalog>
  <product> 
    <product_id>33435</product_id>
    <product_name>High Back Lounge Chair</product_name>
    <categories>
      <category>
        <category_name>chair</category_name>
      </category>
    </categories> 
    <price>299.99</price>
    <url>http://www.monetate.com/products/123</url>
    <product_image_url>http://www.monetate.com/products/123.png</product_image_url>
  </product>
</catalog>

Example with Minimum Required Fields and Optional Fields

<?xml version="1.0" encoding="utf-8"?>
<catalog>
  <product> 
    <product_id>33435</product_id>
    <product_name>High Back Lounge Chair</product_name>
    <product_description>Durable chair with added lumbar support and cup holder</product_description>
    <brand_name>MoneChair</brand_name>
    <categories>
      <category>
        <category_name>chair</category_name>
        <category_id>1234</category_id>         
      </category>
    </categories> 
    <price>299.99</price>
    <alt_price>280.11</alt_price>   
    <url>http://www.monetate.com/products/123</url>
    <product_image_url>http://www.monetate.com/products/123.png</product_image_url>
    <availability>In Stock</availability>
  </product>
</catalog>

Related Articles