XML File Import
If your system exports orders or addresses as XML, you can import them with the File Import function — the same way as CSV files, but with an XML import profile.
The difference to CSV is how the profile learns your field names:
| CSV | XML | |
|---|---|---|
| Field name column | A dropdown, filled from the header row of a sample file | A free-text box — you type the element name or path |
| Sample upload in the profile | Yes (Upload File → Process File) | Not needed — the profile has no upload step |
| Structure | Flat columns | Nested elements and attributes are supported |
Create a Profile
Before importing the file, you must create an import profile.
- Go to Profiles → Addresses or Shipments → press +
- Choose Import Type → Addresses or Shipments
- Add a Profile Name (e.g. Orders XML)
- Choose Import File Type → XML
- Fill in XML row element (tag or XPath) — the element that repeats once per shipment or address (see Choosing the row element)
The Decimal separator and Multiple value delimiter can remain as default (. and ,).
XML row element is mandatory — you cannot continue without it.
- Press Continue
- Fill in the Field name column with the element name or path of each field you want to import
For XML profiles Field name is a free-text box, not a dropdown, and there is no Upload File / Process File button. Type the name exactly as it appears in your file — see How element names become field names.
The Function column can remain untouched.
If needed, you can add a Transformation — created and used when data from the XML file must be adapted for import. For example, use this when the country name in your file is "Switzerland" but the system requires ISO 3166-1 alpha-2 format ("CH").
When all mandatory (and optional) field names are entered, press Save.
Shipment Fields You Can Map
The list of fields you can fill in is exactly the same as for CSV — sender and receiver address, service, parcel and customs details, with the same maximum lengths and the same mandatory fields. See Shipment Fields You Can Map on the CSV page.
Weight is required for every parcel — make sure your XML has a weight element or attribute (in kg) before importing.
Upload the XML File
- Go to File Imports
- Press Import File in the top-right corner
- Choose the Profile (the XML profile you created in step 1)
- Upload the
.xmlfile and press Import
- Press Refresh
The imported information will appear in your address book or shipments. Rows that could not be imported are listed with their error message, and the rest of the file is still imported.
Technical Requirements for XML File
The file must be a well-formed XML document with the extension .xml, and no larger than 25 MB.
Choosing the row element
The XML row element tells the import where one shipment (or one address) begins and ends. Every matching element becomes one row.
You can enter it in two ways:
| What you enter | Meaning | Use when |
|---|---|---|
A plain tag name, e.g. shipment | Every element with that name | Your rows sit directly in a simple document |
An XPath expression, e.g. //order or /root/data/orders/order | Every element the expression selects | Your rows are nested deeper, or the same tag name is used in more than one place |
For this file the row element is shipment:
<?xml version="1.0" encoding="UTF-8"?>
<shipments>
<shipment>
<receiver_name>Andreas Brauchle</receiver_name>
<receiver_countryCode>CH</receiver_countryCode>
<receiver_zipCode>8055</receiver_zipCode>
<receiver_city>ZÜRICH</receiver_city>
<receiver_street>Schaufelbergerstrasse 30</receiver_street>
<service_code>B2B</service_code>
<weight>2.3</weight>
</shipment>
<shipment>
...
</shipment>
</shipments>
Use the repeating element, not the wrapper around it. Above, shipment is correct and shipments is wrong.
A wrapper matches only once, so the entire file collapses into a single row that keeps only the last entry's values. Nothing reports the loss: when that one row is valid the import is marked Successful, and a record count is only shown for partially imported files — so a collapsed file looks completely normal. If a file with 5 entries imports as 1, this is the reason.
For an address file wrapped as <Recipients><Recipient>…, the row element is therefore Recipient — or //Recipient, which finds it at any depth:
For this file the row element is //order (or /root/data/orders/order):
<?xml version="1.0" encoding="UTF-8"?>
<root>
<data>
<orders>
<order id="ORD-001">
<recipient>
<address>
<name>John Doe</name>
<street>Main Street 1</street>
<zip>8000</zip>
<city>Zurich</city>
<country>CH</country>
</address>
<contact>
<email>john@example.com</email>
</contact>
</recipient>
<parcel weight="2.5" service="B2B">
<reference>REF-001</reference>
</parcel>
</order>
</orders>
</data>
</root>
If the row element matches nothing, the import fails with "No XML elements matched the configured row element". Check the spelling and the upper/lower case — XML element names are case-sensitive.
How element names become field names
Field names are written relative to the row element, using / between levels and @ for attributes. Using the nested order example above:
| In the file | What you type as the source field | Value |
|---|---|---|
id attribute on the row element | @id | ORD-001 |
<city> directly under the row element | city | — |
<recipient><address><city> | recipient/address/city | Zurich |
<recipient><contact><email> | recipient/contact/email | john@example.com |
weight attribute on <parcel> | parcel/@weight | 2.5 |
<parcel><reference> | parcel/reference | REF-001 |
Rules that apply to every value:
- Values are trimmed, and invisible characters (non-breaking spaces, zero-width spaces, control characters) are removed
- Empty elements (
<recipient_name2></recipient_name2>or<customs_date />) are treated as not supplied - Text split over several lines is joined into one value
- Elements you don't map are simply ignored
Be consistent within one profile: if your XML is nested, write the full path for every field. Mixing a plain leaf name (city) with a path (recipient/address/city) in the same profile can leave the plain one empty, because for nested files the value is only available under its full path.
Advanced: picking one of several repeated elements
When the same element repeats inside a row and you need one specific occurrence, add an XPath predicate to the source field. Given:
<shipment id="ORD-001">
<addresses>
<address kind="billing">
<city>Zurich</city>
</address>
<address kind="shipping">
<city>Bern</city>
</address>
</addresses>
<parcels>
<parcel type="standard" weight="1.0">
<reference>REF-STD-001</reference>
</parcel>
<parcel type="express" weight="2.5">
<reference>REF-EXP-001</reference>
</parcel>
</parcels>
<items>
<item>First item</item>
<item>Second item</item>
</items>
</shipment>
| Source field | Selects | Value |
|---|---|---|
addresses/address[@kind='shipping']/city | The shipping address, not the billing one | Bern |
parcels/parcel[@type='express']/@weight | The weight of the express parcel | 2.5 |
parcels/parcel[@type='express']/reference | The reference of the express parcel | REF-EXP-001 |
items/item[1] | The first item by position | First item |
Field paths must stay inside the row. A path that starts with / or // is refused when you save the profile, with "Mapping XPaths must be relative to the root row element" — this prevents a row from accidentally picking up another row's data. Absolute paths and // are allowed only in the row element setting itself.
XML with namespaces
If your elements carry a namespace prefix (<ns:order>), select the row element by local name instead of by prefix:
//*[local-name()='order']
Field paths can be written the same way, e.g. *[local-name()='recipient']/*[local-name()='city'].
Character Encoding
XML files state their own encoding in the declaration on the first line:
<?xml version="1.0" encoding="UTF-8"?>
| Profile Encoding setting | What happens |
|---|---|
| Detect automatically (recommended for XML) | The encoding from the XML declaration is used |
| A specific encoding (UTF-8, ISO-8859-1, Windows-1250/1251/1252) | That encoding is used |
Set the profile Encoding to Detect automatically and keep the declaration in your file correct. If you pick a specific encoding, it must match the file — otherwise special characters break (Müller becomes Müller).
You can also override the encoding for a single file with Import encoding in the Import File dialog, without changing the profile — leave it on Use profile setting to keep the profile's value.
XML Configuration Parameters
| Parameter | Type | Description | Example values |
|---|---|---|---|
xmlTag | String | The row element — plain tag name or XPath | shipment, //order |
decimalSeparator | String | Decimal point for numbers such as weight | . (default) or , |
multiValueDelimiter | String | Separator inside a single element that holds several values, e.g. option codes | , (default), ;, | |
Weight with a dot (decimalSeparator = .):
<weight>2.5</weight>
Weight with a comma (decimalSeparator = ,):
<weight>2,5</weight>
Several option codes in one element (multiValueDelimiter = ,):
<option_codes>136,140</option_codes>
Security Restrictions
For security reasons the import rejects files that contain a document type definition (<!DOCTYPE ...>) or custom entities, and never loads anything referenced from outside the file. Export your data without a DTD.
Common Issues & Solutions
"No XML elements matched the configured row element"
The row element in the profile doesn't exist in the file. Open the file in a text editor and check the exact spelling and case of the repeating element. If your rows are nested deeper, use an XPath such as //order instead of a plain tag name.
A mapped field stays empty
The source field text does not match the file exactly. Check that you wrote the full path relative to the row element (recipient/address/city, not city), that attributes start with @ (parcel/@weight), and that the case matches.
"Invalid content type for XML"
The uploaded file was not recognised as XML. Make sure it has the .xml extension and starts with a proper XML declaration or root element — a file that is really CSV or plain text renamed to .xml is rejected.
"Failed to parse XML file"
The file is not well-formed (an unclosed tag, a stray &, a truncated export) or contains a <!DOCTYPE ...> declaration. Open it in a browser or XML editor — it will point at the first broken line. Escape & as &, < as <.
"Mapping XPaths must be relative to the root row element"
A field path starts with / or //. Remove the leading slashes so the path is relative to the row element: recipient/address/city instead of //city.
Special characters look wrong — e.g. Müller shows up as Müller
The profile encoding doesn't match the file. Set Encoding to Detect automatically so the XML declaration decides, or pick the encoding your file is actually saved in.
Weight is not recognised as a number
Your decimal sign doesn't match the profile. Set Decimal separator to match the file: a comma (,) if the file writes 2,5, a dot (.) if it writes 2.5.
Fewer records were imported than the file contains
The row element is pointing at the wrapper instead of the repeating element, so the whole file was read as one row. Compare the two element names in your file — for <shipments><shipment>… the row element is shipment. See the warning under Choosing the row element.
Only some rows failed
That is expected behaviour: each row is imported on its own, and a row that fails validation (missing weight, unknown country, invalid postal code) is listed as failed with its error message while the other rows are imported. Fix those rows and import the file again.
The file is then marked Partially imported, with Incorrect values and the count of affected rows. Open it to see one entry per failed row, each with the reason and a Raw data view of the values that were read:
In the example above the file used numeric country codes (528, 276) where the system expects a two-letter ISO code — the kind of difference a Transformation on the country field fixes.
Pre-Import Checklist
Before importing, verify:
- The file is well-formed XML and has the
.xmlextension - No
<!DOCTYPE ...>declaration in the file - The XML declaration states the correct encoding, and the profile Encoding is on Detect automatically
- The row element in the profile matches the repeating element in the file, not its wrapper (exact case)
- After importing, the number of records matches the number of entries in the file
- Every mapped source field is written relative to the row element, with
/for levels and@for attributes - All mandatory fields are mapped — receiver name, street, postal code, city, country and weight
- Weight is in kg, and the decimal separator matches the profile
- Special characters (ä, ö, ü, é) display correctly in a text editor
- File size is under 25 MB