Additional XML file for product availability

Display and XML feed settings, Product card data display

Detailed information about the availability of goods in the e-shop and at individual brick-and-mortar branches can be transmitted via a separate XML file. This file is automatically generated from your site, so consult your webmaster about its creation or modification. We process the availability XML file only in the case of PPC mode.

The availability XML file is downloaded every ten minutes and must always contain current and correct data and meet the following specifications. We require support for GZip transmission compression to download the file.

If an error occurs in the availability file and you have an active Heureka Marketplace, then unfortunately this may affect your services. Orange buttons may disappear for all or some products. Depending on whether the feed was only partially downloaded.

Stores that use the API connection in the Marketplace do not have to send us the availability file at all. We verify all necessary information via API.

Which items to list and which not to

The availability XML file is used exclusively for items that are ready for immediate dispatch by a shipping carrier or are physically in stock at a brick-and-mortar branch, or for those for which you know the exact date of delivery to the customer (or the exact date when the product will be ready for collection at the branch).

The time between the order (the so-called orderDeadline, more below) and the delivery of the goods to the customer must not exceed 3 days.

Products that do not meet the above-mentioned conditions are not considered “in stock”, their inclusion in the availability XML file will be evaluated as an error and the XML file will not be downloaded and parsed until they are removed.

Only list products for which you supply a unique <ITEM_ID> in the main XML file.

Availability XML must be 100% valid. Otherwise, it will not be parsed at all and therefore no data on the availability of the goods will be available. The validity of the availability XML can be checked via the “Check XML file” link in the administration interface at https://sluzby.heureka.cz/obchody/dostupnost/. You can also use the RelaxNG availability XML schema, which can be downloaded here.

Example of the basic format of an availability XML file:

<?xml version="1.0" encoding="utf-8"?>
<item_list>
  <item id="536234275543">
    <stock_quantity>13</stock_quantity>
    <delivery_time orderDeadline="2011-09-10 12:00">2011-09-11 13:00</delivery_time>
    <depot id="434">
      <stock_quantity>2</stock_quantity>
    </depot>
    <depot id="437">
      <pickup_time orderDeadline="2011-09-10 12:00">2011-09-11 18:00</pickup_time>
    </depot>
    <depot id="436">
      ....
    </depot>
    ....
  </item>
  <item id="536234275547">
    ....
  </item>
  ....
</item_list>

Description of individual elements:

item_list

Root element, contained in the file only once.

item

Contains availability information for a specific product and is included in the file as many times as you have available products.

id parameter (required) Identifies a specific product. The value must match the value of the <ITEM_ID> element of one of the products listed in your main XML file.

stock_quantity

Number of items ready for immediate dispatch. The allowed value is an integer greater than zero. Never specify a zero quantity – completely omit such products from the availability XML file.

delivery_time

Date and time of product delivery to the customer if ordered before the date and time specified in the orderDeadline parameter. The value must be in the YYYY-MM-DD HH:MM format.

orderDeadline parameter (required) Date and time by which the product order must be placed at the latest to guarantee the specified delivery time. The value must be in the YYYY-MM-DD HH:MM format.

Time from order to delivery For a product to be considered “in stock”, the time between ordering (orderDeadline) and delivery must not exceed 2 days. Do not include products in the availability XML file that cannot be delivered within 2 days of ordering.

Invalid orderDeadline The value specified in the orderDeadline parameter must not be invalid. For example, on May 10, 2012 at 19:00, you cannot enter an orderDeadline corresponding to May 10, 2012 at 17:00 in the availability XML file.

depot

Information about product availability at a specific brick-and-mortar branch. Inside each <item></item> element, it is included as many times as the number of branches where the product is available.

id parameter (required) Identifies a specific branch. The value must match one of the values listed under your branches in your online store administration at https://sluzby.heureka.sk/obchody/pobocky/.

pickup_time

Date and time when the product will be ready for pickup at this brick-and-mortar branch if ordered before the date and time specified in the orderDeadline parameter. The value must be in the YYYY-MM-DD HH:MM format.

orderDeadline parameter (required) Date and time by which the product order must be placed at the latest for it to be ready for pickup at the brick-and-mortar branch at the specified time. The value must be in the YYYY-MM-DD HH:MM format.

Time from order to pickup For a product to be considered “in stock”, the time between ordering (orderDeadline) and pickup at the branch must not exceed 2 days. For products that cannot be picked up at the branch within 2 days of ordering, do not include the tag for that branch at all.

1) Zero number of items in the e-shop

<item_list>
  <item id="ABC001">
    <stock_quantity>5</stock_quantity>
  </item>
  <item id="ABC002">
    <stock_quantity>0</stock_quantity>
  </item>
  <item id="ABC003">
    <stock_quantity>7</stock_quantity>
  </item>
</item_list>

Solution:

Completely omit the product in the availability XML file.

<item_list>
  <item id="ABC001">
    <stock_quantity>5</stock_quantity>
  </item>
  <item id="ABC003">
    <stock_quantity>7</stock_quantity>
  </item>
</item_list>

2) Zero number of pieces in the e-shop, non-zero number of pieces at the branch

<item_list>
  <item id="ABC001">
    <stock_quantity>0</stock_quantity>
    <depot id="434">
      <stock_quantity>2</stock_quantity>
    </depot>
  </item>
</item_list>

Solution:

Omit information about availability in the e-shop, in the XML file only indicate the number of pieces available at the branch.

<item_list>
  <item id="ABC001">
    <depot id="434">
      <stock_quantity>2</stock_quantity>
    </depot>
  </item>
</item_list>

3) Zero number of pieces at the branch

<item_list>
  <item id="ABC001">
    <stock_quantity>5</stock_quantity>
    <depot id="434">
      <stock_quantity>0</stock_quantity>
    </depot>
  </item>
</item_list>

Solution:

Completely omit information about availability at the branch.

<item_list>
  <item id="ABC001">
    <stock_quantity>5</stock_quantity>
  </item>
</item_list>

4) The stated orderDeadline has already passed

On 5/9/2012 at 7:00 p.m., the available XML file states:

<item_list>
  <item id="ABC001">
    <delivery_time orderDeadline="2012-05-09 17:00">2012-05-10 13:00</delivery_time>
  </item>
</item_list>

Solution:

After exceeding the orderDeadline for the current day, generate the data valid for the following day in the availability XML file.

<item_list>
  <item id="ABC001">
    <delivery_time orderDeadline="2012-05-10 17:00">2012-05-11 13:00</delivery_time>
  </item>
</item_list>

5) The day of delivery is the same as the deadline of the order

<item_list>
  <item id="ABC001">
    <stock_quantity>4</stock_quantity>
    <delivery_time orderDeadline="2013-05-06 14:00">2013-05-06 18:00</delivery_time>
  </item>
</item_list>

Solution:

It is not possible to indicate the same day of delivery as the deadline of the order. The day of delivery must be valid for the entire Czech Republic, not just for one city.

6) Unlisted stock items

If you do not include items in the availability feed that are in stock in the basic feed, we will always display “store info” for the products, even if you have <DELIVERY_DATE>0</DELIVERY_DATE> listed in the basic feed.

7) ITEM_ID does not match

Always check carefully that the ITEM_ID in the basic feed is identical to the ITEM_ID in the availability feed.

8) The date of order and delivery is displayed, but at the same time Info in the store

Solution:

The In Stock information is only displayed if the delivery date is less than 3 business days.

Online XML Availability Check

The availability XML file can be validated directly here. Just enter the URL where the XML is located in the following field.

To validate the XML file for technical reasons, we need to know its size before starting the download. Therefore, it is necessary for the server to return the Content-Length header with the corresponding value in the response to the http request.

URL file to check:

Note: this validator only validates the correct structure of the XML file, not the correctness of the given data, such as delivery time or orderDeadline. This data is only checked to see if its format matches the specification.

Additional XML file for product availability

Which items to list and which not to

Example of the basic format of an availability XML file:

Description of individual elements:

1) Zero number of items in the e-shop

2) Zero number of pieces in the e-shop, non-zero number of pieces at the branch

3) Zero number of pieces at the branch

4) The stated orderDeadline has already passed

5) The day of delivery is the same as the deadline of the order

6) Unlisted stock items

7) ITEM_ID does not match

8) The date of order and delivery is displayed, but at the same time Info in the store

Online XML Availability Check

Související články

Basic XML File Specifications

Feed integration requirements

How to set a daily credit limit?