If you are not using a platform with native integration, you can integrate Retino with your online store using an XML feed in our format.
This article describes the XML feed structure and its import mechanism.
Feed Structure
The feed starts with an XML header with version 1.0 and UTF-8 encoding. We only support UTF-8 encoding. Then follows a paired tag ORDERS, containing all orders (each in a ORDER tag). Tags are case-sensitive. White-space between tags is ignored. Prices (type DECIMAL) are written with a decimal point (.), without thousands separators.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<ORDERS>
<ORDER>
(... order structure - see below ...)
</ORDER>
<ORDER>
(... order structure - see below ...)
</ORDER>
(... more orders ...)
</ORDERS>If you need to send an empty feed, include the header and an empty paired ORDERS tag.
Example:
<?xml version="1.0" encoding="UTF-8"?>
<ORDERS>
</ORDERS>
ORDER Structure
Example:
<ORDER>
<ORDER_ID>4347</ORDER_ID>
<ORDER_URL>https://example.com/admin/order-detail/4347</ORDER_URL>
<CODE>201800001</CODE>
<INVOICE_CODE>201800001</INVOICE_CODE>
<DATE>2018-03-02 21:46:52</DATE>
<CURRENCY>
<CODE>CZK</CODE>
</CURRENCY>
<PACKAGE_NUMBER>12345678</PACKAGE_NUMBER>
<LANGUAGE>EN</LANGUAGE>
<CUSTOMER>
<EMAIL>[email protected]</EMAIL>
<PHONE>777123456</PHONE>
<BILLING_ADDRESS>
<NAME>George Customer</NAME>
<COMPANY></COMPANY>
<STREET>Masarykova</STREET>
<HOUSENUMBER>1</HOUSENUMBER>
<CITY>Praha</CITY>
<ZIP>10000</ZIP>
<COUNTRY>CZ</COUNTRY>
<COMPANY_ID></COMPANY_ID>
<VAT_ID></VAT_ID>
</BILLING_ADDRESS>
<SHIPPING_ADDRESS>
<NAME>George Customer</NAME>
<COMPANY></COMPANY>
<STREET>Masarykova</STREET>
<HOUSENUMBER>1</HOUSENUMBER>
<CITY>Praha</CITY>
<ZIP>10000</ZIP>
<COUNTRY>CZ</COUNTRY>
</SHIPPING_ADDRESS>
</CUSTOMER>
<TOTAL_PRICE>
<WITH_VAT>457.00</WITH_VAT>
<WITHOUT_VAT>377.68</WITHOUT_VAT>
<VAT>79.32</VAT>
</TOTAL_PRICE>
<ORDER_ITEMS>
<ITEM>
(... item structure - see below ...)
</ITEM>
<ITEM>
(... item structure - see below ...)
</ITEM> (... more items ...) </ORDER_ITEMS>
<STATUSES>
<STATUS>
<NAME>NEW</NAME>
<DATE>2017-03-02 11:32:07</DATE>
</STATUS>
<STATUS>
<NAME>PAID</NAME>
<DATE>2017-03-02 12:30:00</DATE>
</STATUS>
<STATUS>
<NAME>PICKING</NAME>
<DATE>2017-03-02 14:15:30</DATE>
</STATUS>
<STATUS>
<NAME>PACKED</NAME>
<DATE>2017-03-02 15:21:30</DATE>
</STATUS>
<STATUS>
<NAME>DISPATCHED</NAME>
<DATE>2017-03-02 16:45:20</DATE>
</STATUS>
</STATUSES>
<INVOICES>
<INVOICE>
<CODE>201800001</CODE>
<URL>https://example.com/invoice/201800001</URL>
<CHANGE_TIME>2017-05-01 15:01:00</CHANGE_TIME>
</INVOICE>
</INVOICES>
</ORDER>Field descriptions:
Name | Type | Required? | Description |
ORDER_ID | VARCHAR(255) | Yes | Internal ID used in your system. We use it for linking systems via direct link. If this field is the same as the customer-visible order number (tag |
ORDER_URL | VARCHAR(255) | No | Link to the order detail in your online store admin |
CODE | VARCHAR(255) | Yes | Order number as seen by the customer |
INVOICE_CODE | VARCHAR(255) | No | Invoice number as seen by the customer |
DATE | DATETIME | Yes | Order date and time in ISO 8601 format |
CURRENCY/CODE | VARCHAR(3) | Yes | Order currency in ISO 4217 format |
PACKAGE_NUMBER | VARCHAR(255) | No | Shipment number for carrier tracking, separate multiple packages with a comma ("111,222") |
LANGUAGE | VARCHAR(255) | No | Order language |
CUSTOMER | see below | Yes | Customer information (see below) |
TOTAL_PRICE | see below | Yes | Total order price (see below) |
ORDER_ITEMS | see below | Yes | Order items (see below) |
STATUSES | see below | No | List of order statuses (see below) |
INVOICES | see below | No | List of invoices |
Description of the CUSTOMER tag:
VARCHAR(254) | Yes | Customer's email address, must be a valid email | |
PHONE | VARCHAR(255) | No | Customer's phone, ideally in E.164 format (but not validated) |
BILLING_ADDRESS | see below | Yes | Customer's billing address (see below) |
SHIPPING_ADDRESS | see below | Yes | Customer's shipping address (see below) – if the same as billing, include it here again |
Description of BILLING_ADDRESS and SHIPPING_ADDRESS tags:
NAME | VARCHAR(255) | Yes | Customer's name |
COMPANY | VARCHAR(255) | No | Company name |
STREET | VARCHAR(255) | Yes | Street |
HOUSENUMBER | VARCHAR(255) | No | House number (if you don't have separate street and house number, fill both into the |
CITY | VARCHAR(255) | Yes | City |
ZIP | VARCHAR(255) | Yes | Postal code |
COUNTRY | VARCHAR(255) | Yes | Country (in ISO-3166 format, but not validated) |
COMPANY_ID | VARCHAR(255) | No | Company ID (only in |
VAT_ID | VARCHAR(255) | No | VAT ID (only in |
Description of the TOTAL_PRICE tag:
WITH_VAT | DECIMAL | At least one of WITH_VAT / WITHOUT_VAT | Total order amount including VAT |
WITHOUT_VAT | DECIMAL | At least one of WITH_VAT / WITHOUT_VAT | Total order amount excluding VAT (if you are not VAT payer, fill in this tag only) |
VAT | DECIMAL | If WITH_VAT is filled | VAT (absolute amount) |
Description of the STATUS tag:
NAME | see below | Yes | One of the available order statuses |
DATE | DATETIME | Yes | Order status date and time in ISO 8601 format |
Order statuses:
OPEN - Order is open and active, meaning it hasn't been delivered or canceled yet.
CLOSED - Order is closed, meaning it has been delivered or successfully completed.
CANCELED - Order has been canceled and will not be further processed.
AWAITING_PAYMENT - Payment has not yet been received, waiting for customer payment.
PAID - Payment has been successfully received and processed.
PARTIALLY_REFUNDED - Part of the payment has been refunded to the customer.
REFUNDED - Full payment has been refunded to the customer.
FAILED - Payment attempt failed or was rejected by the payment gateway.
NEW - New order, not yet processed in the warehouse.
PICKING - Order is currently being picked from the warehouse, prepared, and packed.
PACKED - Order has been packed and is ready for shipment.
DISPATCHED - Order has been shipped to the customer.
ON_HOLD - Order processing is temporarily paused, waiting for an action or resolution. Not intended for waiting for payment.
READY_FOR_PICKUP - Order is ready for customer pickup at a branch or warehouse.
PICKED_UP - Order has been picked up by the customer in person.
Important Note. Canceled orders (status CANCELED) will not be visible to the customer in the portal.
Description of the INVOICE tag:
CODE | VARCHAR(255) | Yes | Invoice number |
URL | VARCHAR | Yes | URL for downloading the invoice |
CHANGE_TIME | DATETIME | No | Date of change. If you update the date, we will download the invoice again. |
Order Item Description (ITEM)
Example:
<ITEM>
<TYPE>product</TYPE>
<NAME>Product 1</NAME>
<CODE>988765</CODE>
<VARIANT_NAME></VARIANT_NAME>
<MANUFACTURER></MANUFACTURER>
<AMOUNT>1</AMOUNT>
<UNIT>pc</UNIT>
<WEIGHT>0</WEIGHT>
<UNIT_PRICE>
<WITH_VAT>407.00</WITH_VAT>
<WITHOUT_VAT>336.36</WITHOUT_VAT>
<VAT>70.64</VAT>
</UNIT_PRICE>
<TOTAL_PRICE>
<WITH_VAT>407.00</WITH_VAT>
<WITHOUT_VAT>336.36</WITHOUT_VAT>
<VAT>70.64</VAT>
</TOTAL_PRICE>
</ITEM>Field descriptions:
TYPE | ENUM | Yes | Item type (list of options see below) |
NAME | VARCHAR(255) | Yes | Item name |
CODE | VARCHAR(255) | Yes | Product code |
VARIANT_NAME | VARCHAR(255) | No | Variant name (e.g., color or size for fashion items) |
MANUFACTURER | VARCHAR(255) | No | Manufacturer |
AMOUNT | DECIMAL | Yes | Quantity |
UNIT | VARCHAR(10) | Yes | Unit (e.g., pc or g) |
WEIGHT | DECIMAL | No | Weight in kg |
UNIT_PRICE | see below | Yes | Price per unit |
TOTAL_PRICE | see below | Yes | Total price for all units (full quantity) |
IMGURL | VARCHAR(255) | No | Product image URL |
Item types:
product | Product (this can be returned/claimed by the customer) |
discount | Discount |
shipping | Shipping |
billing | Payment (cash on delivery, etc.) |
other | Other items |
Description of UNIT_PRICE and TOTAL_PRICE tags:
WITH_VAT | DECIMAL | At least one of WITH_VAT / WITHOUT_VAT | Price including VAT |
WITHOUT_VAT | DECIMAL | At least one of WITH_VAT / WITHOUT_VAT | Price excluding VAT (non-VAT payers fill in this one only) |
VAT | DECIMAL | If WITH_VAT is filled | VAT (absolute amount) |
Initial Sync Feed
Claims typically can be processed up to 2 years back. Therefore, we need access to older orders. Please send us a one-time feed with historical orders for the period you wish to have available in Retino. We recommend the last 30 months. Please send the feed to our support team at [email protected].
Incremental Sync Feed
Once the initial synchronization is complete, we need to keep the database up-to-date. For this purpose, we need an incremental feed that our system will automatically retrieve. It works as follows:
We download the feed from the URL approximately every 6 hours. This interval may change in the future. You have two options for generating the feed:
A statically generated feed containing orders from the last X days. We recommend X = 7.
A dynamically generated feed where you always send us orders that "we haven't seen yet," meaning you keep a timestamp of the last feed retrieval and then send us orders changed since then.
We recommend option 1.
Important Information. If you send us an order that we have already seen, we will not create a new one, but update the existing one. We match orders based on the CODE tag.
Security of Transfer
Data transfer is via HTTPS and can be secured using HTTP Basic authentication. We recommend this security measure for data protection. If this is not possible in your case, we recommend at least setting the feed URL to an "unguessable" address, e.g., www.store.com/9b9972387feb11eabc550242ac130003.xml.
Your server must return a response within 60 seconds.
Data and Time Formats
Retino supports several date and time formats in the XML feed:
ISO 8601 format:
2023-04-23T14:30:45Date and time with a space:
2023-04-23 14:30:45Date only:
2023-04-23
If the date is given without a time zone, it is considered to be in the server's current time zone.
Processing of Special Values
Retino provides automatic processing of some values:
DECIMAL values - are automatically converted from comma-separated to dot-separated format
Countries - if you provide a country code, it is automatically normalized
All text values are trimmed to a maximum length of 255 characters
Attention to Special Characters
Please note that the XML format does not allow certain characters like <, >, or & within strings. The easiest solution is to wrap all tags where special characters might appear in CDATA entities.
Incorrect example (XML parser will throw an error):
<NAME>Slim&Sun 100 tablet</NAME>
Correct example (handled using CDATA):
<NAME><![CDATA[Slim&Sun 100 tablet]]></NAME>
Feed Validation
For validating the data format in your XML feed, you can use an XSD file. Download the feed schema file below:
Alternatively, you can use the validator on our website.
Example Feed
<?xml version="1.0" encoding="UTF-8"?>
<ORDERS><ORDER>
<ORDER_ID>4347</ORDER_ID>
<CODE>201800001</CODE>
<INVOICE_CODE>2018-001</INVOICE_CODE>
<DATE>2018-03-02 21:46:52</DATE>
<CURRENCY>
<CODE>CZK</CODE>
</CURRENCY>
<PACKAGE_NUMBER>12345678</PACKAGE_NUMBER>
<LANGUAGE>EN</LANGUAGE>
<CUSTOMER>
<EMAIL>[email protected]</EMAIL>
<PHONE>777123456</PHONE>
<BILLING_ADDRESS>
<NAME>Jiří Zákazník</NAME>
<COMPANY></COMPANY>
<STREET>Masarykova</STREET>
<HOUSENUMBER>1</HOUSENUMBER>
<CITY>Praha</CITY>
<ZIP>10000</ZIP>
<COUNTRY>CZ</COUNTRY>
<COMPANY_ID></COMPANY_ID>
<VAT_ID></VAT_ID>
</BILLING_ADDRESS>
<SHIPPING_ADDRESS>
<NAME>Jiří Zákazník</NAME>
<COMPANY></COMPANY>
<STREET>Masarykova</STREET>
<HOUSENUMBER>1</HOUSENUMBER>
<CITY>Praha</CITY>
<ZIP>10000</ZIP>
<COUNTRY>CZ</COUNTRY>
</SHIPPING_ADDRESS>
</CUSTOMER>
<TOTAL_PRICE>
<WITH_VAT>457.00</WITH_VAT>
<WITHOUT_VAT>377.68</WITHOUT_VAT>
<VAT>79.32</VAT>
</TOTAL_PRICE>
<ORDER_ITEMS><ITEM>
<TYPE>product</TYPE>
<NAME>Product 1</NAME>
<AMOUNT>1</AMOUNT>
<CODE>988765</CODE>
<VARIANT_NAME></VARIANT_NAME>
<MANUFACTURER></MANUFACTURER>
<UNIT>pc</UNIT>
<WEIGHT>0</WEIGHT>
<UNIT_PRICE>
<WITH_VAT>407.00</WITH_VAT>
<WITHOUT_VAT>336.36</WITHOUT_VAT>
<VAT>70.64</VAT>
</UNIT_PRICE>
<TOTAL_PRICE>
<WITH_VAT>407.00</WITH_VAT>
<WITHOUT_VAT>336.36</WITHOUT_VAT>
<VAT>70.64</VAT>
</TOTAL_PRICE>
</ITEM><ITEM>
<TYPE>shipping</TYPE>
<NAME>Zásilkovna - Praha</NAME>
<AMOUNT>1</AMOUNT>
<CODE>SHIPPING16</CODE>
<VARIANT_NAME></VARIANT_NAME>
<MANUFACTURER></MANUFACTURER>
<UNIT></UNIT>
<WEIGHT>0</WEIGHT>
<UNIT_PRICE>
<WITH_VAT>25.00</WITH_VAT>
<WITHOUT_VAT>20.66</WITHOUT_VAT>
<VAT>4.34</VAT>
</UNIT_PRICE>
<TOTAL_PRICE>
<WITH_VAT>25.00</WITH_VAT>
<WITHOUT_VAT>20.66</WITHOUT_VAT>
<VAT>4.34</VAT>
</TOTAL_PRICE>
</ITEM><ITEM>
<TYPE>billing</TYPE>
<NAME>Dobírkou</NAME>
<AMOUNT>1</AMOUNT>
<CODE>BILLING3</CODE>
<VARIANT_NAME></VARIANT_NAME>
<MANUFACTURER></MANUFACTURER>
<UNIT></UNIT>
<WEIGHT>0</WEIGHT>
<UNIT_PRICE>
<WITH_VAT>25.00</WITH_VAT>
<WITHOUT_VAT>20.66</WITHOUT_VAT>
<VAT>4.34</VAT>
</UNIT_PRICE>
<TOTAL_PRICE>
<WITH_VAT>25.00</WITH_VAT>
<WITHOUT_VAT>20.66</WITHOUT_VAT>
<VAT>4.34</VAT>
</TOTAL_PRICE>
</ITEM></ORDER_ITEMS>
</ORDER>
</ORDERS>
Portal Integration
Once the data integration is complete, you will need to integrate the customer-facing Retino portal. To display the Retino portal on your website, insert the integration script into your online store page. That's it!
Frequently Asked Questions (FAQ)
Are canceled orders removed from Retino?
No, canceled orders are not removed from Retino. The XML feed does not allow deleting orders, only adding or updating them. If you have a canceled order in your online store, we recommend continuing to send it in the XML feed with the current status to keep the data consistent in the system.
Troubleshooting Connection Issues
If you encounter any problems connecting, please contact us at [email protected]. Our team will gladly assist you with setup or resolving any technical issues.