pixi
Ask AI
What's an 'Ideas Portal'?
DE

Order Import - openTRANS Syntax Specification

This documentation describes the structure of the XML file for importing customer orders from your shop or other sales channels to pixi*.


Structure of the XML

Every valid ORDER openTRANS document is started by the root element ORDER and consists of a header (ORDER_HEADER), an item level (ORDER_ITEM_LIST) and a summary (ORDER_SUMMARY). The openTRANS version and information about the used XML version (XML Info) is optional in pixi* (but not the root tag <ORDER>...</ORDER>).


<?xml version="1.0" encoding="UTF-8" ?>
<ORDER version="1.0" type="standard">
   <ORDER_HEADER>
      ...
   </ORDER_HEADER>
   <ORDER_ITEM_LIST>
      ...
   </ORDER_ITEM_LIST>
   <ORDER_SUMMARY>
      ...
   </ORDER_SUMMARY>
</ORDER>

According to the official openTRANS specification the ORDER_SUMMARY is the closing part of each document which summarizes information on the order, e.g. the number of items. In pixi* this section it is not used and does not need to be provided.

For complex text blocks containing special characters such as &'<"®™>¿ we recommend the use of CDATA rather than encodiing via XML/HTML entities.


Header part: ORDER_HEADER

The <ORDER_HEADER> describes all general information which is related to the whole document. This includes e.g. order number, order date, shipping and billing address, currency, payment type, shop comment.


Example:

<ORDER_HEADER> 	
   <CONTROL_INFO> 	
      <GENERATOR_INFO>Name of the Shop - openTRANS-Export</GENERATOR_INFO> 
      <GENERATION_DATE>2015-02-04T10:16:14+01:00</GENERATION_DATE> 
   </CONTROL_INFO> 
   <ORDER_INFO> 		
      <ORDER_ID>Order Number</ORDER_ID>
      <ORDER_SHOPID>Order ID</ORDER_SHOPID> 
      <ORDER_DATE>date timestamp</ORDER_DATE> 	
      <DATABASE>pixi_XYZ</DATABASE> 	
      <SHOPID>ABC</SHOPID> 		
      <SHOP_NOTE>Shop Comment</SHOP_NOTE>
      <ORDERTAGS>
          <ORDERTAG>Tag 1</ORDERTAG>
          <ORDERTAG>Tag 2</ORDERTAG>
      </ORDERTAGS>
      <ORDER_SHIPLOCK>Y</ORDER_SHIPLOCK>
      <BUYER_SHIPLOCK>Y</BUYER_SHIPLOCK>
      <PRICE_CURRENCY>EUR</PRICE_CURRENCY>
      <PRICE_CURRENCY_ORIGINAL>GBP</PRICE_CURRENCY_ORIGINAL>
      <EXCHANGE_RATE>0.23</EXCHANGE_RATE>
      <TRANSPORT_REMARKS>Shipping Information</TRANSPORT_REMARKS>
      <GIFT_MESSAGE>Custom gift message</GIFT_MESSAGE>
      <SUBSHOPLOGO>Sub shop logo</SUBSHOPLOGO>
      <SUBSHOPNAME>Sub shop name</SUBSHOPNAME>
      <REFERRER>Referrer</REFERRER>
      <LOCATION>LocationID</LOCATION>
      <PARTIAL_DELIVERY>OFF</PARTIAL_DELIVERY>
      <ORDER_TYPE>B2C</ORDER_TYPE>
      <ORDER_PARTIES>
        ...
      </ORDER_PARTIES> 
      <PAYMENT>
        ...
      </PAYMENT> 	       	
      <REMARK>
        ...
      </REMARK> 
   </ORDER_INFO>
</ORDER_HEADER>

Name of XML Tag

Description

GENERATOR_INFO

(Optional) Information about the creator of the XML file; Value: [Name of your shop systems] – openTRANS-Export

GENERATION_DATE

(Optional) Creation date of the XML file in format YYYY-MM-DDTHH:MM:SS+HH:MM

ORDER_ID

Mandatory - Unique order number, imported in field "External order number" in pixi* Customer Service

 
ORDER_SHOPID

(Optional) An ID for the order in the external system that is not stored in pixi but which is returned in the URL Call to confirm a successful Export as $$$order_id$$$ if specified, otherwise as ORDER_ID

ORDER_DATE

Mandatory - Order date in format YYYY-MM-DDTHH:MM:SS+HH:MM

DATABASE

(Optional) Name of the pixi* database, e.g. pixi_ABC

 
SHOPID

ID of the shop in pixi*, e.g. XYZ

Mandatory if <ORDER_PARTIES><BUYER_PARTY><PARTY><SHOPID> is not in the XML file.

 
SHOP_NOTE

(Optional) Comment from the customer that should be imported with the order, is imported to field "Shop comments" in pixi* Customer Service > tab Orders > tab General.

 
ORDERTAGS

(Optional) Tags that are assigned to the order. In case a tag does not yet exist in pixi, it will be automatically created with order import. Name and description of the tag will be taken from the XML.

Tags can also be manually created: Manage Tags

 
ORDER_SHIPLOCK

(Optional) Set a customer lock. Possible values:

  • "Y" to enable customer lock,

  • "N" or empty to not enable the customer lock.

Used if <ORDER_PARTIES><BUYER_PARTY><PARTY><ADDRESS><BUYER_SHIPLOCK> is not provided in the XML file.

 
BUYER_SHIPLOCK

(Optional) Set a ship lock for this order. Possible values:

  • "Y" to enable ship lock,

  • "N" or empty to not enable the ship lock.

 
PRICE_CURRENCY

Mandatory - sets the currency of the order.

When order currency is changed in the shop and the order is re-imported into pixi* with the new currency, the existing order currency of the order in pixi* is updated.

 
PRICE_CURRENCY_ORIGINAL

Obsolete

(Optional) Foreign currency of the order. If no value is provided <ORDER><ORDER_HEADER><ORDER_INFO><PRICE_CURRENCY> is used.

 
EXCHANGE_RATE

(Optional) Exchange rate of the order. If no value is provided, the database exchange rate is used for the order. The value needs to be provided with 2 decimal places and with dot as decimal seperator. (from AVA Update 7 on)

TRANSPORT_REMARKS

(Optional) Contains specific information about the processing of customer orders with delivery dates or automatic processing as express orders for shipping vendor DHL, e.g.

<TRANSPORT_REMARKS>DHL Express;;;[Method]|[Product]|[Tools]|[Shipping date]
</TRANSPORT_REMARKS>

Example:

<TRANSPORT_REMARKS> DHL Express;;;72|7202|7210|01.01.2016 </TRANSPORT_REMARKS>

Is imported to the fields Method ("72"), Product ("7202"), Tools ("7210") and Shipping date ("01.01.2016").

If you only want to import the Shipping date, values need to be provided as follows:

<TRANSPORT_REMARKS> DHL Express;;;|||01.01.2016 </TRANSPORT_REMARKS>

Note: The first part "DHL Express;;;" is deprecated and no longer imported and can be set to "anything;;;".

 
GIFT_MESSAGE

(Optional) If the customer can enter a gift message in the shop, e.g. if the order should be shipped to a different shipping address, this can be imported here. It will be set into field "Gfit message" in pixi* Customer Service > tab Orders > tab General. Max. 1000 characters.

Line breaks can be achieved with pipe symbol "|", e.g.:

<GIFT_MESSAGE> Line 1 | Line 2 </GIFT_MESSAGE>

SUBSHOPLOGO

(Optional) URL of the logo of the sub shop, imported to column "SubShopLogo" in pixi* Customer Service > tab Orders > Orders grid.

SUBSHOPNAME

(Optional) Name of the sub shop, imported to column "SubShopName" in pixi* Customer Service > tab Orders > Orders grid.

REFERRER

(Optional) Referrer of the order, imported to column "Referrer" in pixi* Customer Service > tab Orders > Orders grid.

LOCATION

(Optional) If you are using multiple locations to ship orders, you can provide here the shipping location ID for the specific order if database setting "openTRANS - Use Location from XML" is enabled (pixi* Control Center > tab Database Settings > folder Import/Export > sub folder openTRANS. If value is empty or cannot be found in location table, by default "001" is used.

PARTIAL_DELIVERY

(Optional) With this tag it is possible to enable the partial delivery options. Possible values:

  • OFF - default (if tag is not provided, this is used as default)

  • ONCE - remaining items will be shipped in one package when they are available

  • ALWAYS - remaining items will be shipped immediately when they are available, if necessary in multiple packages

ORDER_TYPE

Recommended

This element was introduced with pixi* ELI Milestone 2 and is used to determine the order type of an order. Possible values:

  • "B2C" - for normal end customer orders, default value, also set if tag <ORDER_TYPE> is empty or not provided

  • "B2B" - for B2B orders

Defines which prices are imported for the order, i.e. if order type is B2B all prices are imported as net prices to pixi*.

When order type (B2C or B2B) is changed in the shop and the order is re-imported into pixi* with the new order type, the existing order type of the order in pixi* is not updated.

ORDER_PARTIES

Mandatory - This tag is used to import addresses and customer data of the order. See details below.

PAYMENT

Mandatory - This tag is used to import information about the payment type of the order. See details below.

REMARK

Mandatory - With remark tags additional information about the order can be imported if attribute "type" is set accordingly, e.g. shipping costs. See details below.


Back to top

ORDER_PARTIES

This element is used to import addresses and customer data of the order. The element <BUYER_PARTY> is mandatory and needs to be imported always because it contains the unique customer number for the customer of the order. The elements <INVOICE_PARTY> and <SHIPMENT_PARTIES> can be missing, but then the address data in pixi* is empty and the order cannot be shipped.


Example:

<ORDER_PARTIES>
   <BUYER_PARTY>
      ...
   </BUYER_PARTY>
   <INVOICE_PARTY>
      ...
   </INVOICE_PARTY>
   <SHIPMENT_PARTIES>
      <DELIVERY_PARTY>
         ...
     </DELIVERY_PARTY>
   </SHIPMENT_PARTIES>
</ORDER_PARTIES>


BUYER_PARTY

The element <BUYER_PARTY> is used to import mainly three values: Customer Number External, ShopID and VAT ID.


Example:

<BUYER_PARTY>
   <PARTY>
      <PARTY_ID type="buyer_specific">CustomerNrExternal 001</PARTY_ID>
      <SHOPID>MAD</SHOPID>
      <VAT_ID>BUYER_Old_VAT_ID</VAT_ID>
      <ADDRESS>
         <CUSTOMER_DISCOUNT_PERCENTAGE>CUSTOMER_DISCOUNT</CUSTOMER_DISCOUNT_PERCENTAGE>
         <VAT_ID>BUYER_VAT_ID</VAT_ID>
	 <BUYER_SHIPLOCK>Y</BUYER_SHIPLOCK>
      </ADDRESS>
   </PARTY>
</BUYER_PARTY>

Name of XML tag

Description

PARTY_ID

Mandatory - Customer Number External - unique identifier of the customer in pixi*, we recommend a generated customer number from the shop or the e-mail address of the customer.

SHOPID

(Optional) ID of the shop in pixi*, e.g. XYZ. If not provided, tag <SHOPID> from element <ORDER_HEADER><ORDER_INFO> is used.

DCUSTOMER_DISCOUNT_PERCENTAGE

(Optional) With this tag you can set the customer discount (pixi* Customer Service > Customer details tab). In case the tag is not included in the XML, the customer discount is not changed. The value needs to be provided with 2 decimal places and with dot as decimal seperator. (from AVA Update 21 on)

VAT_ID

(Optional) In case of a B2B customer, you can provide here the VAT ID which is imported to field "VAT ID" of the invoice and billing address in pixi* Customer Service > tab Orders > tab General. Element is used only if <ORDER_PARTIES><BUYER_PARTY><PARTY><ADDRESS><VAT_ID> is not provided.

ADDRESS

VAT_ID

(Optional) In case of a B2B customer, you can provide here the VAT ID which is imported to field "VAT ID" of the invoice and billing address in pixi* Customer Service > tab Orders > tab General. If this element is not provided, VAT ID is imported from element <ORDER_PARTIES><BUYER_PARTY><PARTY><VAT_ID>.

BUYER_SHIPLOCK

(Optional) Set a customer lock. Possible values:

  • "Y" to enable customer lock

  • "N" or empty to not enable the customer lock

If tag is not provided, value from <ORDER_HEADER><ORDER_INFO><BUYER_SHIPLOCK> is used.

Info: The ADDRESS block is mandatory! If it shouldn't contain any value, the XML at least needs to contain an empty tag <ADDRESS/>.

Back to top

INVOICE_PARTY

The element <INVOICE_PARTY> contains the billing address data.


Example:

<INVOICE_PARTY>
   <PARTY>
      <ADDRESS>
         <NAME>BILL_NAME</NAME>
         <SAL>BILL_SAL</SAL>
         <NAME2>BILL_FirstName</NAME2>
         <NAME3>BILL_LastName</NAME3>
         <STREET>BILL_Street</STREET> 
         <ZIP>BILL_ZIP</ZIP>
         <ZIPBOX>BILL_HOUSENR</ZIPBOX>
         <CITY>BILL_CITY</CITY>
         <COUNTRY>BILL_COUNTRY</COUNTRY>
         <STATE>BILL_STATE</STATE>
         <PHONE>BILL_PHONE</PHONE>
	 <FAX>BILL_FAX</FAX>
         <EMAIL>BILL_EMAIL</EMAIL>
      </ADDRESS>
   </PARTY>
</INVOICE_PARTY>

Name of XML tag

Description

NAME

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > Company

SAL

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > Salutation

NAME2

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > First name

NAME3

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > Last name

STREET

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > Street

If field also includes house number it is parsed to house number field separately.

ZIP

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > ZIP

ZIPBOX

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > House Nr. (max. 12 characters)

CITY

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > City

COUNTRY

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > Country

Country can be specified as and are matched to records in the countries table in this sequence:
1) EXACT match for Code ISO2 (3166-1)
2) EXACT match for Code ISO3 (3166-1)
3) EXACT match for Country Name
4) EXACT match for Code (pixi* internal country code)
5) EXACT match for one country name in the comma-separated list "Additional Names"
6) LIKE fuzzy match based on "Additional Names"

STATE

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > State

Max. 3 characters allowed, more characters will be cut when parsing the value.

PHONE

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > Phone

FAX

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > Fax

EMAIL

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > E-Mail (max. 60 characters)


Back to top

SHIPMENT_PARTIES

The element <SHIPMENT_PARTIES> contains the shipping address data for the order.


Example:

<SHIPMENT_PARTIES>
   <DELIVERY_PARTY>
      <PARTY>
         <ADDRESS>
            <NAME>SHIPMENT_NAME</NAME>
            <SAL>SHIPMENT_SAL</SAL>
            <NAME2>SHIPMENT_FirstName</NAME2>
            <NAME3>SHIPMENT_LastName</NAME3>
            <STREET>SHIPMENT_Street</STREET> 
            <ZIP>SHIPMENT_ZIP</ZIP>
            <ZIPBOX>SHIPMENT_HOUSENR</ZIPBOX>
            <CITY>SHIPMENT_CITY</CITY>
            <COUNTRY>SHIPMENT_COUNTRY</COUNTRY>
            <STATE>SHIPMENT_STATE</STATE>
            <PHONE>SHIPMENT_PHONE</PHONE>
	    <FAX>SHIPMENT_FAX</FAX>
            <EMAIL>SHIPMENT_EMAIL</EMAIL>
	    <ADDRESS_REMARKS>SHIPMENT_ADDRESS_REMARKS</ADDRESS_REMARKS>
	    <CHARGE_VAT>SHIPMENT_CHARGE_VAT</CHARGE_VAT>
            <EXPORT_EMAIL_PHONE_POLLING>Y</EXPORT_EMAIL_PHONE_POLLING>
         </ADDRESS>
      </PARTY>
   </DELIVERY_PARTY>
</SHIPMENT_PARTIES>

Name of XML tag

Description

NAME

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Shipping address > Company

SAL

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Shipping address > Salutation

NAME2

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Shipping address > First Name

NAME3

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Shipping address > Last Name

STREET

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Shipping address > Street

IF field also includes house number; the number is parsed to proper house number field

ZIP

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Shipping address > ZIP

ZIPBOX

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Shipping address > House Nr. (max. 12 characters)

CITY

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Shipping address > City

COUNTRY

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Shipping address > Country

EXEC GOSGetCountryByName; VAT rate will be calculated based on this value... regarding settings in countries table

STATE

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Shipping address > State (3 characters)

PHONE

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Shipping address > Phone

FAX

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Shipping address >Fax

EMAIL

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Shipping address > E-Mail (max. 60 characters)

ADDRESS_REMARKS

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Address remarks

CHARGE_VAT

(Optional) Sets checkbox "Don't charge VAT" in pixi* Customer Service > tab Orders > tab General. Possible values:

  • "N" - checkbox is enabled

  • "Y" or empty - checkbox is disabled

If a VAT ID was provided by the customer and the shipping country is within the European Union, the customer does not need to pay VAT. In this case value "N" needs to be set, i.e. VAT is not charged. This is handled in latest pixi version via element ORDER_TYPE and VAT is removed automatically if order type B2B is set.

EXPORT_EMAIL_PHONE_POLLING

(Optional) Sets checkbox "Export E-mail and Phone Nr. for Polling" for each order in pixi* Customer Service > Orders. Possible values:

  • "N" - checkbox is disabled

  • "Y" or empty or tag not in XML - checkbox is enabled

The effect on this flag depends on the database setting Export E-mail and Phone Nr. to Shipping Vendor as follows:

Setting Value

Checkbox Value

Export to Shipping Vendor

ON

ON

YES

ON

OFF

NO

OFF

ON

NO

OFF

OFF

NO

Back to top

Use Case: P.O. Box

For shipments to a P.O. box please import:

<DELIVERY_PARTY>
...
<NAME><!--Optional: Company Name--></NAME>
<STREET>P.O. Box</STREET>
<ZIPBOX><!--P.O. Box Number--></ZIPBOX>
<ADDRESS_REMARKS><!--P.O. Box Company Code--><ADDRESS_REMARKS>
...
<DELIVERY_PARTY>


Back to top

PAYMENT

The element <PAYMENT> contains all information about the payment type of the order. Please note that different tags need to be provided depending on the payment type.

Note: Depending on the setting "Order Status" in table Payments in pixi* Control Center, the initial order line status will be set for all items in the order. If initial order status in payments table for the payment type is not defined, HAL status will be set by default.


Example:

<PAYMENT>
   <Generic_XML_tag_From_Payments_Table>
      <CARD_NUM>CardNr</CARD_NUM>
      <CARD_EXPIRATION_DATE>CardExp</CARD_EXPIRATION_DATE> 
      <CARD_TYPE>CardType</CARD_TYPE>
      <CARD_HOLDER_NAME>CardName</CARD_HOLDER_NAME>
      <CARD_CVC>CardCVC</CARD_CVC>
      <CARD_AUTH_CODE>CardAuthID</CARD_AUTH_CODE>
      <CARD_AUTHORIZATION>CardAuthorization</CARD_AUTHORIZATION>
      <CCP_MERCHANT>CCPMerchant</CCP_MERCHANT>
      <BANK_ACCOUNT>AccountNr</BANK_ACCOUNT> 
      <HOLDER>AccountName</HOLDER>
      <BANK_CODE>BankNr</BANK_CODE> 
      <BANK_NAME>BankName</BANK_NAME>
      <BIC>Bank Identifier Code</BIC>
      <IBAN>International Bank Account Number</IBAN>
   </Generic_XML_tag_From_Payments_Table>
</PAYMENT>

Important: <Generic_XML_tag_From_Payments_Table> refers to the value entered in setting "XML Tag" in table Payments in pixi* Control Center. Here you can define for every payment type, with which XML tag it will be imported with the customer order. If XML payment tag is not set for a payment type, <CARD> element will be used by default.


Every payment type can then use all the elements within the <Generic_XML_tag_From_Payments_Table> as listed below or shown in above example. It can also be empty, for example:

<PAYMENT>
   <PAYPAL></PAYPAL>
</PAYMENT>

Name of XML tag

Description

CARD_NUM

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > Card Nr.

CARD_EXPIRATION_DATE

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > Card Exp.

CARD_TYPE

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > Card Type

CARD_HOLDER_NAME

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > Card Name

CARD_CVC

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > CVC

CARD_AUTH_CODE

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > payID

If field is empty <CARD_AUTHORIZATION> is used instead. If field is not empty (authorization was already done in shop), order line status is set to ANG.

CARD_AUTHORIZATION

(Optional) If <CARD_AUTH_CODE> is not provided, value is imported to pixi* Customer Service > tab Orders > tab General > Billing address > payID.

CCP_MERCHANT

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > CCP Merchant

BANK_ACCOUNT

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > Account

HOLDER

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > Acc. Name

BANK_CODE

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > BLZ

BANK_NAME

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > Bank Name

BIC

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > BIC

IBAN

(Optional) Imported to pixi* Customer Service > tab Orders > tab General > Billing address > IBAN


Back to top

REMARK

With remark tags additional information about the order can be imported if attribute "type" is set accordingly, e.g. shipping costs.

Example:

<REMARK type="SHIPPING">0.00</REMARK>
<REMARK type="SHIPPING_ORIGINAL">0.00</REMARK>
<REMARK type="VOUCHERCODE">ABC_VOUCHERCODE</REMARK>
<REMARK type="DISCOUNT">0.00</REMARK>
<REMARK type="SHIPPING2">0.00</REMARK>
<REMARK type="SHIPPINGVENDOR">DHL</REMARK>

Type attribute

Description

SHIPPING

(Optional) Used to import shipping costs for an order. If field value is not numeric, 0 is used by default.

Import gross shipping costs if ORDER_TYPE is B2C, net shipping costs if ORDER_TYPE is B2B.

SHIPPING_ORIGINAL

(Optional) Used to import shipping costs in foreign currency, but is not displayed in the user interface of pixi* Customer Service. If field value is not numeric, 0 is used by default.

Obsolete

VOUCHERCODE

(Optional) Imported to field Voucher ID in pixi* Customer Service > tab Orders > tab General. If not provided and discount bigger than 0: pixi* generates a voucher ID.

DISCOUNT

Mandatory - Used to import the discount voucher for the complete order. You can use the field to summarize any discounts that the customer got on the whole order, e.g. early payment discount (Skonto) or vouchers. If no voucher ID is provided in <VOUCHERCODE>, it is generated by pixi*.

Import gross discount value if ORDER_TYPE is B2C, net discount value if ORDER_TYPE is B2B.

SHIPPING2

(Optional) Used to import shipping costs for an order. If field value is not numeric, <SHIPPING> value is used.

Import gross shipping costs if ORDER_TYPE is B2C, net shipping costs if ORDER_TYPE is B2B.

SHIPPINGVENDOR

(Optional) Code of the shipping vendor that should be used to ship the order, e.g. DHL. Value needs to match one entry of table "Shipping Vendors" in pixi* Control Center > tab Tables.

If missing or empty, value from setting "Opentrans, Default Shipping Vendor" is used (pixi* Control Center > tab Database Settings > folder Import/Export > sub folder openTRANS).


Back to top

Item level part: ORDER_ITEM_LIST

The item level part in <ORDER_ITEM_LIST> element contains the relevant information for the individual positions in the order. Per order max 3000 orderlines can be imported.


Example:

<ORDER_ITEM_LIST>
   <ORDER_ITEM>
      <LINE_ITEM_ID>LINE_ITEM_ID</LINE_ITEM_ID>
      <WAREHOUSE_LOCATION>001</WAREHOUSE_LOCATION>
      <ARTICLE_ID>
         ...
      </ARTICLE_ID>
      <QUANTITY>1</QUANTITY>
      <DESCRIPTION_SHORT>DESCRIPTION_SHORT</DESCRIPTION_SHORT>
      <ITEM_NOTE>ITEM_NOTE</ITEM_NOTE>
      <DATEV>DATEV</DATEV>
      <DF_TYPE>DF_TYPE</DF_TYPE>
      <ORDER_UNIT/>
      <ITEM_NAME>ITEM_NAME</ITEM_NAME>
      <ARTICLE_PRICE type="udp_gross_customer">
         ...
      </ARTICLE_PRICE>
      <ARTICLE_PRICE type="udp_net_customer">
         ...
      </ARTICLE_PRICE>
   </ORDER_ITEM>
   <ORDER_ITEM>
      ...
   </ORDER_ITEM>
</ORDER_ITEM_LIST>

Name of XML tag

Description

LINE_ITEM_ID

Mandatory - Every order line needs to be imported to pixi* with a unique identifier within this tag. We recommend the following structure: [OrderNr]-[NrOfOrderline], e.g. "123456-1", "123456-2".

Value is used as internal reference for the shop order line in pixi* database, not visible in GUI.

WAREHOUSE_ID

(OPTIONAL) - Used to pass the location ID specific for each order line

Character limit is 3

ARTICLE_ID

Mandatory - See below: ARTICLE_ID

QUANTITY

Mandatory - Used to import the ordered quantity of the concerning item.

DESCRIPTION_SHORT

(OPTIONAL) Can be used to import the item name for each order line.

If setting "Opentrans, Import of Item Name" is disabled (pixi* Control Center > tab Database Settings > folder Import/Export > sub folder openTRANS) and

  • tag ITEM_NAME is not provided or empty, the value of DESCRIPTION_SHORT is used.

  • tag ITEM_NAME and tag DESCRIPTION_SHORT are not provided or empty, value from <ARTICLE_ID><DESCRIPTION_SHORT> is used.

  • tag ITEM_NAME is provided, value of ITEM_NAME is used.

If setting "Opentrans, Import of Item Name" is enabled and

  • tag ITEM_NAME is not provided or empty, the value of DESCRIPTION_SHORT is used.

  • tag ITEM_NAME and tag DESCRIPTION_SHORT are not provided or empty, the value from <ARTICLE_ID><DESCRIPTION_SHORT> is used.

  • tag ITEM_NAME, DESCRIPTION_SHORT and ARTICLE_ID/DESCRIPTION_SHORT are not provided or empty, the item name is taken from pixi* database like it was imported with item import (BMEcat).

  • tag ITEM_NAME is provided, DESCRIPTION_SHORT is used. Only if DESCRIPTION_SHORT is not provided, value from ITEM_NAME is used.

  • tag ITEM_NAME is provided and tag DESCRIPTION_SHORT is not provided or empty, the value from <ARTICLE_ID><DESCRIPTION_SHORT> is used.

  • tag ITEM_NAME is provided and DESCRIPTION_SHORT and ARTICLE_ID/DESCRIPTION_SHORT are not provided or empty, value from ITEM_NAME is used.

The value for the item name is limited to 120 characters.

Recommendation: Wrap the value in CDATA to properly handle special characters;

Example:

<DESCRIPTION_SHORT><![CDATA[The SpecialItem® Brand Name™]]></DESCRIPTION_SHORT>

ITEM_NOTE

(Optional) For each order line it is possible to import a text from the shop, e.g. if customers can enter desired text for personalized items in the shop.

parsed to oItemSpecialNote

  1. ITEM_NOTE has priority over ITEM_NOTE_XTC

  2. existing value in DB has priority over ITEM_NOTE

The value for the item note is limited to 8.000 characters.

DATEV

(Optional)

DF_TYPE

(Optional) Needed in case you are using Direct Fulfillment functionality in pixi*. If tag is empty, value is set according to setting "DF-Type - Default Value" in pixi* Control Center > tab Database Settings > folder Import/Export > BMEcat.

ORDER_UNIT

(Optional) Can be used to import the package unit of the item. Package unit is not used on customer orders, but can be used for ordering items from suppliers. See for example: Modify an Item

Value needs to be numeric.

ITEM_NAME

(Optional) See DESCRIPTION_SHORT.

ARTICLE_PRICE

Mandatory - Element to import price information of the ordered item.

It is necessary to include the type attribute in order to define if the net or gross price is provided:

  • If type = "udp_gross_customer": values are parsed as gross amounts

  • If type = "udp_net_customer": values are parsed as net amounts

See details below: ARTICLE_PRICE


Back to top

ARTICLE_ID

Element <ARTICLE_ID> contains the unique identifier to match the item in the order with an existing item in the pixi* database.


Name of XML tag

Description

 
SUPPLIER_AID

Mandatory - Needs to contain the unique identifier of the item in order to match it with an existing item in pixi* that was imported via item import (BMEcat). You can see this item number in pixi* item info in field "Shop Item Number".

Shop Item Number has to be unique, should not change over time, max. 50 characters, only numbers and/or letters, point and dash.

DESCRIPTION_SHORT

(Optional) See DESCRIPTION_SHORT

ITEM_NOTE

(Optional) See ITEM_NOTE


Back to top

ARTICLE_PRICE

Element <ARTICLE_PRICE> is used to import order line prices for each ordered item.

It is necessary to include the type attribute in order to define if the net or gross price is provided:

  • If type = "udp_gross_customer": all values in <ARTICLE_PRICE> element are parsed as gross amounts

  • If type = "udp_net_customer": all values in <ARTICLE_PRICE> element are parsed as net amounts

Prices are in general calculated based on setting "Number of decimal places for prices" in pixi* Control Center > tab Database Settings > folder General.

See details for net prices functionality: Net Prices in pixi


Example:

<ARTICLE_PRICE type="udp_gross_customer">
   <PRICE_AMOUNT>0</PRICE_AMOUNT>
   <PRICE_AMOUNT_ORIGINAL>0</PRICE_AMOUNT_ORIGINAL>
   <PRICE_LINE_AMOUNT>0</PRICE_LINE_AMOUNT>
   <DISCOUNT_PERC>0</DISCOUNT_PERC>
   <DISCOUNT_VALUE>0</DISCOUNT_VALUE>
   <FULL_PRICE>0</FULL_PRICE>
</ARTICLE_PRICE>
<ARTICLE_PRICE type="udp_net_customer">
   <PRICE_AMOUNT>0</PRICE_AMOUNT>
   <PRICE_AMOUNT_ORIGINAL>0</PRICE_AMOUNT_ORIGINAL>
   <PRICE_LINE_AMOUNT>0</PRICE_LINE_AMOUNT>
   <DISCOUNT_PERC>0</DISCOUNT_PERC>
   <DISCOUNT_VALUE>0</DISCOUNT_VALUE>
   <FULL_PRICE>0</FULL_PRICE>
</ARTICLE_PRICE>

Name of XML tag

Description

 
SHOPID

Recommended - Final selling price of single item incl. discount.

If PRICE_AMOUNT is empty, final selling price of the item is calculated based on FULL_PRICE value and DISCOUNT_PERC. If also DISCOUNT_PERC is empty or not provided, DISCOUNT_VALUE is used.

PRICE_AMOUNT_ORIGINAL

(Optional) Can be used to import the final selling price of a single item in a foreign currency. Value is imported to pixi* in Price_OrderCurr in pixi* Customer Service > tab Orders > tab Items. Currency is defined by value of tag PRICE_CURRENCY_ORIGINAL in ORDER_INFO element.

Obsolete. If tag is still included in the XML file, value must be the same as in tag PRICE_AMOUNT, otherwise order will not be imported.

PRICE_LINE_AMOUNT

(Optional) Ordered quantity multiplied with the final selling price of the item, i.e. order line total.

DISCOUNT_PERC

(Optional) Discount per order line in percent. Can be used to import any kind of discount, also early payment discount (Skonto). Value needs to be provided as decimal number, e.g. 5 percent should be imported as "0.05".

If DISCOUNT_PERC is not provided, it is calculated from DISCOUNT_VALUE and FULL_PRICE. If DISCOUNT_PERC and DISCOUNT_VALUE are present, DISCOUNT_PERC is recalculated based on DISCOUNT_VALUE in order to prevent rounding issues.

DISCOUNT_VALUE

(Optional) Discount per order line as amount. Can be used to import any kind of discount, also early payment discount (Skonto). Value needs to be provided as decimal number, e.g. 12,34 EUR discount should be imported as "12.34" in case the currency of the order is EUR.

If DISCOUNT_VALUE is not provided, it is calculated from DISCOUNT_PERC and FULL_PRICE value.

FULL_PRICE

Mandatory - Original selling price of single item without discount.


If both FULL_PRICE and PRICE_AMOUNT are provided and both DISCOUNT tags are missing or empty, then the discount is calculated from the difference between the FULL_PRICE and the PRICE_AMOUNT. The order cannot be imported, if both PRICE_AMOUNT and FULL_PRICE are missing.


Back to top

Complete openTRANS XML example

<?xml version="1.0" encoding="UTF-8" ?>
<ORDER version="1.0" type="standard">
    <ORDER_HEADER>
        <CONTROL_INFO>
            <GENERATOR_INFO>Name of the Shop - openTRANS-Export</GENERATOR_INFO>
            <GENERATION_DATE>2015-02-04T10:16:14+01:00</GENERATION_DATE>
        </CONTROL_INFO>
        <ORDER_INFO>
            <ORDER_ID>Order Number</ORDER_ID>
            <ORDER_DATE>date timestamp</ORDER_DATE>
            <DATABASE>pixi_XYZ</DATABASE>
            <SHOPID>ABC</SHOPID>
            <SHOP_NOTE>Shop Comment</SHOP_NOTE>
            <ORDERTAGS>
                <ORDERTAG>Tag 1</ORDERTAG>
                <ORDERTAG>Tag 2</ORDERTAG>
            </ORDERTAGS>
            <ORDER_SHIPLOCK>Y</ORDER_SHIPLOCK>
            <BUYER_SHIPLOCK>Y</BUYER_SHIPLOCK>
            <PRICE_CURRENCY>EUR</PRICE_CURRENCY>
            <PRICE_CURRENCY_ORIGINAL>GBP</PRICE_CURRENCY_ORIGINAL>
            <TRANSPORT_REMARKS>Shipping Information</TRANSPORT_REMARKS>
            <GIFT_MESSAGE>Custom gift message</GIFT_MESSAGE>
            <SUBSHOPLOGO>Sub shop logo</SUBSHOPLOGO>
            <SUBSHOPNAME>Sub shop name</SUBSHOPNAME>
            <REFERRER>Referrer</REFERRER>
            <LOCATION>LocationID</LOCATION>
            <PARTIAL_DELIVERY>OFF</PARTIAL_DELIVERY>
            <ORDER_TYPE>B2C</ORDER_TYPE>
            <ORDER_PARTIES>
                <BUYER_PARTY>
                    <PARTY>
                        <PARTY_ID type="buyer_specific">CustomerNrExternal 001</PARTY_ID>
                        <SHOPID>MAD</SHOPID>
                        <VAT_ID>BUYER_Old_VAT_ID</VAT_ID>
                        <ADDRESS>
                            <CUSTOMER_DISCOUNT_PERCENTAGE>CUSTOMER_DISCOUNT</CUSTOMER_DISCOUNT_PERCENTAGE>
                            <VAT_ID>BUYER_VAT_ID</VAT_ID>
                            <BUYER_SHIPLOCK>Y</BUYER_SHIPLOCK>
                        </ADDRESS>
                    </PARTY>
                </BUYER_PARTY>
                <INVOICE_PARTY>
                    <PARTY>
                        <ADDRESS>
                            <NAME>BILL_NAME</NAME>
                            <SAL>BILL_SAL</SAL>
                            <NAME2>BILL_FirstName</NAME2>
                            <NAME3>BILL_LastName</NAME3>
                            <STREET>BILL_Street</STREET>
                            <ZIP>BILL_ZIP</ZIP>
                            <ZIPBOX>BILL_HOUSENR</ZIPBOX>
                            <CITY>BILL_CITY</CITY>
                            <COUNTRY>BILL_COUNTRY</COUNTRY>
                            <STATE>BILL_STATE</STATE>
                            <PHONE>BILL_PHONE</PHONE>
                            <FAX>BILL_PHONE</FAX>
                            <EMAIL>BILL_EMAIL</EMAIL>
                        </ADDRESS>
                    </PARTY>
                </INVOICE_PARTY>
                <SHIPMENT_PARTIES>
                    <DELIVERY_PARTY>
                        <PARTY>
                            <ADDRESS>
                                <NAME>SHIPMENT_NAME</NAME>
                                <SAL>SHIPMENT_SAL</SAL>
                                <NAME2>SHIPMENT_FirstName</NAME2>
                                <NAME3>SHIPMENT_LastName</NAME3>
                                <STREET>SHIPMENT_Street</STREET>
                                <ZIP>SHIPMENT_ZIP</ZIP>
                                <ZIPBOX>SHIPMENT_HOUSENR</ZIPBOX>
                                <CITY>SHIPMENT_CITY</CITY>
                                <COUNTRY>SHIPMENT_COUNTRY</COUNTRY>
                                <STATE>SHIPMENT_STATE</STATE>
                                <PHONE>SHIPMENT_PHONE</PHONE>
                                <FAX>SHIPMENT_PHONE</FAX>
                                <EMAIL>SHIPMENT_EMAIL</EMAIL>
                                <ADDRESS_REMARKS>SHIPMENT_ADDRESS_REMARKS</ADDRESS_REMARKS>
                                <CHARGE_VAT>SHIPMENT_CHARGE_VAT</CHARGE_VAT>
                            </ADDRESS>
                        </PARTY>
                    </DELIVERY_PARTY>
                </SHIPMENT_PARTIES>
            </ORDER_PARTIES>
            <PAYMENT>
                <Generic_XML_tag_From_Payments_Table>
                    <CARD_NUM>CardNr</CARD_NUM>
                    <CARD_EXPIRATION_DATE>CardExp</CARD_EXPIRATION_DATE>
                    <CARD_TYPE>CardType</CARD_TYPE>
                    <CARD_HOLDER_NAME>CardName</CARD_HOLDER_NAME>
                    <CARD_CVC>CardCVC</CARD_CVC>
                    <CARD_AUTH_CODE>CardAuthID</CARD_AUTH_CODE>
                    <CARD_AUTHORIZATION>CardAuthorization</CARD_AUTHORIZATION>
                    <CCP_MERCHANT>CCPMerchant</CCP_MERCHANT>
                    <BANK_ACCOUNT>AccountNr</BANK_ACCOUNT>
                    <HOLDER>AccountName</HOLDER>
                    <BANK_CODE>BankNr</BANK_CODE>
                    <BANK_NAME>BankName</BANK_NAME>
                    <BIC>Bank Identifier Code</BIC>
                    <IBAN>International Bank Account Number</IBAN>
                </Generic_XML_tag_From_Payments_Table>
            </PAYMENT>
            <REMARK type="SHIPPING">0.00</REMARK>
            <REMARK type="SHIPPING_ORIGINAL">0.00</REMARK>
            <REMARK type="VOUCHERCODE">ABC_VOUCHERCODE</REMARK>
            <REMARK type="DISCOUNT_ORIGINAL">0.00</REMARK>
            <REMARK type="DISCOUNT">0.00</REMARK>
            <REMARK type="SHIPPING2">0.00</REMARK>
            <REMARK type="SHIPPINGVENDOR">DHL</REMARK>
        </ORDER_INFO>
    </ORDER_HEADER>
    <ORDER_ITEM_LIST>
        <ORDER_ITEM>
            <LINE_ITEM_ID>LINE_ITEM_ID</LINE_ITEM_ID>
            <ARTICLE_ID>
                <SUPPLIER_AID>SUPPLIER_AID</SUPPLIER_AID>
                <DESCRIPTION_SHORT>DESCRIPTION_SHORT</DESCRIPTION_SHORT>
                <ITEM_NOTE>ITEM_NOTE</ITEM_NOTE>
            </ARTICLE_ID>
            <QUANTITY>1</QUANTITY>
            <DESCRIPTION_SHORT><![CDATA[DESCRIPTION_SHORT]]></DESCRIPTION_SHORT>
            <ITEM_NOTE>ITEM_NOTE</ITEM_NOTE>
            <DATEV>DATEV</DATEV>
            <DF_TYPE>DF_TYPE</DF_TYPE>
            <ORDER_UNIT/>
            <ITEM_NAME>ITEM_NAME</ITEM_NAME>
            <ARTICLE_PRICE type="udp_gross_customer">
                <PRICE_AMOUNT>0</PRICE_AMOUNT>
                <PRICE_AMOUNT_ORIGINAL>0</PRICE_AMOUNT_ORIGINAL>
                <PRICE_LINE_AMOUNT>0</PRICE_LINE_AMOUNT>
                <DISCOUNT_PERC>0</DISCOUNT_PERC>
                <DISCOUNT_VALUE>0</DISCOUNT_VALUE>
                <FULL_PRICE>0</FULL_PRICE>
            </ARTICLE_PRICE>
            <ARTICLE_PRICE type="udp_net_customer">
                <PRICE_AMOUNT>0</PRICE_AMOUNT>
                <PRICE_AMOUNT_ORIGINAL>0</PRICE_AMOUNT_ORIGINAL>
                <PRICE_LINE_AMOUNT>0</PRICE_LINE_AMOUNT>
                <DISCOUNT_PERC>0</DISCOUNT_PERC>
                <DISCOUNT_VALUE>0</DISCOUNT_VALUE>
                <FULL_PRICE>0</FULL_PRICE>
            </ARTICLE_PRICE>
        </ORDER_ITEM>
    </ORDER_ITEM_LIST>
</ORDER>


Back to top