XML interfaces

Introduction

The purpose of this document is to:

  • Provide an overview of the logistic XML interfaces of Magento Order Management System (Magento OMS)
  • Explain the OMS sFTP folder structure used file conventions to follow for incoming and outgoing files
  • Steps for validating examples

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

XSD-file

Overview

XML-Diagram

Examples

Example

<?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>_stockNadjustment_YYYYMMDDHH24MISSUUUUUU.xml
Acknowledgement ACK_<CLIENT>_shipmentNresponse_<Timestamp>.xml (optional)

Schema

XSD-file

Overview

XML-Diagram

Examples

Example

<?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

XSD-file

Overview

XML-Diagram

Examples

Example

<?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

XSD-file

Overview

XML-Diagram

Examples

Example

<?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

XSD-file

Overview

XML-Diagram

Examples

Example

<?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

XSD-file

Overview

XML-Diagram

Examples

Example

<?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

XSD-file

Overview

XML-Diagram

Example

Success

Example

<?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

Example

<?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

Schema

XSD-file

Overview

XML-Diagram

Examples

Example

<?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

XSD-file

Overview

XML-Diagram

Examples

Example

<?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

XSD-file

Overview

XML-Diagram

Examples

Example

<?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

XSD-file

Overview

XML-Diagram

Examples

Example

<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

XSD-file

Overview

XML-Diagram

Examples

Example

<?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/ folder, there are the folders transfer, queue, processed, error and ack;
  • Inside each outbox/ folder, there are the folders queue and processed.

folder structure

Incoming files (Inbox)

Whenever a file is sent to the OMS, the following 2 step procedure must be accomplished (always under inbox/ 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.

incoming file flow

Outgoing files (Outbox)

Whenever OMS generates outgoing feeds, files are stored in the outbox//queue folder. When the client wants to acknowledge the reception of the file, has to move it to the outbox/""/processed folder.

outgoing file flow

Validate Examples

Here are the steps to validate the examples shown above:

  1. Go to the folder where you have your XML and XSD files.
  2. 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”.
  3. 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
  4. And check the results: validates or fails to validate.