If you want to transfer a large amount of product information between your system 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.

The XML feed must contain a few elements. Let's build an example feed together. You can view the full example feed at the bottom of the page.

This tutorial will guide you with generating a feed in any programming language or tool if you know how to write text to a file with that language or tool. It will also help you to manually create a feed.

Before we start read this article if you don't have a basic understanding of XML.

1. XML Declaration

Start with writing the XML Prolog that indicates the XML version and the encoding used for the file. In this case we'll use the most common values: XML version 1.0 and UTF-8 encoding.

<?xml version="1.0" encoding="utf-8"?>

2. Create the root element

Every XML document must have a root element. Our root element is 'tweakwise' and we'll open it with an opening tag <tweakwise>. Here's how that looks.

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

❗️
Important
Keep in mind that XML is case sensitive. The tweakwise tag as well as all other tags we're going to add should be lower case, otherwise you'll encounter errors during the import.

3. Adding categories

Now we'll write an element containing our categories. We'll open the categories the same way as we opened the tweakwise element so our current XML looks like this:

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

📘
Good to know
We are adding space before the categories element to make different levels in the XML more clear and make the feed more readable for humans. This is called indentation. It is not required to use indentation to import the feed. Putting everything on one line can make the feed size smaller.

Every category has the following properties we need in Tweakwise:

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

A category will be an element containing an element for each of the above properties. Let's start with writing the root category. This is where the tree starts. Only one root category is allowed. We'll recognize the root category because it doesn't have parents. 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>

Note that we have now also closed the categories section with the closing tag </categories>

📘
Note that only one root category is allowed

4. 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.

For each item 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	a code used to group products related to each other, this field is necessary if the grouping is used for your lister pages
image	no*	alphanumeric	500	the main image URL
url	no*	alphanumeric	500	a URL to the item page

🚧
*In case you choose to implement Tweakwise in your frontend via our JS implementation, both the image as the url property are required as well.

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>

📘
CDATA sections
We used CDATA sections in the image and url elements. This is because a URL usually contains special characters like an ampersand (&) which should either be encoded or enclosed in a CDATA section. It is best practice to do this for all fields containing text.
To increase readability in this guide we omit this from the item name, item brand, category name and later on the attribute name and value as well.

4.1 Adding custom attributes to our items

Of course you'd want to add more information about the item so Tweakwise can use those properties for search. 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.

4.2 Adding categories to our 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.

5. Full feed

Finally when we wrote all our items to our feed we can close the items tag with </items>. After that we close the root element with </tweakwise>. Our 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>

Generating

1. XML Declaration

2. Create the root element

❗️
Important

3. Adding categories

📘
Good to know

📘

4. Adding items

🚧

📘
CDATA sections

4.1 Adding custom attributes to our items

4.2 Adding categories to our items

5. Full feed

1. XML Declaration

2. Create the root element

❗️Important

3. Adding categories

📘Good to know

📘

4. Adding items

🚧

📘CDATA sections

4.1 Adding custom attributes to our items

4.2 Adding categories to our items

5. Full feed

❗️
Important

📘
Good to know

📘
CDATA sections