XML interfaces
In this topic you will see an overview of the logistic XML interfaces of Magento Order Management System (Magento OMS), an explanation of the OMS sFTP folder structure (file conventions to follow for incoming and outgoing files), and steps for validating examples.
In the schema files for each feed below, you must change the shared.xsd portion of the file name to point to the feed you want to use. For instance, for stock-snapshot you would replace the <xs:include schemaLocation="shared.xsd"/> part of the linked schema with <xs:include schemaLocation="stock-snapshot.xsd"/>.
Incoming
stock-snapshot
The Stock Snapshot is a feed that is used for stock audit and reconciliation purposes by the OMS, front-ends or the internal client’s system (ERP). Where necessary, multiple sources feeds may be aggregated by the OMS and rules applied before the generation of front-end feeds which can be provided for a single web store or a group of web stores. The snapshots are sent as either a full, delta or non-zero (which is the same as the full feed but SKUs not included should be assumed to have a stock of zero).
| Sender / Receiver | Stock sources > EE > front-end Stock sources > EE > client |
| Mode | Full: Full Inventory Snapshot including zero stock SKUs Full without zero: Full Inventory Snapshot excluding zero stock SKUs Delta: Including stock counts changed since last delta |
| Frequency | Processed and forwarded in near-real-time when received from stock sources. Usually a full stock snapshot is received from the warehouse and processed once a day (during the night) whereas delta snapshot can be run more often. |
| Format | XML |
| Transport | sFTP |
| Filename | <client>_stock-snapshot_YYYYMMDDHH24MISSUUUUUU.xml |
| Acknowledgement | ACK_<CLIENT>_stock-snapshot_<Timestamp>.xml (only when importing the feed) |
Schema
Overview
Examples
<?xml version="1.0" encoding="UTF-8"?>
<stockSnapshot
version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../schema/stock-snapshot.xsd">
<client>CLIENT</client>
<merchantId>RETAILER NAME</merchantId>
<catalogId>500</catalogId>
<source>WAREH1</source>
<mode>DELTA</mode>
<snapshotTime>2013-12-17T17:22:01Z</snapshotTime>
<items>
<item>
<clientSku>8718343609973</clientSku>
<stockType>GOOD</stockType>
<qty>7</qty>
</item>
<item>
<clientSku>8718343609974</clientSku>
<stockType>GOOD</stockType>
<qty>43</qty>
</item>
<item>
<clientSku>8718343609975</clientSku>
<stockType>DAMAGED</stockType>
<qty>19</qty>
</item>
<item>
<clientSku>8718343609873</clientSku>
<stockType>GOOD</stockType>
<qty>6786</qty>
</item>
<item>
<clientSku>8718343609980</clientSku>
<stockType>GOOD</stockType>
<qty>414</qty>
</item>
</items>
</stockSnapshot>
stock-adjustment
The Stock Adjustment is a close to real-time feed that is received by the OMS from the LSP and sent to the front-end for stock adjustment purposes whenever the stock of an item in the warehouse increases or decreases. The front-end will then adjust its internal counters to reflect the change. The inventory adjustment can be sent to the front-end and/or to the partner. In the first case, only adjustments of relevance to the front-end are sent. In the second case, all adjustments are sent to give visibility of all stock adjustments to the partner.
| Sender / Receiver | Stock sources > EE > front-end and if required Stock sources > EE > Partner |
| Frequency | Processed and forwarded in nearNrealNtime when received from stock sources |
| Format | XML |
| Transport | sFTP |
| Filename | <client>_stock-adjustment_YYYYMMDDHH24MISSUUUUUU.xml |
| Acknowledgement | ACK_<CLIENT>_shipment-response_<Timestamp>.xml (optional) |
Schema
Overview
Examples
<?xml version="1.0" encoding="UTF-8"?>
<stockAdjustment
version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../schema/stock-adjustment.xsd">
<client>CLIENT</client>
<source>WAREH1</source>
<store>STORE</store>
<transactions>
<transaction>
<adjustmentDate>2013-12-17T17:40:53+02:00</adjustmentDate>
<documentReference>100252363</documentReference>
<adjustmentReasonCode>85</adjustmentReasonCode>
<adjustmentReason>Damaged in Facility</adjustmentReason>
<adjustmentReasonComment>Pallet fell and 12 items were damaged.</adjustmentReasonComment>
<adjustments>
<adjustment>
<clientSku>8718343609974</clientSku>
<stockType>DAMAGED</stockType>
<qty>12</qty>
</adjustment>
<adjustment>
<clientSku>8718343609974</clientSku>
<stockType>GOOD</stockType>
<qty>-12</qty>
</adjustment>
</adjustments>
</transaction>
</transactions>
</stockAdjustment>
shipment-result
The Shipment Result feed is used to notify the OMS either of a successful shipment or a failed shipment. For one order there might be multiple shipment-result and each result will include only the information about the items processes in this particular shipment
| Sender / Receiver | LSP > OMS |
| Frequency | As soon as the LSP has been processed the shipment or cancelled an order line due to stock issues |
| Format | XML |
| Transport | sFTP |
| Filename | <client>_shipment-result_YYYYMMDDHH24MISSUUUUUU.xml |
| Acknowledgement | ACK_<CLIENT>shipment-result<Timestamp>.xml |
Schema
Overview
Examples
<?xml version="1.0" encoding="UTF-8"?>
<shipmentResult>
<client>CLIENT</client>
<distributionCentre>GH-2020</distributionCentre>
<externalId>CLIENT-TEST-002-aggr-sgl-addr-01</externalId>
<order>
<id>TEST-002-aggr-sgl-addr</id>
<store>CLIENT_ALL</store>
<shipments>
<shipment>
<logisticsId>1234</logisticsId>
<newStatus>SHIPPED</newStatus>
<aggregatedItems>
<aggregatedItem>
<line>1</line>
<sku>QA_SKU_0001a</sku>
<statuses>
<status>
<name>SHIPPED</name>
<quantity>2</quantity>
</status>
</statuses>
</aggregatedItem>
<aggregatedItem>
<line>2</line>
<sku>QA_SKU_0001b</sku>
<statuses>
<status>
<name>SHIPPED</name>
<quantity>2</quantity>
</status>
</statuses>
</aggregatedItem>
<aggregatedItem>
<line>3</line>
<sku>QA_SKU_0001c</sku>
<statuses>
<status>
<name>SHIPPED</name>
<quantity>1</quantity>
</status>
</statuses>
</aggregatedItem>
</aggregatedItems>
</shipment>
</shipments>
</order>
</shipmentResult>
item master
The Item Master feed informs the OMS and the LSP about the basic set of SKUs they will handle and related information such as price, dimension, harmonized code, etc. This information is needed before any other feed for order management, logistic and shipment of goods and services.
| Sender / Receiver | Partner > OMS or Front-end > OMS OMS > LSP |
| Mode | Full: Full Catalog Delta: Only changes since last feed |
| Frequency | Processed and forwarded in near-real-time when received |
| Format | XML |
| Transport | sFTP |
| Filename | <client>_item-master_YYYYMMDDHH24MISSUUUUUU.xml |
| Acknowledgement | <client>_item-master_YYYYMMDDHH24MISSUUUUUU_ACK.xml |
Schema
Overview
Examples
<?xml version="1.0" encoding="UTF-8"?>
<itemMaster
version="1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="../../schema/item-master.xsd">
<client>CLIENT</client>
<catalogId>500</catalogId>
<merchantId>RETAILER NAME</merchantId>
<items>
<item>
<details>
<clientCode>6BHTV024</clientCode>
<styleCode>6BHTV024</styleCode>
<name>Long Sleeves T-Shirt-HT122</name>
<type>PHYSICAL</type>
<category>Shirt</category>
<originCountry>ESP</originCountry>
<serialNumbers>false</serialNumbers>
<customsNumber>6204339000</customsNumber>
<price>
<currency>EUR</currency>
<amount>49</amount>
</price>
</details>
<warehouseData>
<warehouseMeasurements>
<param>
<key>height</key>
<unit>cm</unit>
<value>55</value>
</param>
</warehouseMeasurements>
<warehouseInfo>
<param>
<key>season</key>
<value>0906</value>
</param>
</warehouseInfo>
</warehouseData>
<variants>
<variant>
<sku>8718343609973</sku>
<clientSku>8718343609973</clientSku>
<optionName>Long Sleeves T-Shirt</optionName>
<price>
<currency>EUR</currency>
<amount>49.95</amount>
</price>
<attributes>
<param>
<key>COLOR</key>
<value>514</value>
</param>
<param>
<key>COLORNAME</key>
<value>Medium Pur</value>
</param>
<param>
<key>SIZE</key>
<value>32</value>
</param>
</attributes>
<warehouseData>
<warehouseMeasurements>
<param>
<key>height</key>
<unit>cm</unit>
<value>55</value>
</param>
</warehouseMeasurements>
<warehouseInfo>
<param>
<key>season</key>
<value>0906</value>
</param>
</warehouseInfo>
</warehouseData>
<channelData>
<param>
<channel>WEB_ES</channel>
<key>allowBackorders</key>
<value>true</value>
</param>
<param>
<channel>WEB_FR</channel>
<key>allowBackorders</key>
<value>false</value>
</param>
</channelData>
</variant>
</variants>
</item>
</items>
</itemMaster>
order new
The Order New requests are sent by the front-end to OMS when a customer completes an order in the front-end.
| Sender / Receiver | Front-end > OMS |
| Frequency | Processed in near-real-time when received from front-end |
| Format | XML |
| Transport | sFTP |
| Filename | <client>_order-new_YYYYMMDDHH24MISSUUUUUU.xml |
| Acknowledgement | <client>_order-new_YYYYMMDDHH24MISSUUUUUU_ACK.xml |
Schema
Overview
Examples
<?xml version="1.0" encoding="UTF-8"?>
<orderNew version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../schema/order-new.xsd">
<client>BCN</client>
<order>
<id>BCN200000000001452</id>
<store>BCN200000000001452</store>
<details>
<created>2014-01-31T10:37:24+00:00</created>
<customer>BUBBA</customer>
<customerType>REGISTERED</customerType>
<ip>10.0.2.2</ip>
<language>es</language>
<vatCountry>ES</vatCountry>
<origin>WEB</origin>
<originDate>2014-01-31T10:37:24+00:00</originDate>
<customerReference>turn left on main</customerReference>
<fingerprint>TF1;015;;;;;;;;;;;;;;;;;;;;;;Mozilla;Netscape;5.0%20%28Windows%29;20100101;undefined;true;Windows%20NT%206.1%3B%20WOW64;true;Win32;undefined;Mozilla/5.0%20%28Windows%20NT%206.1%3B%20WOW64%3B%20rv:26.0%29%20Gecko/20100101%20Firefox/26.0;en-US;undefined;localhost;undefined;undefined;undefined;undefined;true;false;1391164644242;1;Tuesday%2C%20June%2007%2C%202005%209:33:44%20PM;1366;768;;11.9;7.7.4;;;2010;14;-60;-120;Friday%2C%20January%2031%2C%202014%2011:37:24%20AM;24;1366;738;0;0;Adobe%20Acrobat%7CAdobe%20PDF%20Plug-In%20For%20Firefox%20and%20Netscape%2010.1.9;;;;;Shockwave%20Flash%7CShockwave%20Flash%2011.9%20r900;;;;QuickTime%20Plug-in%207.7.4%7CThe%20QuickTime%20Plugin%20allows%20you%20to%20view%20a%20wide%20variety%20of%20multimedia%20content%20in%20Web%20pages.%20For%20more%20information%2C%20visit%20the%20%3CA%20HREF%3Dhttp://www.apple.com/quicktime/%3EQuickTime%3C/A%3E%20Web%20site.;;;;;Silverlight%20Plug-In%7C5.1.20913.0;;;;15;</fingerprint>
<deviceInfo>
<timeOnSite>unknown</timeOnSite>
<sessionId>dpovsm4gtghbicjpocfbof8ku6</sessionId>
<deviceHostname>localhost:8080</deviceHostname>
<httpHeader>
<header>
<param>
<key>host</key>
<value>localhost:8080</value>
</param>
<param>
<key>user-agent</key>
<value>Mozilla/5.0 (Windows NT 6.1; WOW64; rv:26.0) Gecko/20100101 Firefox/26.0</value>
</param>
<param>
<key>accept</key>
<value>text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8</value>
</param>
<param>
<key>accept-language</key>
<value>en-US,en;q=0.5</value>
</param>
<param>
<key>accept-encoding</key>
<value>gzip, deflate</value>
</param>
<param>
<key>cookie</key>
<value>PHPSESSID=dpovsm4gtghbicjpocfbof8ku6</value>
</param>
<param>
<key>connection</key>
<value>keep-alive</value>
</param>
</header>
</httpHeader>
</deviceInfo>
</details>
<people>
<person>
<ref>1</ref>
<title>Mr.</title>
<firstName>John</firstName>
<lastName>Paul</lastName>
<phone>408-598-6080</phone>
<fax>724-972-9527</fax>
<mobile>724-972-9527</mobile>
<email>barnabridge_us@test.com</email>
<department/>
<companyName/>
<gender>M</gender>
<dateofbirth>1966-05-15</dateofbirth>
</person>
</people>
<addresses>
<address>
<ref>3</ref>
<addresstype>enumeration not known</addresstype>
<address1>3983 Spruce Drive</address1>
<address2/>
<city>Pittsburgh</city>
<state>PA</state>
<zip>15203</zip>
<country>
<code>US</code>
<name>lands unknown</name>
</country>
</address>
</addresses>
<payments>
<payment>
<ref>1</ref>
<currency>USD</currency>
<transactions>
<transaction>
<details>
<method>PY</method>
<submethod>PayPal</submethod>
<amount>394.33</amount>
<expirationDate>2015-05-15T00:00:00+00:00</expirationDate>
</details>
<gateway>
<id>KoP</id>
<account>BCN2</account>
<transactionId>3</transactionId>
<gatewayData>
<authStatus>AUTHORIZED</authStatus>
<paymentAccountUniqueId>T45P4PTQ9NCJ6</paymentAccountUniqueId>
<originalAuthRequestId>11009</originalAuthRequestId>
<ccAuthAttempts>8</ccAuthAttempts>
<paymentServiceResponse>
<param>
<key>PayPalPayer</key>
<value>verified</value>
</param>
<param>
<key>PayPalAddress</key>
<value>Confirmed</value>
</param>
</paymentServiceResponse>
</gatewayData>
</gateway>
<billToAddress>
<personRef>1</personRef>
<addressRef>3</addressRef>
</billToAddress>
</transaction>
</transactions>
</payment>
</payments>
<items>
<item>
<line>1</line>
<id/>
<details>
<itemType/>
<clientCode/>
<styleCode/>
<itemName>Product A</itemName>
<clientSku/>
<sku>54NV2</sku>
<serialNumber/>
<optionName/>
<localName/>
</details>
<shipToAddress>
<personRef>1</personRef>
<addressRef>3</addressRef>
</shipToAddress>
<payments>
<payment>
<ref>1</ref>
<paymentRef>1</paymentRef>
<details>
<costGross>99.99</costGross>
<costNet>0.00</costNet>
<costVat>0.00</costVat>
<vatRate>0</vatRate>
<vatDetail>
<vat>
<type>VAT</type>
<amount>0.00</amount>
<rate>0</rate>
</vat>
</vatDetail>
</details>
</payment>
</payments>
</item>
<item>
<line>2</line>
<id/>
<details>
<itemType/>
<clientCode/>
<styleCode/>
<itemName>Product A</itemName>
<clientSku/>
<sku>54NV2</sku>
<serialNumber/>
<optionName/>
<localName/>
</details>
<shipToAddress>
<personRef>1</personRef>
<addressRef>3</addressRef>
</shipToAddress>
<payments>
<payment>
<ref>2</ref>
<paymentRef>1</paymentRef>
<details>
<costGross>99.99</costGross>
<costNet>0.00</costNet>
<costVat>0.00</costVat>
<vatRate>0</vatRate>
<vatDetail>
<vat>
<type>VAT</type>
<amount>0.00</amount>
<rate>0</rate>
</vat>
</vatDetail>
</details>
</payment>
</payments>
</item>
<item>
<line>3</line>
<id/>
<details>
<itemType/>
<clientCode/>
<styleCode/>
<itemName>Product A</itemName>
<clientSku/>
<sku>54NV2</sku>
<serialNumber/>
<optionName/>
<localName/>
</details>
<shipToAddress>
<personRef>1</personRef>
<addressRef>3</addressRef>
</shipToAddress>
<payments>
<payment>
<ref>3</ref>
<paymentRef>1</paymentRef>
<details>
<costGross>99.99</costGross>
<costNet>0.00</costNet>
<costVat>0.00</costVat>
<vatRate>0</vatRate>
<vatDetail>
<vat>
<type>VAT</type>
<amount>0.00</amount>
<rate>0</rate>
</vat>
</vatDetail>
</details>
</payment>
</payments>
</item>
<item>
<line>4</line>
<id/>
<details>
<itemType/>
<clientCode/>
<styleCode/>
<itemName>Product B</itemName>
<clientSku/>
<sku>54NV2</sku>
<serialNumber/>
<optionName/>
<localName/>
</details>
<shipToAddress>
<personRef>1</personRef>
<addressRef>3</addressRef>
</shipToAddress>
<payments>
<payment>
<ref>4</ref>
<paymentRef>1</paymentRef>
<details>
<costGross>10.00</costGross>
<costNet>0.00</costNet>
<costVat>0.00</costVat>
<vatRate>0</vatRate>
<vatDetail>
<vat>
<type>VAT</type>
<amount>0.00</amount>
<rate>0</rate>
</vat>
</vatDetail>
</details>
</payment>
</payments>
</item>
<item>
<line>5</line>
<id/>
<details>
<itemType/>
<clientCode/>
<styleCode/>
<itemName>Product B</itemName>
<clientSku/>
<sku>54NV2</sku>
<serialNumber/>
<optionName/>
<localName/>
</details>
<shipToAddress>
<personRef>1</personRef>
<addressRef>3</addressRef>
</shipToAddress>
<payments>
<payment>
<ref>5</ref>
<paymentRef>1</paymentRef>
<details>
<costGross>10.00</costGross>
<costNet>0.00</costNet>
<costVat>0.00</costVat>
<vatRate>0</vatRate>
<vatDetail>
<vat>
<type>VAT</type>
<amount>0.00</amount>
<rate>0</rate>
</vat>
</vatDetail>
</details>
</payment>
</payments>
</item>
<item>
<line>6</line>
<id/>
<details>
<itemType/>
<clientCode/>
<styleCode/>
<itemName>Product C</itemName>
<clientSku/>
<sku>54NV2</sku>
<serialNumber/>
<optionName/>
<localName/>
</details>
<shipToAddress>
<personRef>1</personRef>
<addressRef>3</addressRef>
</shipToAddress>
<payments>
<payment>
<ref>6</ref>
<paymentRef>1</paymentRef>
<details>
<costGross>25.75</costGross>
<costNet>0.00</costNet>
<costVat>0.00</costVat>
<vatRate>0</vatRate>
<vatDetail>
<vat>
<type>VAT</type>
<amount>0.00</amount>
<rate>0</rate>
</vat>
</vatDetail>
</details>
</payment>
</payments>
</item>
<item>
<line>7</line>
<masterLine>6</masterLine>
<id/>
<details>
<itemType>SERVICE</itemType>
<clientCode/>
<styleCode/>
<itemName>Gift Wrap</itemName>
<clientSku/>
<sku>GW123</sku>
<serialNumber/>
<optionName/>
<localName/>
</details>
<shipToAddress>
<personRef>1</personRef>
<addressRef>3</addressRef>
</shipToAddress>
<payments>
<payment>
<ref>7</ref>
<paymentRef>1</paymentRef>
<details>
<costGross>25.75</costGross>
<costNet>0.00</costNet>
<costVat>0.00</costVat>
<vatRate>0</vatRate>
<vatDetail>
<vat>
<type>VAT</type>
<amount>0.00</amount>
<rate>0</rate>
</vat>
</vatDetail>
</details>
</payment>
</payments>
</item>
</items>
</order>
</orderNew>
return new
The Return New feed informs the OMS of a return received by the LSP (or other return location). It defines the returned items and the reasons for the return
| Sender / Receiver | LSP > OMS (or other parties where necessary) |
| Frequency | When the LSP triggers the feed |
| Format | XML |
| Transport | sFTP |
| Filename | <client>_return-new_YYYYMMDDHH24MISSUUUUUU.xml |
| Acknowledgement | ACK_<CLIENT>return-new<Timestamp>.xml |
Schema
Overview
Examples
<?xml version="1.0" encoding="UTF-8"?>
<returnNew version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../schema/return-new.xsd">
<client>CLIENT</client>
<orderId>DE-1414203</orderId>
<source>FIGDE02</source>
<lines>
<line>
<line>1</line>
<orderLine>2</orderLine>
<details>
<reason>01</reason>
<reasonDescription>Too wide in the shoulders</reasonDescription>
<condition>GOOD</condition>
</details>
</line>
</lines>
</returnNew>
ack
The Ack feed provides success or failure information regarding the importation of a feed from an external system in the OMS. Please refer to each feed documentation to check if an acknowledgment is provided.
| Sender / Receiver | OMS > External systems |
| Frequency | Each time a feed is processed |
| Format | XML |
| Transport | sFTP |
| Filename | ACK_<Feed Name>.xml |
| Acknowledgement | Not applicable |
Schema
Overview
Example
Success
<?xml version="1.0" encoding="UTF-8"?>
<ack version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../schema/ack.xsd">
<client>CLIENT</client>
<request>returnDetail</request>
<resultCode>OK</resultCode>
<result>RMA-21</result>
</ack>
Failure
<?xml version="1.0" encoding="UTF-8"?>
<ack version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../schema/ack.xsd">
<client>CLIENT</client>
<request>returnDetail</request>
<resultCode>FAIL</resultCode>
<result>Line 1 already returned</result>
</ack>
Outgoing
shipment-request
The Shipment Request feed contains a new shipment request from the OMS to the LSP. In the item section, all items to be shipped are detailed. There is also a section with the payment information.
| Sender / Receiver | OMS > LSP |
| Frequency | Processed as soon as the fraud check has been completed successfully |
| Format | XML |
| Transport | sFTP |
| Filename | <client>_shipment-request_YYYYMMDDHH24MISSUUUUUU.xml |
| Acknowledgement | <client>_shipment-request_YYYYMMDDHH24MISSUUUUUU_ACK.xml |
For more information about generating a feed for shipment request exports, see the Order details topic.
Schema
Overview
Examples
<?xml version="1.0"?>
<shipmentRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0" xsi:noNamespaceSchemaLocation="../../schema/shipment-request.xsd">
<client>CLIENT</client>
<distributionCentre>FIGDE02</distributionCentre>
<externalId>ORDEREXTERNALID-01</externalId>
<order>
<ref>12186</ref>
<id>900101960</id>
<store><![CDATA[GB]]></store>
<details>
<created><![CDATA[2013-12-18T11:38:32Z]]></created>
<customer>868779</customer>
<ip>2.50.43.110</ip>
<language>en-GB</language>
<vatCountry>GB</vatCountry>
<origin>WEB</origin>
<originDate><![CDATA[2013-12-18T10:21:23Z]]></originDate>
<customerReference>Deliver next door</customerReference>
<csAgent/>
<shippingMethod>STANDARD</shippingMethod>
</details>
<people>
<person>
<ref>9932</ref>
<title>Lady</title>
<firstName>Jane</firstName>
<lastName>Doe</lastName>
<phone>123456789</phone>
<fax>123456789</fax>
<mobile>123456789</mobile>
<email><![CDATA[jane@jane.com]]></email>
<department/>
<companyName/>
<gender>M</gender>
<dateofbirth>1980-01-30</dateofbirth>
</person>
</people>
<addresses>
<address>
<ref>8342</ref>
<addresstype>customer</addresstype>
<address1><![CDATA[whalley close]]></address1>
<address2><![CDATA[17]]></address2>
<city>Roitham</city>
<state/>
<zip>4661</zip>
<country>
<code>AT</code>
<name>AUSTRIA</name>
</country>
</address>
<address>
<ref>8343</ref>
<addresstype>customer</addresstype>
<address1><![CDATA[Church road]]></address1>
<address2><![CDATA[33]]></address2>
<city>London</city>
<state/>
<zip>NW4 4EB</zip>
<country>
<code>GB</code>
<name>UNITED KINGDOM</name>
</country>
</address>
</addresses>
<payments>
<payment>
<ref>4567</ref>
<currency>EUR</currency>
<transactions>
<transaction>
<details>
<method>paypal</method>
<submethod>paypal</submethod>
<amount>28.15</amount>
</details>
<billToAddress>
<personRef>9932</personRef>
<addressRef>8343</addressRef>
</billToAddress>
</transaction>
</transactions>
</payment>
</payments>
<items>
<item>
<ref>41927</ref>
<line>1</line>
<id/>
<details>
<itemType>PHYSICAL</itemType>
<clientCode>6BGTT034</clientCode>
<styleCode>6BGTT034</styleCode>
<itemName/>
<clientSku>SKU1</clientSku>
<sku>SKU1</sku>
<serialNumber/>
<optionName><![CDATA[GT360]]></optionName>
<localName><![CDATA[GT360]]></localName>
<catalogId>500</catalogId>
<merchantId>RETAILER NAME</merchantId>
</details>
<shipToAddress>
<personRef>9932</personRef>
<addressRef>8342</addressRef>
</shipToAddress>
<payments>
<payment>
<ref>4567</ref>
<paymentRef>4567</paymentRef>
<details>
<costGross>49.95</costGross>
<costNet>39.96</costNet>
<costVat>9.99</costVat>
<vatRate>25</vatRate>
<vatDetail>
<vat>
<type>VAT</type>
<amount>9.99</amount>
<rate>25.00</rate>
</vat>
</vatDetail>
</details>
<status>
<code>AUTHORISED</code>
<name>Authorised</name>
</status>
</payment>
</payments>
</item>
<item>
<ref>41928</ref>
<line>2</line>
<id/>
<details>
<itemType>PHYSICAL</itemType>
<clientCode>6BGTT034</clientCode>
<styleCode>6BGTT034</styleCode>
<itemName/>
<clientSku>SKU2</clientSku>
<sku>SKU2</sku>
<serialNumber/>
<optionName><![CDATA[GT369]]></optionName>
<localName><![CDATA[GT369]]></localName>
<catalogId>500</catalogId>
<merchantId>RETAILER NAME</merchantId>
</details>
<shipToAddress>
<personRef>9932</personRef>
<addressRef>8342</addressRef>
</shipToAddress>
<payments>
<payment>
<ref>4567</ref>
<paymentRef>4567</paymentRef>
<details>
<costGross>49.95</costGross>
<costNet>39.96</costNet>
<costVat>9.99</costVat>
<vatRate>25</vatRate>
<vatDetail>
<vat>
<type>VAT</type>
<amount>9.99</amount>
<rate>25.00</rate>
</vat>
</vatDetail>
</details>
<status>
<code>AUTHORISED</code>
<name>Authorised</name>
</status>
</payment>
</payments>
</item>
<item>
<ref>41927</ref>
<line>3</line>
<id/>
<details>
<itemType>PHYSICAL</itemType>
<clientCode>6BGTT034</clientCode>
<styleCode>6BGTT034</styleCode>
<itemName/>
<clientSku>SKU3</clientSku>
<sku>SKU3</sku>
<serialNumber/>
<optionName><![CDATA[GT363]]></optionName>
<localName><![CDATA[GT363]]></localName>
<catalogId>500</catalogId>
<merchantId>RETAILER NAME</merchantId>
</details>
<shipToAddress>
<personRef>9932</personRef>
<addressRef>8342</addressRef>
</shipToAddress>
<payments>
<payment>
<ref>4567</ref>
<paymentRef>4567</paymentRef>
<details>
<costGross>49.95</costGross>
<costNet>39.96</costNet>
<costVat>9.99</costVat>
<vatRate>25</vatRate>
<vatDetail>
<vat>
<type>VAT</type>
<amount>9.99</amount>
<rate>25.00</rate>
</vat>
</vatDetail>
</details>
<status>
<code>AUTHORISED</code>
<name>Authorised</name>
</status>
</payment>
</payments>
</item>
<item>
<ref>41928</ref>
<line>4</line>
<id/>
<details>
<itemType>SHIPPING</itemType>
<clientCode>SHIPPING</clientCode>
<styleCode>SHIPPING</styleCode>
<itemName>Shipping</itemName>
<clientSku>STANDARD</clientSku>
<sku>STANDARD</sku>
<serialNumber/>
<optionName><![CDATA[Standard]]></optionName>
<localName><![CDATA[Standard Shipping]]></localName>
</details>
<shipToAddress>
<personRef>9932</personRef>
<addressRef>8342</addressRef>
</shipToAddress>
<payments>
<payment>
<ref>4567</ref>
<paymentRef>4567</paymentRef>
<details>
<costGross>12</costGross>
<costNet>9.6</costNet>
<costVat>2.4</costVat>
<vatRate>25</vatRate>
<vatDetail>
<vat>
<type>VAT</type>
<amount>2.40</amount>
<rate>25.00</rate>
</vat>
</vatDetail>
</details>
<status>
<code>REQUESTED</code>
<name>Requested</name>
</status>
</payment>
</payments>
</item>
</items>
</order>
</shipmentRequest>
return request
The Return Request feed informs the warehouse that a return will be received by the LSP (or other return location). This field should be used to anticipate future returns to the warehouse and provide them the RMA numbers.
| Sender / Receiver | LSP > OMS (or other parties where necessary) |
| Frequency | When the LSP triggers the feed |
| Format | XML |
| Transport | sFTP |
| Filename | <client>_return-request_YYYYMMDDHH24MISSUUUUUU.xml |
| Acknowledgement | ACK_<CLIENT>return-request<Timestamp>.xml |
Schema
Overview
Examples
<?xml version="1.0" encoding="UTF-8"?>
<returnRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../schema/return-request.xsd">
<client>CLIENT</client>
<orderId>CLIENTID-1414203</orderId>
<rmaCode>RMA-CS-EXTERNALID-2</rmaCode>
<source>SOURCE</source>
<items>
<item>
<line>1</line>
<orderLine>2</orderLine>
<details>
<reason>01</reason>
<reasonDescription>Too wide in the shoulders</reasonDescription>
<sku>SKU1</sku>
<clientSku>SKU1</clientSku>
<optionName><![CDATA[SKU1_OPTION]]></optionName>
<localName><![CDATA[SKU1_LOCAL]]></localName>
</details>
</item>
</items>
</returnRequest>
order status
The Order Status feed includes all order item statuses and the status of the overall order. If an order has left the warehouse, it additionally includes order tracking information.
| Sender / Receiver | OMS > Front-end (or other parties where necessary) |
| Frequency | Sent to the front-end whenever an order status changes |
| Format | XML |
| Transport | sFTP |
| Filename | <client>_order-status_YYYYMMDDHH24MISSUUUUUU.xml |
| Acknowledgement | <client>_order-status_YYYYMMDDHH24MISSUUUUUU_ACK.xml |
Schema
Overview
Examples
<?xml version="1.0" encoding="UTF-8"?>
<orderStatus xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0" xsi:noNamespaceSchemaLocation="../../schema/order-status.xsd">
<client>CLIENT</client>
<order>
<id>900102009</id>
<store>FR</store>
<status>
<code>COMPLETE</code>
<name>Complete</name>
<reasonCode>PARTIALLYSHIPPED</reasonCode>
<reasonName>Order processing completed</reasonName>
<date>2013-12-19T09:33:09Z</date>
</status>
<items>
<item>
<ref>42067</ref>
<line>1</line>
<id/>
<status>
<code>SHIPPED</code>
<name>Shipped</name>
<reasonCode>OSREPORT</reasonCode>
<reasonName>Reported shipped in OS feed</reasonName>
<date>2013-12-19T09:33:08Z</date>
</status>
<payment>
<status>AUTHORISED</status>
</payment>
</item>
<item>
<ref>42068</ref>
<line>2</line>
<id/>
<status>
<code>CANCELLED</code>
<name>Cancelled</name>
<reasonCode>OUTOFSTOCK</reasonCode>
<reasonName>Out of stock</reasonName>
<date>2013-12-18T11:40:30Z</date>
</status>
<payment>
<status>CANCELLED</status>
</payment>
</item>
<item>
<ref>42069</ref>
<line>3</line>
<id/>
<status>
<code>SHIPPED</code>
<name>Shipped</name>
<reasonCode>OSREPORT</reasonCode>
<reasonName>Reported shipped in OS feed</reasonName>
<date>2013-12-19T09:33:08Z</date>
</status>
<payment>
<status>CAPTURED</status>
</payment>
</item>
</items>
<packages>
<package>
<packageId>34324</packageId>
<carrier>CARRIER</carrier>
<trackingNumber>123</trackingNumber>
<boxNumber>456</boxNumber>
<trackingLink>http://www.test.com/track?tn=123</trackingLink>
<lines>
<line>
<orderItemRef>42067</orderItemRef>
<orderLine>1</orderLine>
<orderItemId>123123</orderItemId>
</line>
<line>
<orderItemRef>42069</orderItemRef>
<orderLine>3</orderLine>
<orderItemId>123123</orderItemId>
</line>
</lines>
</package>
</packages>
</order>
</orderStatus>
refund status
The Refund Status feed informs the front-end of refunds processed by the OMS, the refund status and the reasons of the refund.
| Sender / Receiver | OMS > Front-end (or other parties where necessary) |
| Frequency | Near real time when a refund is released by the OMS (i.e. a request for a refund is sent to the payment gateway) |
| Format | XML |
| Transport | sFTP |
| Filename | <client>_refund-status_YYYYMMDDHH24MISSUUUUUU.xml |
| Acknowledgement | Not applicable |
Schema
Overview
Examples
<refundStatus version="1.0">
<client>CLIENT</client>
<orderId>100000003</orderId>
<storeId>DE</storeId>
<creditNoteNumber>REFUND-CS-100000003-1</creditNoteNumber>
<creditNoteDate>2013-12-19T09:09:09Z</creditNoteDate>
<status>
<code>RELEASED</code>
<name>released</name>
<reasonCode>RECEIVED</reasonCode>
<reasonName>received</reasonName>
<date>2013-12-19T09:33:09Z</date>
</status>
<lines>
<line>
<orderLine>1</orderLine>
<orderItemId>6_1</orderItemId>
<payments>
<payment>
<ref>46413</ref>
<paymentRef>4616</paymentRef>
<details>
<costGross>29.95</costGross>
<costNet>23.96</costNet>
<costVat>5.99</costVat>
<vatRate>25</vatRate>
<vatDetail>
<vat>
<type>VAT</type>
<amount>5.99</amount>
<rate>25.00</rate>
</vat>
</vatDetail>
</details>
<status>
<code>CAPTURED</code>
<name>Captured</name>
</status>
</payment>
</payments>
</line>
<line>
<orderLine>2</orderLine>
<orderItemId>8_2</orderItemId>
<payments>
<payment>
<ref>46413</ref>
<paymentRef>4616</paymentRef>
<details>
<costGross>29.95</costGross>
<costNet>23.96</costNet>
<costVat>5.99</costVat>
<vatRate>25</vatRate>
<vatDetail>
<vat>
<type>VAT</type>
<amount>5.99</amount>
<rate>25.00</rate>
</vat>
</vatDetail>
</details>
<status>
<code>CAPTURED</code>
<name>Captured</name>
</status>
</payment>
</payments>
</line>
<line>
<orderLine>3</orderLine>
<orderItemId>7_1</orderItemId>
<payments>
<payment>
<ref>46413</ref>
<paymentRef>4616</paymentRef>
<details>
<costGross>29.95</costGross>
<costNet>23.96</costNet>
<costVat>5.99</costVat>
<vatRate>25</vatRate>
<vatDetail>
<vat>
<type>VAT</type>
<amount>5.99</amount>
<rate>25.00</rate>
</vat>
</vatDetail>
</details>
<status>
<code>CAPTURED</code>
<name>Captured</name>
</status>
</payment>
</payments>
</line>
</lines>
</refundStatus>
return status
The Return Status feed informs the front-end of a return received by the LSP (or other return location). It defines the returned items, the return status and the reasons for the return.
| Sender / Receiver | OMS > Front-end (or other parties where necessary) |
| Frequency | Near real time when a return request has been created or a return has |
| Format | XML |
| Transport | sFTP |
| Filename | <client>_return-status_YYYYMMDDHH24MISSUUUUUU.xml |
| Acknowledgement | <client>_return-status_YYYYMMDDHH24MISSUUUUUU_ACK.xml |
Schema
Overview
Examples
<?xml version="1.0" encoding="UTF-8"?>
<returnStatus version="1.0">
<client>CLIENT</client>
<orderId>100000003</orderId>
<storeId>DE</storeId>
<source>FIGDE02</source>
<rma>RMA-CS-100000003-3</rma>
<status>
<code>APPROVED</code>
<name>requested</name>
<reasonCode>RECEIVED</reasonCode>
<reasonName>received</reasonName>
<date>2013-12-19T09:33:09Z</date>
</status>
<lines>
<line>
<line>1</line>
<orderLine>7_1</orderLine>
<orderItemId>7_1</orderItemId>
<details>
<reason>01</reason>
<reasonDescription>Too wide in the shoulders</reasonDescription>
<condition>GOOD</condition>
</details>
</line>
<line>
<line>2</line>
<orderLine>7_2</orderLine>
<orderItemId>7_2</orderItemId>
<details>
<reason>01</reason>
<reasonDescription>Too wide in the shoulders</reasonDescription>
<condition>GOOD</condition>
</details>
</line>
<line>
<line>3</line>
<orderLine>8_3</orderLine>
<orderItemId>8_3</orderItemId>
<details>
<reason>01</reason>
<reasonDescription>Too wide in the shoulders</reasonDescription>
<condition>GOOD</condition>
</details>
</line>
</lines>
</returnStatus>
File management - How to integrate with Magento OMS
How to connect to the sFTP server
The connection will be through our SFTP server (SSH encryption). Magento will provide you with the account details for connecting to our server.
SFTP folder structure
The OMS sFTP folder structure will follow this set of rules:
- The 3rd-Parties will exchange feeds with OMS under the folder DATA;
- Under the DATA folder, two main folders will be used: inbox (for Incoming files) and outbox (for Outgoing files);
- Each feed type (e.g. item-adjustment, inventory-snapshot, etc.) has its folder inside the folders inbox and outbox;
- Inside each inbox/feed-name folder, there are the folders transfer, queue, processed, error and ack;
- Inside each outbox/feed-name folder, there are the folders queue and processed.
Incoming files (Inbox)
Whenever a file is sent to the OMS, the following 2 step procedure must be accomplished (always under inbox/feed-name folder):
- The file must be uploaded to the transfer folder;
- Once the file has been fully uploaded to the sFTP and for OMS to process the file, the sender must move it to the queue folder, from where it will be collected and processed.
From the moment where the OMS reads the file, there are four possible cases:
- The file does not follow the naming pattern – the file is skipped;
- The XML file is not well formed or is not valid (does not validate schema) – the file is moved to the error folder; an ACK file is generated and stored in the ack folder;
- There is a business error in the file – the file is moved to the error folder; an ACK file is generated and stored in the ack folder;
- The data in the file is correct, and it is imported into the OMS system – the file is moved to the processed folder; an ACK file is generated and stored in the ack folder.
Outgoing files (Outbox)
Whenever OMS generates outgoing feeds, files are stored in the outbox/feed-name/queue folder.
When the client wants to acknowledge the reception of the file, has to move it to the outbox/”
Validate Examples
Here are the steps to validate the examples shown above:
- Go to the folder where you have your XML and XSD files.
- Use a program to validate an XML file (i.e. examples) against the XSD files and reports on any differences. For instance, you can use “xmllint”.
- Compare the two files. Using the previous program and taking the Return-Status feed as an example, the command will be:
xmllint samples/return-status.xml –schema XSD/return-status.xsd - And check the results: validates or fails to validate.