Import content in Tweakwise

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

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 content inside the items element. For each content item an 'item' element should be added. An item has the following properties:

PropertyTypeMax lengthDescription
idalphanumeric100a unique identifier
namealphanumeric500the item name
imagealphanumeric500the main image URL
urlalphanumeric500a URL to the item page

Example

<item>
  <id>PROMO-shirts-june-2024</id>
  <name>Tweakwise T-Shirts</name>
  <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

Introduce a specific attribute where you will store your item content type. This can be any attribute name, for example: item-type.

Contact us to configure the attribute as characteristic: the front-end API will use this type in the type field.

<item>
  <id>PROMO-shirts-june-2024</id>
  <name>Tweakwise T-Shirt</name>
  <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>visual</value>
    </attribute>
  </attributes>
</item>

Adding category links

The last thing we have to do is link the item to an existing category:

<item>
  <id>PROMO-shirts-june-2024</id>
  <name>Tweakwise T-Shirt</name>
  ...
  <categories>
    <categoryid>promo-shirts-june</categoryid>
  </categories>
</item>

Full example

<?xml version="1.0" encoding="utf-8"?>
<tweakwise>
  <items>
    <item>
      <id>PROMO-shirts-june-2024</id>
      <name>Tweakwise T-Shirt</name>
      <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>visual</value>
        </attribute>
      </attributes>
      <categories>
        <categoryid>Promo-shirts-june</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.
  • 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.