XML file specification

The root element, contained only once in the file.

This element contains information about a specific product. It is included in the file as many times as you have product variants. For example, if you sell a T-shirt in five sizes (S, M, L, XL, XXL) and ten colors (white, yellow, orange, red, blue, purple, green, brown, beige, gray, and black), you must include 50 SHOPITEM elements in the XML.

Thorough division of variants allows for the correct filling of parameters and subsequent product filtering.

This is a mandatory tag, without which items will not be displayed on Heureka. A unique identifier for the product within your e-shop. It must remain unique forever, which allows us to unambiguously identify the product for the Verified by Customers service or the Availability XML file, even if the URL changes.

A combination of a maximum of 36 characters [ _ – 0-9 a-z A-Z ], i.e., underscores, hyphens, numbers 0-9, and lowercase and uppercase letters without diacritics. The tag is not yet used for item pairing.

The PRODUCTNAME tag should contain the basic name of the product, which includes all mandatory information according to the selected category. The maximum length of the text in this tag is limited to 200 characters.

PRODUCTNAME should not contain any supplementary information such as a free gift, case, or charger, etc.

In general, the name must not be generic. If you include the manufacturer, series, and product number in the product name, the product should be correctly categorized. If these are product variants that differ in color, dimensions, flavor, quantity, and other attributes, it is necessary to differentiate all these parameters in the product name.

Examples of correct product names can be found here.

The PRODUCT tag contains the PRODUCTNAME (exact product name) + possible supplementary information about product distribution or personal collection options, e.g., “Whirlpool WBA 43983 NFC IX – personal collection in Prague.”

The product description. Try to provide the most relevant description possible, as it is taken into account in full-text search. It should contain the description and specification of the product without advertising for free shipping, promotions, or the store. Excessive punctuation is not allowed. The number of characters in the DESCRIPTION tag is not limited, but we display only 200 characters in the full-text search results.

To activate Heureka Marketplace, it is essential that you send us the complete description in this tag, not just a shortened version (the same text as on the product detail page in the e-shop).

The link to the page with the offer for the given product in the store. This page must show the price of the product in CZK and the option to add it to the cart. The URL address must be unique for every product. If you have multiple product variants, ensure a unique URL for each variant. If you have product variants on a single page in your e-shop, the only solution is to use so-called hashtags.

This works by splitting each product variant separately in the XML feed, each with its own PRODUCTNAME (which includes the product code), and using a URL such as:

http://www.test.cz/product/tastickova-matrace-argon-latex-9-zon#1

http://www.test.cz/product/tastickova-matrace-argon-latex-9-zon#2

Browsers will only link to the text before the ‘#’ character, meaning both link to the same address http://www.test.cz/product/tastickova-matrace-argon-latex-9-zon, but for our system, the entire address including the text after the ‘#’ character will be considered; thus, the URL will be unique for us. The URL must not be longer than 300 characters.

We recommend discussing this adjustment with your webmaster.

The link to the main/primary image of the product.

Image requirements

• The image address must not contain spaces or diacritics.
• The maximum length of the image URL address is 255 characters.
• If you have one image for multiple products, always use the one and the same address (the address does not have to be unique within the feed).
• The image should also not have a transparent background.
• If the image on the store’s pages changes, the image URL address in the XML file must also be changed.

Specifications

• The minimum required image size is 20 x 50 or 50 x 20 pixels (but we recommend at least 175 x 175 pixels) and 30 kB.
• The maximum image size is 4,096 x 4,096 pixels and 2,000 kB.
• The maximum length of the image URL address is 255 characters.
• We currently support only the jpeg format.

Do not include images of the type https://www.srovnanicen.cz/static/css/image/bez-obrazku.gif in the feed!
Ensure that images do not rotate on a single URL (the same image must always be located at the same address), because our system can download the image from your pages at any time. You might then see incorrect (or no) images for products.

Images must be universal and generic; they must not contain a watermark, display of discounts or bonuses, or notifications of any product advantage, including awards. Otherwise, they will be blocked.

If your store is involved in the Heureka Marketplace model and sends images with a watermark, your offers will not be displayed in the upper TOP position, even if they are the most advantageous (they will only be displayed in the price comparison section).

The link to an additional image of the product, such as a view from a different angle, an overview of the entire package, etc. Can be included multiple times.

The final price of the product including VAT. The price must include copyright and recycling fees.
Prices are stated in CZK.
The prices on the Heureka.cz server are final.

The price can be provided in these formats:

• 25 000
• 25000
• 25000,50
• 25000.50

Do not use a period (‘.’) as a thousands/millions separator; it is used for decimal places. The price should have a maximum of 2 decimal places.

If your store is part of the Heureka Marketplace, you must send us the prices of goods rounded to whole crowns in this tag. If you also send a discount voucher with the product (see the SALES_VOUCHER tag), the price in the PRICE_VAT tag must correspond to the price after applying this voucher.
The price must be for a single product, and you cannot include a price with a quantity discount. Quantity discounts are not supported on Heureka.
Therefore, if the price changes for two or more pieces, do not list it on Heureka.

If your price is not updated in the comparison, a common mistake is that it hasn’t been generated in the feed yet, so we don’t have information about the change.

We recommend always checking that the price is already updated in the XML file and that a feed import has already taken place on our end.

VAT, the tax varies by product category.

VAT

The <VAT> tag is mainly supplementary for EET (electronic sales records). You can still send both <PRICE_VAT> and <VAT>.

<?xml version=”1.0″ encoding=”utf-8″?>

<VAT>21%</VAT>   

The VAT parameter is mandatory for stores selling goods with a different (reduced) VAT rate in the Heureka Cart. More info can be found here.

To distinguish new items. Use this tag to mark products that are:

• used or refurbished;
• with damaged, non-original, or bulk packaging (White box, OEM, blister, etc.);
• returned within the 14-day period;
• without a full warranty period;
• of second quality;
• display or demo pieces;
• unboxed (opened);
• goods under a special VAT regime;
• and others that Heureka does not consider new.

<ITEM_TYPE>bazar</ITEM_TYPE>

These products must not be marked as new; they must be marked as “bazar” or not included in the XML file for Heureka at all.

Here you can specify product parameters. If parameters are not filled in, your products cannot be displayed in specific filtering options.

List of parameters (XLSX/CSV)

The MANUFACTURER tag contains the name of the product manufacturer. It is used for filtering and not for pairing items. Therefore, the manufacturer must also be included in the PRODUCTNAME tag.

The MANUFACTURER_POSTAL_ADDRESS tag contains the manufacturer’s postal address, which customers can contact.

The MANUFACTURER_ELECTRONIC_ADDRESS tag provides the manufacturer’s electronic contact—this can be an email or a website with a contact form.

Product category. Always provide the full path to the product, ideally according to our category tree. You can, of course, also use your own categories, just make sure they match the Heureka categorization structure.

Correct categorization path:

Heureka.cz | Velké spotřebiče | Pračky a sušičky | Pračky
(Heureka.cz | Large appliances | Washing machines and dryers | Washing machines)

Incorrect categorization path:

Velké spotřebiče | Pračky a sušičky
(Large appliances | Washing machines and dryers)

The EAN code is used to identify individual types of goods. We support the EAN 13 format. Do not use internal product numbers, but official product codes! (More about EAN code)

The EAN code is a mandatory field for the categories Books, Textbooks, Maps and guides, Films, Music, and Comics.
If you sell other goods, the EAN is not mandatory, so you don’t need to send it.

An alphanumeric code used for the unique identification of book editions. We support ISBN-10 and ISBN-13 formats. Numbers in the ISBN code are separated by a hyphen, for example, “978-0-123456-47-2”. (More about ISBN code)

This tag allows you to set the maximum price you are willing to bid for a click. Use a comma to separate decimal places. The maximum price per click is 1,000 CZK. If you don’t want to bid, do not include the tag at all. Please do not enter the number 0.

Product delivery time in days, i.e., the time from receiving payment (or from receiving the order in the case of cash on delivery) until the goods are shipped. The numerical value is then automatically converted to a text expression by our system.

Availability on Heureka.cz is then displayed as:

• in stock – 0
• within 3 days – 1-3
• within a week – 4-7
• within 2 weeks – 8-14
• within a month – 15-30
• more than a month – 31 and more
• info in store – if you don’t provide a delivery time

Do not enter a value with a hyphen, but only one selected digit.

For example”2

Note: Detailed and up-to-date information on product availability can also be provided via a separate XML feed (more about availability XML), which is updated every 10 minutes. Examples:

• Goods in stock can be listed as:
  
  <DELIVERY_DATE>0</DELIVERY_DATE>
• Delivery time stated in days (only an integer value):
  
  <DELIVERY_DATE>4</DELIVERY_DATE>
• Delivery time stated by date – the product will be available on the market from this date:
  
  <DELIVERY_DATE>2013-08-15</DELIVERY_DATE>

Note: This designation is only used for cases where a product is newly launched on the market and is for sale only from a specific date, provided that pre-orders can be made. If products are long-term unavailable and the approximate delivery time is unknown, these products must not be included in the XML file.

The price and method of shipping that can be used for the delivery of this product. It is repeated as many times as there are shipping methods available for this product.

Each shipping method can only be listed once per product. If you list two carriers for one product, you will cause an error, and we will not display either shipping method. The maximum number of different shipping methods in the feed is 100.

If you choose to use shipping via the feed, the shipping filled in under “shipping prices” in the administration is completely ignored, as the DELIVERY tag takes precedence.

It contains the following tags:

• DELIVERY_ID – a string identifying the carrier. You can choose from our designated carriers; you cannot use any other.
• DELIVERY_PRICE – the total price (incl. VAT) for a specific delivery method for this product with advance payment.
• DELIVERY_PRICE_COD – the total price (incl. VAT) for a specific delivery method for this product, including cash on delivery. If the price for cash on delivery is the same as the regular price, repeat the price in this tag. If the goods cannot be delivered with this carrier on cash on delivery, do not include the tag.

Note: If you use multiple services from the same carriers, list the price of the cheapest one, but it must be a service that allows home delivery to customers throughout the Czech Republic (not just to a pickup point).

Here are the supported carriers with the following names:

Delivery to address

Pickup points

Pickup boxes

Other delivery options

Online delivery

Own transport

Note: If you offer your own transport for goods, your transport must again be available throughout the Czech Republic. This refers to your delivery to the customer. It is not personal pickup, city/region delivery, etc.

An identifier for a group of products that are variants of each other. A combination of a maximum of 36 characters [ _ – 0-9 a-z A-Z ], i.e., underscores, hyphens, numbers zero to nine, and lowercase and uppercase letters without diacritics.

Variants in XML Feed 2.0

Use variants to distinguish different sizes, colors, patterns, sets, and types of products. You then tag the same group in the ITEMGROUP_ID tag.

Example:

<?xml version=”1.0″ encoding=”utf-8″?>

Contains the ITEM_ID of an item that is an accessory to this product, e.g., a charger, case, etc. It can be included multiple times.

This allows your e-shop to sell accessories for items that a customer has in their cart. You choose these accessories yourself, whether they are chargers, cases, or anything relevant.

Up to 10 tags, containing the ITEM_ID of the item, can be assigned to each product. The customer is then shown a maximum of 10 specific products before purchase.

Contains a text description of gifts or items that are free with the product. The length limit for the name of one gift is 250 characters.

It can optionally contain an ID attribute for the unique identification of gifts (recommended). This attribute has the same format as ITEM_ID. A combination of a maximum of 36 characters [ _ – 0-9 a-z A-Z ], i.e., underscores, hyphens, numbers 0-9, and lowercase and uppercase letters without diacritics.

<?xml version=”1.0″ encoding=”utf-8″?>

A gift must be listed only for the specific product with which the customer will actually receive the gift. The gift must not be further restricted in any way (e.g., a higher order amount, the purchase of another product, etc.). It can be included multiple times if all gifts are delivered with one product. If there is a choice between gifts, only one gift is listed.

If you list multiple gifts, you cannot determine their position on the product card. If you decide to send multiple gifts with one product, you must send all listed gifts in the shipment (you cannot choose which gift to send).

A gift means an item or a voucher for a specific item, not a discount or service. The use of cashback is also allowed; however, it must only be listed with the product for which it is actually offered, and a specific amount or item that is the subject of the cashback must be stated.

If the cashback is from a specific brand and is offered to all users, the information is stated in the product description by Heureka, and it is not allowed to include it in the GIFT tag. If it is a brand-specific cashback for selected stores, it must be listed as: “XXX cashback upon registration on the XXX website.”

This tag contains information about the extended warranty of a product. If you want to display an extended warranty on Heureka, filling in this description is mandatory. You can also specify the extended warranty period, which is stated in months. The maximum description length is 128 characters.

If you enter a value greater than 999 in the VAL, Heureka will display a “lifetime warranty”.

<?xml version=”1.0″ encoding=”utf-8″?>

The Special Service tag contains information about a supplementary service provided with the purchase of a product. The number of offered services is limited to a maximum of 5, which also equals the maximum number of times this tag can appear for one product. If the maximum number of 5 services is exceeded, this tag will not be processed, and no supplementary service will be displayed for the product. The maximum description length is 128 characters.

<?xml version=”1.0″ encoding=”utf-8″?>

Examples of supplementary/special services:

• free service,
• carry-up to the floor,
• extended return period for goods,
• and others

What does not belong in this tag:

• free shipping (list in the DELIVERY tag only),
• availability information (list in the availability feed or DELIVERY_DATE),
• authorized dealer designation,
• installment plan option,
• personal pickup at branches,
• discount on a future purchase,
• extended warranty,
• and other forms of expressed discounts (instant discount, promotional price, bonus…)

A discount voucher for a product. With this tag, you can provide users with a discount code that they can use in your e-shop. The voucher always applies to the product it is listed with. If you provide a blanket discount on all products, the same voucher can be listed for all products in the store.

Warning: If you want to use the discount voucher, the price in the PRICE_VAT tag must correspond to the price after applying this voucher.

<?xml version=”1.0″ encoding=”utf-8″?>

CODE contains the discount code that the user enters in your e-shop. The maximum length is 24 characters.

DESC contains a description of the discount, which will be displayed with the code. If the voucher’s validity is time-limited, we recommend stating the expiration date here. The maximum length is. Excess characters will be truncated and supplemented with three dots (…).

Conditions for sending discount vouchers in the feed:

• The voucher must be usable by any customer.
• Its use must not be conditioned on, for example, the purchase of multiple items or types of products, registration in the store, membership in a loyalty club, etc.
• If the voucher’s validity is time-limited, it must no longer be in the feed after it expires. We recommend stating the expiration date in the DESC description.
• The product price sent in the PRICE_VAT tag must correspond to the price after applying this voucher.
• After clicking through from Heureka, the product price on your store’s website must be visibly displayed both before and after the discount (e.g., “price with code…”).