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 a seperate products feed together:

Basic structure
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.

💡
Tip
The recommended method to get your product data into Tweakwise is by generating a feed with products and categories combined. To learn more, go to Create an XML feed to import your catalog data in Tweakwise.

Basic structure

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>
  <items>
    <!-- -->
  </items>
</tweakwise>

Adding items

Now we will add all our items (i.e. products, content or articles).

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>

Adding attributes

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>

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

📘
Multiple attribute values
You can add multi-value attributes in separate elements with the same name but different values.
<attributes>
  <attribute>
    <name>Color</name>
    <value>Blue</value>
  </attribute>
  <attribute>
    <name>Color</name>
    <value>Red</value>
  </attribute>
</attributes>

Adding category links

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>
  ...
  <attributes>
    ...
  </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.

Full example

<?xml version="1.0" encoding="utf-8"?>
<tweakwise>
  <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>

Import

In Tweakwise App > Connectivity > Tasks you should create a new import task with Import type set to Import items only.

Make sure this task is executed afterthe category import task, using the task chaining option. This is necessary because the product import has a dependency on the category import.

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

Import products in Tweakwise

💡
Tip

Basic structure

Adding items

Products

Adding attributes

📘
Multiple attribute values

Adding category links

Full example

Import

Good to know

💡Tip

Basic structure

Adding items

Products

Adding attributes

📘Multiple attribute values

Adding category links

Full example

Import

Good to know

💡
Tip

📘
Multiple attribute values