If you want to transfer a large amount of product information between your platform and Tweakwise, you can use a specially formatted file to import that data. Tweakwise uses the XML format to perform this task. This is called the XML feed.

In this guide, we'll build an example feed together:

Basic structure
Adding categories
Adding items
Adding attributes to items
Adding category links to items
Import the feed

You can view the full example feed at the bottom of the page.

Basic structure

Every XML document must have a root element. Our root element is 'tweakwise' and contains a <categories> and <items> element:

<?xml version="1.0" encoding="utf-8"?>
<tweakwise>
  <categories>
  </categories>
  <items>
  </items>
</tweakwise>

Adding categories

Now we will add categories inside the categories element. For each category a 'category' element should be added. A category has the following required properties:

Property	Type	Max length	Description
categoryid	numeric/alphanumeric	-/50	a unique identifier of numeric characters by default. If you need to use alphanumeric characters, contact our support team
name	alphanumeric	500	the name of the category
rank	numeric	-	a number to determine the sequence of the category
parents	list	-	IDs of the categories which are parents of the category

Let's start with writing the root category. This is where the tree starts. Only one root category is allowed. Tweakwise will recognize this root category, based on the existance of any parent links. The XML for a root category looks like this:

<category>
  <categoryid>1</categoryid>
  <name>root</name>
  <rank>0</rank>
</category>

Let's add this category to the XML we have built until now and add two main categories 'Clothing' and 'Accessories'.

<?xml version="1.0" encoding="utf-8"?>
<tweakwise>
  <categories>
    <category>
      <categoryid>1</categoryid>
      <name>root</name>
      <rank>0</rank>
    </category>
    <category>
      <categoryid>234</categoryid>
      <name>Clothing</name>
      <rank>1</rank>
      <parents>
        <categoryid>1</categoryid>
      </parents>
    </category>
    <category>
      <categoryid>567</categoryid>
      <name>Accessories</name>
      <rank>2</rank>
      <parents>
        <categoryid>1</categoryid>
      </parents>
    </category>
  </categories>
  <items></items>
</tweakwise>

Adding items

Now we will add all our items (i.e. products, content or articles). We have to open the section by writing an open tag <items> just like we opened the 'categories' section.

Products

For each product we have to write an 'item' element. An item has the following required properties:

Property	Required	Type	Max length	Description
id	yes	alphanumeric	100	A unique identifier
name	yes	alphanumeric	500	The item name
price	yes	decimal	-	The item price.
stock	yes	numeric	-	The current available stock.
brand	no	alphanumeric	250	The item brand
groupcode	no	alphanumeric	100	Code used to group products related to each other, this field is necessary if the grouping is used for your lister pages. Not supported in Tweakwise JS.
image	no*	alphanumeric	500	the main image URL.
url	no*	alphanumeric	500	a URL to the item page.

* In case of Tweakwise JS, these are recommended.

Let's create an XML element for our Tweakwise T-Shirt:

<item>
  <id>TSH0123</id>
  <name>Tweakwise T-Shirt</name>
  <price>24.99</price>
  <stock>10</stock>
  <brand>Tweakwise</brand>
  <groupcode>SHOE-GROUP1</groupcode>
  <image><![CDATA[https://codesandboxdemostorage.blob.core.windows.net/codesandboxdemostorage/products/tshirt-blauw.jpg]]></image>
  <url><![CDATA[https://3zbfu.csb.app/#twn|?tn_q=tweakwise%20t-shirt%20blue]]></url>
</item>

<?xml version="1.0" encoding="utf-8"?>
<tweakwise>
  <categories>
    <category>
      <categoryid>1</categoryid>
      <name>root</name>
      <rank>0</rank>
    </category>
    <category>
      <categoryid>234</categoryid>
      <name>Clothing</name>
      <rank>1</rank>
      <parents>
        <categoryid>1</categoryid>
      </parents>
    </category>
    <category>
      <categoryid>567</categoryid>
      <name>Accessories</name>
      <rank>2</rank>
      <parents>
        <categoryid>1</categoryid>
      </parents>
    </category>
  </categories>
  <items>
    <item>
      <id>TSH0123</id>
      <name>Tweakwise T-Shirt</name>
      <price>24.99</price>
      <stock>10</stock>
      <brand>Tweakwise</brand>
      <groupcode>SHOE-GROUP1</groupcode>
      <image><![CDATA[https://codesandboxdemostorage.blob.core.windows.net/codesandboxdemostorage/products/tshirt-blauw.jpg]]></image>
      <url><![CDATA[https://3zbfu.csb.app/#twn|?tn_q=tweakwise%20t-shirt%20blue]]></url>
    </item>

Non-products

For each item that is not a product, we also have to write an 'item' element. An item has the following properties:

Property	Required	Type	Max length	Description
id	yes	alphanumeric	100	A unique identifier
name	yes	alphanumeric	500	The item name
image	yes	alphanumeric	500	the main image URL.
url	yes	alphanumeric	500	a URL to the item page.

Let's create an element for a banner for a free Tweakwise T-Shirt:

<item>
  <id>promo-TSH0123</id>
  <name>Free Tweakwise T-Shirt</name>
  <image><![CDATA[https://codesandboxdemostorage.blob.core.windows.net/codesandboxdemostorage/products/tshirt-blauw.jpg]]></image>
  <url><![CDATA[/free-shirt-now]]></url>
</item>

<?xml version="1.0" encoding="utf-8"?>
<tweakwise>
  <categories>
    <category>
      <categoryid>1</categoryid>
      <name>root</name>
      <rank>0</rank>
    </category>
    <category>
      <categoryid>234</categoryid>
      <name>Clothing</name>
      <rank>1</rank>
      <parents>
        <categoryid>1</categoryid>
      </parents>
    </category>
    <category>
      <categoryid>567</categoryid>
      <name>Accessories</name>
      <rank>2</rank>
      <parents>
        <categoryid>1</categoryid>
      </parents>
    </category>
  </categories>
  <items>
    <item>
      <id>TSH0123</id>
      <name>Tweakwise T-Shirt</name>
      <price>24.99</price>
      <stock>10</stock>
      <brand>Tweakwise</brand>
      <groupcode>SHOE-GROUP1</groupcode>
      <image><![CDATA[https://codesandboxdemostorage.blob.core.windows.net/codesandboxdemostorage/products/tshirt-blauw.jpg]]></image>
      <url><![CDATA[https://3zbfu.csb.app/#twn|?tn_q=tweakwise%20t-shirt%20blue]]></url>
    </item>

Adding attributes to items

Of course you'd want to add more information about the item so Tweakwise can use those properties for search.

Property	Type	Max length	Description
name	alphanumeric	100	The attribute name. Note: this field cannot not contain HTML.
value	alphanumeric	400	The attribute value.

For a T-shirt you probably want the color and size. Let's add them in an attributes element:

<item>
  <id>TSH0123</id>
  <name>Tweakwise T-Shirt</name>
  <price>24.99</price>
  <stock>10</stock>
  <brand>Tweakwise</brand>
  <groupcode>SHOE-GROUP1</groupcode>
  <image><![CDATA[https://codesandboxdemostorage.blob.core.windows.net/codesandboxdemostorage/products/tshirt-blauw.jpg]]></image>
  <url><![CDATA[https://3zbfu.csb.app/#twn|?tn_q=tweakwise%20t-shirt%20blue]]></url>
  <attributes>
    <attribute>
      <name>Size</name>
      <value>Medium</value>
    </attribute>
    <attribute>
      <name>Color</name>
      <value>Blue</value>
    </attribute>
  </attributes>
</item>

<?xml version="1.0" encoding="utf-8"?>
<tweakwise>
  <categories>
    <category>
      <categoryid>1</categoryid>
      <name>root</name>
      <rank>0</rank>
    </category>
    <category>
      <categoryid>234</categoryid>
      <name>Clothing</name>
      <rank>1</rank>
      <parents>
        <categoryid>1</categoryid>
      </parents>
    </category>
    <category>
      <categoryid>567</categoryid>
      <name>Accessories</name>
      <rank>2</rank>
      <parents>
        <categoryid>1</categoryid>
      </parents>
    </category>
  </categories>
  <items>
    <item>
      <id>TSH0123</id>
      <name>Tweakwise T-Shirt</name>
      <price>24.99</price>
      <stock>10</stock>
      <brand>Tweakwise</brand>
      <groupcode>SHOE-GROUP1</groupcode>
      <image><![CDATA[https://codesandboxdemostorage.blob.core.windows.net/codesandboxdemostorage/products/tshirt-blauw.jpg]]></image>
      <url><![CDATA[https://3zbfu.csb.app/#twn|?tn_q=tweakwise%20t-shirt%20blue]]></url>
      <attributes>
        <attribute>
          <name>Size</name>
          <value>Medium</value>
        </attribute>
        <attribute>
          <name>Color</name>
          <value>Blue</value>
        </attribute>
      </attributes>
    </item>

We added an attributes element containing multiple attribute elements. Each attribute element contains a name and a value.

Adding category links to items

The last thing we have to do is link the T-shirt to the clothing category. For that we can use a categories element:

<item>
  <id>TSH0123</id>
  <name>Tweakwise T-Shirt</name>
  <price>24.99</price>
  <stock>10</stock>
  <brand>Tweakwise</brand>
  <groupcode>SHOE-GROUP1</groupcode>
  <image><![CDATA[https://codesandboxdemostorage.blob.core.windows.net/codesandboxdemostorage/products/tshirt-blauw.jpg]]></image>
  <url><![CDATA[https://3zbfu.csb.app/#twn|?tn_q=tweakwise%20t-shirt%20blue]]></url>
  <attributes>
    <attribute>
      <name>Size</name>
      <value>Medium</value>
    </attribute>
    <attribute>
      <name>Color</name>
      <value>Blue</value>
    </attribute>
  </attributes>
  <categories>
    <categoryid>234</categoryid>
  </categories>
</item>

<?xml version="1.0" encoding="utf-8"?>
<tweakwise>
  <categories>
    <category>
      <categoryid>1</categoryid>
      <name>root</name>
      <rank>0</rank>
    </category>
    <category>
      <categoryid>234</categoryid>
      <name>Clothing</name>
      <rank>1</rank>
      <parents>
        <categoryid>1</categoryid>
      </parents>
    </category>
    <category>
      <categoryid>567</categoryid>
      <name>Accessories</name>
      <rank>2</rank>
      <parents>
        <categoryid>1</categoryid>
      </parents>
    </category>
  </categories>
  <item>
    <id>TSH0123</id>
    <name>Tweakwise T-Shirt</name>
    <price>24.99</price>
    <stock>10</stock>
    <brand>Tweakwise</brand>
    <groupcode>SHOE-GROUP1</groupcode>
    <image><![CDATA[https://codesandboxdemostorage.blob.core.windows.net/codesandboxdemostorage/products/tshirt-blauw.jpg]]></image>
    <url><![CDATA[https://3zbfu.csb.app/#twn|?tn_q=tweakwise%20t-shirt%20blue]]></url>
    <attributes>
      <attribute>
        <name>Size</name>
        <value>Medium</value>
      </attribute>
      <attribute>
        <name>Color</name>
        <value>Blue</value>
      </attribute>
    </attributes>
    <categories>
      <categoryid>234</categoryid>
    </categories>
  </item>

We added a categories element with ID 234. This is the id of the category 'Clothing' that we created in chapter 3.

Import

After generating the feed, next steps would be to:

Make the feed available: Once your feed is generated, the next step is to make it available so Tweakwise can access and import it. To learn more, go to Make a feed available for Tweakwise.
Import the feed: Once the feed is available, it can be read and processed by Tweakwise. To learn more, go to Import a feed.

Full example

The full feed now looks like this:

<?xml version="1.0" encoding="utf-8"?>
<tweakwise>
  <categories>
    <category>
      <categoryid>1</categoryid>
      <name>root</name>
      <rank>0</rank>
    </category>
    <category>
      <categoryid>234</categoryid>
      <name>Clothing</name>
      <rank>1</rank>
      <parents>
        <categoryid>1</categoryid>
      </parents>
    </category>
    <category>
      <categoryid>567</categoryid>
      <name>Accessories</name>
      <rank>2</rank>
      <parents>
        <categoryid>1</categoryid>
      </parents>
    </category>
  </categories>
  <items>
    <item>
      <id>TSH0123</id>
      <name>Tweakwise T-Shirt</name>
      <price>24.99</price>
      <stock>10</stock>
      <brand>Tweakwise</brand>
      <groupcode>SHOE-GROUP1</groupcode>
  		<image><![CDATA[https://codesandboxdemostorage.blob.core.windows.net/codesandboxdemostorage/products/tshirt-blauw.jpg]]></image>
  		<url><![CDATA[https://3zbfu.csb.app/#twn|?tn_q=tweakwise%20t-shirt%20blue]]></url>
      <attributes>
        <attribute>
          <name>Size</name>
          <value>Medium</value>
        </attribute>
        <attribute>
          <name>Color</name>
          <value>Blue</value>
        </attribute>
      </attributes>
      <categories>
        <categoryid>234</categoryid>
      </categories>
    </item>
  </items>
</tweakwise>

Good to know

If you don't have a basic understanding of XML, we recommend reading XML for the uninitiated.
This tutorial will guide you in generating a feed in any programming language or tool, as long as you know how to write text to a file using that language or tool. It will also help you manually create a feed if needed.
Only one root category is allowed.
A category ID is considerd alphanumeric, and can contain both letters and numbers.
To increase readability, the examples contain different levels of indentation>> and newlines. This is not required in your feed. Removing tabs and newlines can make the feed size smaller and have impact on the performance of the import.
It is best practice to apply CDATA sections to all fields containing text. For example, image and url elements usually contain characters like an ampersand (&). To increase readability in this guide we omit this from some elements.