To transfer a large amount of product information between your platform and Tweakwise, you can use a specially formatted file. Tweakwise uses the XML format for this purpose, which is referred to as an XML feed.

In this guide, we'll walk through building a separate products feed, covering:

• Basic structure
• Adding items
• Adding attributes to items
• Adding category links to items
• Importing 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', which we open with an <tweakwise> tag. Here's an example:

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

Adding Items

Now, let's add our items (e.g., products, content, or articles).

Products

For each product, you must define an <item> element. An item has the following required properties:

* These are recommended for Tweakwise JS.

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

You'll likely want to add more information about the item so Tweakwise can use these properties for search.

For a T-shirt, you'll likely want to include attributes such as color and size. Let's add them within 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>item_type</name>
      <value>product</value>
    </attribute>
    <attribute>
      <name>Size</name>
      <value>Medium</value>
    </attribute>
    <attribute>
      <name>Color</name>
      <value>Blue</value>
    </attribute>
  </attributes>
</item>

We've 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 currently plan to add item types other than products, it's good practice to include an attribute that specifies the item's type. This will often be a product, but it could also be a visual or a custom type you define.

💡

Multiple Attribute Values

You can add multi-value attributes in separate <attribute> elements with the same name but different values.

Example

<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

The final step is to link the T-shirt to its respective categories. For this, you can use a <categories> element.

In this example, the item is linked to multiple categories. These categoryids refer to the categories mentioned in Adding categories:

<item>
  <id>TSH0123</id>
  <name>Tweakwise T-Shirt</name>
  ...
  <attributes>
    ...
  </attributes>
  <categories>
    <categoryid>234</categoryid>
    <categoryid>456</categoryid>
  </categories>
</item>

Adding a Group Code

Group codes enable the grouping of product variants. Learn more about this concept here.

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, create a new import task with the Import type set to Import items only.

Ensure this task is executed after the category import task by using the task chaining option. This is necessary because the product import depends on the category import.

Good to Know

• If you lack a basic understanding of XML, we recommend reading XML for the uninitiated.
• This tutorial will guide you in generating a feed using any programming language or tool, provided you know how to write text to a file. It will also assist you in manually creating a feed if necessary.
• To increase readability, the examples include different levels of indentation and newlines. These are not required in your feed. Removing tabs and newlines can reduce the feed size and impact import performance.
• It is best practice to apply CDATA sections to all fields containing text. For example, image and url elements typically contain characters like an ampersand (&). To enhance readability in this guide, we sometimes omit this from elements.