XML Schema Guide

Bunting can learn about your product inventory to drive our product recommendation system, as well as using this data to enable social proofing & urgency messaging.

This document discusses the XML format required by Bunting.

Example Complete Feed

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
  <!DOCTYPE feed SYSTEM "https://YOUR_BUNTING_ID.1.example.com/feed-9.dtd">
    <feed>
      <product>
        <upc>abc123</upc>
        <ns>
          <ENG>iPad</ENG>
        </ns>
        <ps>
          <GBP>399.99</GBP>
        </ps>
        <u>https://example.com/products/abc123-ipad.html</u>
        <iu>https://example.com/main-images/ipad.jpg</iu>
        <i2u>https://example.com/secondary-images/ipad.jpg</i2u>
        <c>Tablets</c>
        <b>Apple</b>
        <oss>
          <GBP></GBP>
        </oss>
        <oe></oe>
        <rt>4.8</rt>
        <s>y</s>
        <gtin>3001234567892</gtin>
        <kw>black 250Gb</kw>
        <g></g>
        <cv1></cv1>
        <cv2>Extended Warranty</cv2>
        <cv3></cv3>
        <cv4></cv4>
        <cv5></cv5>
      </product>
        <product>
        <upc>xyz789</upc>
        <ns>
          <ENG>Revolving iPad Case in Pink</ENG>
        </ns>
        <ps>
          <GBP>34.99</GBP>
        </ps>
        <u>https://example.com/products/xyz789-ipad-case.html</u>
        <iu>https://example.com/main-images/ipad-case.jpg</iu>
        <i2u></i2u>
        <c>iPad Accessories</c>
        <b>FAB Cases</b>
        <oss>
          <GBP>5</GBP>
        </oss>
        <oe>1541078129</oe>
        <rt>3.2</rt>
        <s>4</s>
        <gtin>3001234567892</gtin>
        <kw>leather casual</kw>
        <g>female</g>
        <cv1>Free Screen Cover!</cv1>
        <cv2></cv2>
        <cv3></cv3>
        <cv4></cv4>
        <cv5></cv5>
        <a>yes</a>
      </product>
    </feed>

Specification

Please note For products with variations, you should only include the main product, which represents all variations. For example if “Men’s Pique Polo Shirt” is available in red and blue, you should only include the product once within the feed, using the title “Men’s Pique Polo Shirt”. Do not include the product multiple times for each variation.

Unique Product Code

The identifier for each product has to be unique within your account, and cannot be re-used. You can use any sequence of letters and digits for the product ID.

Requirement Tag Type Character Limit Example Value XML Example
Mandatory <upc> Text 250 Characters Max abc123 <upc>abc123</upc>

Product Name

This is the name of your product, which is required. Within the <ns>...</ns> node should be the name, in each relevant language accepted by your site, as demonstrated below. It is highly recommended that you wrap your values in a CDATA section to avoid invalid XML.

The default language is required for all products. Secondary languages are highly recommended, but not mandatory.

Requirement Tag Type Character Limit Example Value XML Example
Mandatory <ns> Text 250 Characters Max iPad <ns><ENG><![CDATA[iPad]]></ENG></ns>

Product Price

The price of the product. Within the <ps>...</ps> node should be the price, in each relevant currency accepted by your site, as demonstrated below.

The default currency is required for all products. Secondary currencies are highly recommended, but not mandatory.

Important: If the product is on offer, then the price should be after the reduction, not before. So, for example, if a product was 300 reduced to 250, then the price should be 250

Requirement Tag Type Character Limit Example Value XML Example
Mandatory <ps> Number 250 Characters Max 399.99 <ps><GBP>399.99</GBP></ps>

Product URL

This is the web address of the product on your website. It must be an absolute URL, including the http:// protocol. Please do not include any tracking parameters. It is highly recommended that you wrap your values in a CDATA section to avoid invalid XML.

Requirement Tag Type Character Limit Example Value XML Example
Mandatory <u> Text (include protocol) 250 Characters Max https://www.yoursite.com/products/abc123-ipad.html <u><![CDATA[http://www.yoursite.com/products/abc123-ipad.html]]></u>

Product Image URL

This is the URL of the main image for a product and is the first image that users see on product detail pages. It must be an absolute URL, including the http:// protocol.

If you have multiple different images of the product, submit the main image using this attribute and include a secondary image in the ‘Image 2 URL’ attribute. For best performance, images should ideally be around 700px by 700px.

It is highly recommended that you wrap your values in a CDATA section to avoid invalid XML.

Required for all products.

Requirement Tag Type Character Limit Example Value XML Example
Mandatory <iu> Text (include protocol) 250 Characters Max https://example.com/main-images/abc123.jpg <iu><![CDATA[http://example.com/main-images/abc123.jpg]]></iu>

Image 2 URL

If you have an additional image for this product, include its URL in this attribute, including the http:// protocol. For example, if you have an image that shows the product from a different angle than the main image or if you have images of the packaging or the product in various settings. For best performance, images should ideally be around 700px by 700px.

It is highly recommended that you wrap your values in a CDATA section to avoid invalid XML.

Required for all products.

Requirement Tag Type Character Limit Example Value XML Example
Optional <i2u> Text (include protocol) 250 Characters Max https://example.com/secondary-images/abc123.jpg <i2u><![CDATA[https://example.com/secondary-images/abc123.jpg]]></i2u>

Category

This attribute is the category path used by your system that contains the product. Nested categories should be separated by > symbols.

It is highly recommended that you wrap your values in a CDATA section to avoid invalid XML.

Required for all products.

Requirement Tag Type Character Limit Example Value XML Example
Optional <c> Text 250 Characters Max >Electronics > Computers > Tablets< <c><![CDATA[Electronics > Computers > Tablets]]></c>

Brand

The name of the brand that manufactures the product. It is highly recommended that you wrap your values in a CDATA section to avoid invalid XML

Requirement Tag Type Character Limit Example Value XML Example
Optional <b> Text 250 Characters Max Apple <b><![CDATA[Apple]]></b>

Offer Saving

Offer saving if this product is on offer (number). For example, if price is 250, but used to be 300 when not on offer, then this value should be 50

Within the <oss>…</oss> node should be the offer saving, in each relevant currency accepted by your site, as demonstrated below.

Requirement Tag Type Character Limit Example Value XML Example
Optional <oss> Text 250 Characters Max 59.50 <oss><GBP>59.50</GBP></oss>

Offer Expiry

If the product is on offer, then this attribute should be set to the expiry date. Dates can be submitted as Unix Timestamps only (timestamp info). If the product isn’t on offer, or if the offer doesn’t have an end date then simply enter 0.

Requirement Tag Type Example Value XML Example
Optional <oe> 10 digit number 1541078733 <oe>1541078733</oe>

Product Rating

If this product has been rated then enter the rating here. Rating values should be between 0 and 5. If your rating uses a different scale, then this should be converted. For example, a product rated 9 / 10 should be halved to make 4.5. Decimal places accepted.

Requirement Tag Type Example Value XML Example
Optional <oe> Number between 0 and 5 4.5 <rt>4.5</rt>

Stock Level

Is product in stock? Passing a number means: “yes, 14 units are remaining”. Passing the value y means units are remaining, but the number is unspecified. Passing n or 0 mean out of stock.

Requirement Tag Type Example Value XML Example
Optional <s> Alpha-numeric value 14 <s>14</s>

GTIN

Use the ‘GTIN’ attribute to submit Global Trade Item Numbers (GTINs) in one of the following formats:

  • UPC (in North America): 12-digit number such as 3234567890126
  • EAN (in Europe): 13-digit number such as 3001234567892
  • JAN (in Japan): 8- or 13-digit number such as 49123456 or 4901234567894
  • ISBN (for books): 10- or 13-digit number such as 0451524233. If you have both, only include the 13-digit number.

For products with multiple variations and, consequently, multiple GTIN numbers, you can separate each number with a comma. For example, a jumper in red, blue and yellow could have the following GTINs: <gtin>3001234567892,4001234567892,5001234567892</gtin>

Requirement Tag Type Character Limit: Example Value XML Example
Optional <gtin> 8-, 12- or 13-digit number (UPC, EAN, JAN or ISBN) 20 3001234567892 <gtin>3001234567892</gtin>

Keywords

Part of Bunting’s product recommendation algorithm involves matching keywords found in each product’s name to find similarities. However, if your product names are short or keyword-poor then we recommend including additional keywords in this field to compensate. These could be, for example, the name of a range that each product is part of, or a characteristic that plays in important role in visitor’s buying decisions, such as colour or size.

Well chosen keywords can notably improve product recommendations while supportive order data is being collected. However, conversely, poorly chosen keywords can damage them. Therefore we recommend including keywords only if you have good ones available.

Keywords can be separated by commas or spaces. It is highly recommended that you wrap your values in a CDATA section to avoid invalid XML.

Requirement Tag Type Character Limit: Example Value XML Example
Optional <kw> Text 250 black 250Gb <kw><![CDATA[black 250Gb]]></kw>

Gender

Does product have a target gender, such as a lady’s jumper, or a man’s watch? If so, enter male or female. If the product is unisex (applicable to both genders) then leave this field blank. Any other value, including blank, will default to unisex.

Requirement Tag Format Example Value XML Example
Optional <g> ‘male’,’female’, or any other value including blank for unisex female <g>female</g>

Custom Values 1 – 5

Within the product recommendations that Bunting delivers to your website you may wish to have unique features or benefits displayed against some products but not others. To achieve this you can use Custom Values. Up to 5 values are accepted per product.

Values can contain HTML such as an <img />, they can be text strings that can be styled within your recommendation widgets, or be simple flag values to be caught by a recommendation widget IF statement. Anything within 250 characters length.

It is highly recommended that you wrap your values in a CDATA section to avoid invalid XML.

Optional for all products.

Requirement Tag Type Example Value XML Example
Optional <cv1> - <cv5> Text Free Carry Case
3 Year Extended Warranty
<cv1><![CDATA[Free Carry Case]]></cv1>
<cv2><![CDATA[3 Year Extended Warranty]]></cv2>

Active

Is the product active and available to buy on the website? If not then pass the value no. Any other value, including blank, will default to yes.

Requirement Tag Format Example Value XML Example
Optional <a> ‘yes’ or ‘no’. Any value other than ‘no’, including blank, is taken as ‘yes’ yes <a>yes</a>