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.

💡
Multiple language or multiple shops?
If you need to support multiple languages, read our guide on Multi-lang / multi-shop to choose an approach. The same concept can be applied to multiple shops.

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

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
url	alphanumeric	400	Optional Predefined category URL used for linking to category pages

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><![CDATA[root]]></name>
  <rank>0</rank>
</category>

Category URL

Linking to pretty category page URL's is one of things that always requires some investment to get working nicely. For example by translating category IDs to URL's on the application side, we can also store this on our side and provide it in our API's.

To support this, add the category URL in the category feed:

<category>
  <categoryid>5001</categoryid>
  <name><![CDATA[T-Shirts]]></name>
  <rank>100</rank>
  <url><![CDATA[/products/t-shirts]]></url>
</category>

Category hierarchy

Tweakwise is built around the mental model of your shop, that model is the category tree. Based on this model, you can apply powerful and flexible configurations in Tweakwise.

To get the most out of Tweakwise, it’s highly recommended to build a category hierarchy into your setup.

A category tree consists of main categories and subcategories. You define the structure by specifying which category is the parent of another.

Clothing  
└── Women  
    └── Dresses

In your XML feed this relationship is expressed by adding parents to a subcategory.

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><![CDATA[Clothing]]></name>
      <url><![CDATA[/clothing/]]></url>
      <rank>1</rank>
      <parents>
        <categoryid>1</categoryid>
      </parents>
    </category>
    <category>
      <categoryid>567</categoryid>
      <name><![CDATA[Accessories]]></name>
      <url><![CDATA[/accessories/]]></url>
      <rank>2</rank>
      <parents>
        <categoryid>1</categoryid>
      </parents>
    </category>
  </categories>
  <items></items>
</tweakwise>

Notes:

We recommend using relative URL's when possible: it offers benefits in flexibility, maintenance and of course SEO.
The parent categories of Accessories and Clothing both relate to the root

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.
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><![CDATA[Tweakwise T-Shirt]]></name>
  <price>24.99</price>
  <stock>10</stock>
  <brand><![CDATA[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>
 <attributes>
    <attribute>
      <name>item_type</name>
      <value>visual</value>
    </attribute>
</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><![CDATA[Tweakwise T-Shirt]]></name>
  <price>24.99</price>
  <stock>10</stock>
  <brand><![CDATA[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>item_type</name>
      <value><![CDATA[product]]></value>
    </attribute>
    <attribute>
      <name>Size</name>
      <value><![CDATA[Medium]]></value>
    </attribute>
    <attribute>
      <name>Color</name>
      <value><![CDATA[Blue]]></value>
    </attribute>
  </attributes>
</item>

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

👍
Add an item type attribute
Even if you don't plan to add other item types than products for now, it's a good practice to add an attribute to specify what the type of the added item is. Often this would be a product, but it could also be a visual or something you want to define yourself.

Multivalue attributes

Attributes can have multiple values by providing the same attribute name multiple times:

<attributes>
  <attribute>
      <name>Size</name>
      <value>S</value>
  </attribute>
  <attribute>
      <name>Size</name>
      <value>M</value>
  </attribute>
  <attribute>
      <name>Size</name>
      <value>XL</value>
  </attribute>
</attributes>

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 the (multivalue) categories element.

In this example, the item is linked to multiple categories: these categoryid's are a reference to the categories mentioned in Adding categories:

<item>
  <id>TSH0123</id>
  <name><![CDATA[Tweakwise T-Shirt]]></name>
  <!-- omitted for brevity -->
  <attributes>
    <!-- omitted for brevity -->
  </attributes>
  <categories>
    <categoryid>234</categoryid>
    <categoryid>567</categoryid>
  </categories>
</item>

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>
      <url>/clothing/</url>
      <rank>1</rank>
      <parents>
        <categoryid>1</categoryid>
      </parents>
    </category>
    <category>
      <categoryid>567</categoryid>
      <name>Accessories</name>
      <url>/accessories/</url>
      <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>
        <categoryid>456</categoryid>
      </categories>
    </item>
  </items>
</tweakwise>

Next steps

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.

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.