Order Flow

You can use the Order data format specification to transfer order-related information between Walmart.com and all suppliers, including Direct Ship Vendors. This information provides guidelines for using the Order interface.

Note: You can also refer to this article in Word format: Walmart.com Drop Ship Vendor_Order Interfaces_XML.docx

Data Files

The Order interface supports these data files:

• Order Request File – Contains customer order requests (Sent from Walmart.com to Supplier only).
• Order Cancel File – Contains customer order cancellation requests (Sent from Walmart.com to Supplier only).
• Order Status File – Contains customer order status updates (Sent from Supplier to Walmart.com only). Response files supported by these interfaces are as follows:
  • Confirmation File – Contains a file confirmation (Sent both directions between Supplier and Walmart.com).
  • Error File – Contains a file error message (Sent in both directions between Supplier and Walmart.com).

File transfer workflow

Each file transfer is divided into three basic steps:

1. The sender generates a data file and pushes it to the recipient's server.
2. The recipient parses the received file and validates the file format and data consistency.
3. If the file parses, the recipient replies with a Confirmation File to the sender. Otherwise, reply with an Error File.

Interface Design and Implementation

System Requirements

• Messages are sent between Walmart.com and the DSV as ASCII text files in XML format. After creating a file, its creator pushes it to the recipient.

Order Process Flow
These are the steps in the order process flow starting with a purchase on the Walmart.com website:

1. The process is initiated when a customer places an order on the Walmart.com website, and their credit card is authorized for the purchase amount.
2. Once the credit card is successfully authorized, the customer order is split into multiple order requests, if necessary. An order request will contain all the line items for a particular supplier (customer's order can have multiple sources) at a particular shipping address (customer's order can have multiple shipping addresses) using the same shipping method (customer's order can have multiple shipping methods). Each order request is included as an OR_ORDER element in the next scheduled Order Request File delivered to the appropriate supplier.
3. When the Order Request File arrives at the supplier, they parse the file and validate the XML message against the v4.0 DTD. If the message is invalid, they send an Error File back to Walmart.com. Otherwise, they send back a Confirmation File and continue processing.
4. The supplier processes each OR_ORDER in the Order Request File and checks for data errors. If an error is found, they send an Error File back to Walmart.com and stop processing the bad order. There are two exceptions to this error processing rule when an Order Status File is sent back instead:
   1. Unrecognized Item – If the order request line item isn't recognized in the supplier's system, send back a line STATUSCODE of “LU”.
   2. Discontinued Item – If the order request line item refers to a discontinued (no longer available) item in the supplier's system, send back a line STATUSCODE of “LD”.
5. Once an OR_ORDER is loaded into the supplier's order processing system, they generate an Order Status File to acknowledge each order line. This response can be different for each of the two general cases:
   1. In Stock Items – If an item is available immediately, then respond with a line STATUSCODE of “LI” for each line. This message is due within four hours of receiving the Order Request File and indicates that the line will ship in one to two business days.
   2. On-Demand Items – If the item is not available immediately but will become available within a timeframe, then respond with a line STATUSCODE of “LH” to indicate that the line is “on hold” in the supplier’s system and will ship when available. This is identified in two ways:
   • Supplier sends a line STATUSCODE of “LH” within four hours of receiving the Order Request File.
   • Supplier sends a line STATUSCODE of “LI” within four hours of receiving the Order Request File to satisfy the initial acknowledgment requirement. Then, a line STATUSCODE of “LH” is sent within one to two business days to put the line on hold.
     Note: Walmart.com records item availability at the time the order is placed, as reported by each DSV in Item Inventory File. The line is expected to not be on hold past the maximum availability time. See DSV Inventory Interfaces Spec v4.0.
6. As the supplier picks items and packages them for shipment, they might receive a cancellation request or find out that all the items (per line) aren't, available to ship. Here are the corresponding order line responses:
   • Canceled Line – The supplier will cancel an order request line only after receiving a cancellation request from Walmart.com (via verbal request, automated e-mail message, or Order Cancel File). In this case, send back a line STATUSCODE of “LC,” and it will cancel all items in the line.
   • Fully Backordered Line – If all items in a line are not available to ship, send back a line STATUSCODE of “LB” and set the QUANTITY equal to the number of items ordered. This transfers control back to the Walmart.com system, and another order request will be generated when the items return to stock. The outstanding items will not remain live in the supplier's system.
   • Partially Backordered Line (Not Applicable for Drop Ship Suppliers – only for Walmart.com owned item facilities) – If some items in a line are not available to ship, then send back a line STATUSCODE of “LB” and set the QUANTITY equal to the number of items not available. Then send a package invoice message to reflect the number of items shipped (see below). This transfers control back to the Walmart.com system for the outstanding items, and another order request will be generated when the items return to stock. The outstanding items will not remain live in the supplier’s system.
     Note: Backorders aren’t accepted for “Build to Order” DSV items with inventory availability code of “BO”. For more information, see the Item Inventory File section of the DSV Inventory Interfaces Specification, v4.0.0.
7. Once the items are available, the supplier packages them and ships them according to the requested shipping method. The package should have a Walmart.com shipping label on the outside. The supplier also sends a package invoice message in the Order Status File that reflects the shipping details and an invoice to Walmart.com with the cost of goods and services. Here are the possible package fulfillment cases:
   • Electronic Delivery Item – If the line contains a “virtual” item downloaded over the internet, then send back a package STATUSCODE of “PE”.
   • External Carrier Shipment – If all items were shipped via an external carrier (e.g. UPS, FedEx, Airborne, etc.), then send back an OS_PACKAGEINVOICE message for each unique tracking number and a package STATUSCODE of “PS”.
   • In-Store Delivery via Wal-Mart Fleet Carrier – If the items are to be picked up at a Walmart store and are delivered via a Walmart fleet truck, then send back a package STATUSCODE of “PT” and a unique tracking number to indicate that the items are in transit. Once the items arrive and are available for pickup, send a package STATUSCODE of “PA” with the same package ID and tracking number.
8. Walmart.com keeps track of the items shipped. If some order lines are back ordered, Walmart.com keeps the order alive and sends another request once the items are back in stock. The new request will not return to the original order request but will have the same customer order number.
9. Walmart.com bills the customer's card and pays each DSV (through the Wal-Mart accounts payable system) for items shipped.

Error Handling/Resend Process
Will use Error Files for messaging. There are two types of error response:

1. The received file is incomplete or invalid against the v4.0 DTD. In this case, the entire file is bad, and it's assumed that no data was processed. The sender will receive only the Error File (no Confirmation File) and error messageresend a valid file as soon as possible.
2. File contains a message with bad data. In this case, only the message containing the error is rejected, and all other messages in the file are processed. For example, if Walmart.com processes an Item Inventory file with 10 II_ITEM messages and finds 2 messages that contain bad data, then the following will occur:
   • Supplier sends a Confirmation File because the file is complete and valid against the v4.0 DTD.
   • Supplier sends back an Error File with 2 FE_ERROR elements detailing the bad OR_ORDER messages.
   • Supplier processes the other 48 OR_ORDER messages.
   • Walmart.com resends the OR_ORDER messages in a subsequent file.

Scheduling & Volume Analysis
The expected order volume is different for each supplier. Estimates can be obtained from the Walmart.com Logistics and/or Merchandising Teams. Variations on the standard schedule (as described below) can be negotiated between each supplier and the Walmart.com Logistics Team. Outbound Walmart.com messages are generated as follows:

• Order Request and Order Cancel Files – A batch job queries database for order and cancel requests every X(will be defined by partner) minutes (24x7x365). If requests are present and ready to be transmitted, then the job generates an XML message to the appropriate supplier and transmits it right away. If no requests are present for a particular supplier, no messages are sent.
• Confirmation and Error Files – One or both of these messages are generated as each inbound file is processed (if applicable). The messages are placed in an outbound queue and transmitted right away.

Inbound Walmart.com messages are processed as they are uploaded to the gateway server. Each supplier is expected to send files as follows:

• Initial Confirmation or Error Files – For each file transmitted to the supplier, a Confirmation or Error File response is expected within one hour of the transmission. This acknowledges the receipt of the file and indicates whether the file passed file validation checks.
• Processing Error Files – As the supplier processes each file, an Error File is generated if bad data is found. This error message (if applicable) is expected within four hours of file transmission.
• Order Request Line Status – If an order request is processed without format or data errors, an Order Status File with an acknowledgment status of “LI” or “LH” is expected within four hours. Alternatively, the supplier could send a non-fulfillment status of “LD”, “LU” or “LB” in the first four hours – or after the acknowledgement and before the package fulfillment message is expected (see below).
• Order Request Line Cancellation Status – The Order Status response to an Order Cancel File is expected in the same timeframe as the package fulfillment response below. This might be a line cancellation of “LC” or a package fulfillment message.
• Order Request Package Fulfillment – The supplier sends an Order Status File with a package fulfillment status of “PS”, “PE” or “PT” as each package is sent. The timing of these messages for each order request line depends on the item type and stated availability.

General XML File Structure

Initial XML Declaration
The first line of the file defines the XML Standard version and the character encoding used in the file. The format for this is as follows:

XML Data Definition
Each data element (and its component attributes and sub-elements) is described in this document with the following information:

• XPath Location: The location of each element or attribute within the data element is defined based on Xpath notation.

  • If the Xpath begins with a “/” character, then it’s absolute within the XML message (e.g. “/WMI/WMIHEADER/FH_TO@ID”).
  • If the Xpath begins with any other character, then it’s relative to the specified reference node (e.g. “FH_TO@ID”, with a reference node of “/WMI/WMIHEADER”).

  For more information, go to http://www.w3.org/TR/xpath.

• Optional/Required: Specifies whether each element or attribute is required to populate its parent element.

  • If optional, the element or attribute can be populated with no data or omitted entirely. Note that most optional data must be populated based on certain conditional business rules, so this must be considered when validating the file.
  • If required, the element or attribute must exist and might not be empty.

• Data Type: Specifies the type of data that's contained in an element or attribute.

  • “STR” – A string value that can contain alphanumeric characters and punctuation. This is parsed data, so any XML markup delimiters must be escaped with a character string as follows:

    • Replace greater than (>) with “>”
    • Replace less than (<) with “<”
    • Replace ampersand (&) with “&”
    • Replace double-quote (“) with “"”
    • Replace apostrophe (‘) with “'”
    • For more information, go to http://www.w3.org/TR/REC-xml

  • “DEC” – A decimal value that contains only numeric data and a decimal point. If the decimal is not present, it’s implied at the end.

  • “NUM” – Numeric data containing no alphabetic characters or punctuation.

  • “DTM” – A formatted date/time value containing only numeric and punctuation characters. It is formatted as “MM/DD/CCYY.hh24.mi”, where “MM/DD/CCYY” is the date and “hh24.mi” is the 24-hour time (e.g. “12/11/2001.17.01”).

  • “FID” – A formatted File ID that contains only numeric and punctuation characters. It is built from the file generation date and time, the WMFC vend,or number and a six-digit random number (to guarantee uniqueness). The format is:
    VVVVVVVVV.YYYYMMDD.HHMMSS.NNNNNN
    Using the following notation:

    • VVVVVVVVV is the Vendor ID assigned by Walmart.com (1 to 9 digits)
    • YYYYMMDD is an eight-digit file creation date (GMT date)
    • HHMMSS is a six-digit file creation time (24-hour GMT time)
    • NNNNNN is a six-digit random number.

    Note that these are the same fields used to generate an XML filename. The filename and the File ID will use the same date, time, and random number values.

• Data Length: Specifies the maximum length of the data as follows:

  • “STR” – Number of character digits. Note: When a character is escaped, the length of the data string expands. The length of the data string may be up to 6 times the number of string characters (for a case with all double-quote characters).
  • “DEC” – Expressed as “N.D” notation, where “N” is the number of characters allowed to the left of the decimal and “D” is the number of digits to the right. Note: Leading zeros are not required.
  • “NUM” – Number of numeric digits.
  • “DTM” – Number of characters in the formatted string.
  • “FID” – Number of characters in the formatted string.

WMIHEADER Element
The WMIHEADER element is the first element in any file. It contains a unique file ID, the sender's name, vendor number, and information for contacting the sender.

Note: Use one of the two below values for the FILETYPE value:

• FFC: File contains WMIFILECONFIRM data element
• FFE: File contains WMIFILEERROR data element
• FOR: File contains WMIORDERREQUEST data element.
• FOC: File contains WMIORDERCANCEL data element.
• FOS: File contains WMIORDERSTATUS data element.

Order Request XML File

The Order Request File contains detailed information required to fulfill customer order requests.

File Naming Convention
The file name contains the file type, creation date and time, the Supplier ID, and a six-digit random number. All filenames are case-sensitive. The naming convention is:
WMI_Order_Req_VVVVVVVVV_YYYYMMDD_HHMMSS_NNNNNN.xml

• VVVVVVVVV is the Supplier ID assigned by Walmart.com (up to 9 digits)
• YYYYMMDD is a formatted file creation date (GMT date)
• HHMMSS is a formatted file creation time (24-hour GMT time)
• NNNNNN is a six-digit random number to guarantee uniqueness.

Example: WMI_Order_Req_999999_20010418_163108_097981.xml
WMIORDERREQUEST Element
The WMIORDERREQUEST element contains a group of order request messages. Each order request message tells the supplier to pack and ship items to a customer. If data is missing or invalid, OR_ORDER elements can be individually rejected via an Error File (see the previous error handling section).

Line VASCODE Values
The following list provides details on the Line VASCODE Values

• VGT: Gift Tag with TO and FROM messages (30 characters max for each)
• VGM: Gift Message with LINE1, LINE2, LINE3, LINE4 messages (30 characters max for each)
• VGW: Gift Wrap with UPC (13-digit numeric)
• VCD: Customs Declaration with CDFLAG (character value ‘Y’)
• VPR: Puerto Rico Customs Declaration with PRCDFLAG (character value ‘Y’)
• VOI: Outer Invoice on carton with INVOICE (character value ‘Y’)
• VSR: Signature on delivery with SOD (character value ‘Y’)

Shipping CARRIERMETHODCODE Values
The applicable carrier method codes from the following list is provided before the start of testing.

TC number Calculations
TC number is calculated in OMS (Order Management System) and encrypted using ISD-provided code. Unencrypted, it's comprised of:

• Store Number – 4 digits
• Terminal ID = 3 digits
• Transaction ID – 4 digits
• Amount in cents – 7 digits
• Year of sale – 2 digits
• Day of year – 3 digits

For Walmart.com, store number is 2677, transaction ID is 4 last digits of PO number, and terminal ID is next 2 digits of PO number.
Example: TCNUMBER=”46708052813539595453″
Store# – 2677
PO# (last 6 digits) 675342
Amount – $97.88
Date of sale – 3/12/06

Sample WMIORDERREQUEST Files

---

S2HS2SGIFTCARDPAYPALPROMOTIONGIFTS2HS2SGIFTCARDPAYPALPROMOTIONGIFT

<?xml version="1.0" encoding="UTF-8"?>
<WMI> <WMIFILEHEADER FILEID="123456.20060410.001714.909268" FILETYPE="FOR" VERSION="4.0.0"> <FH_TO ID="123456" NAME="Vendor name"/> <FH_FROM ID="2677" NAME="Walmart.com"> <FH_CONTACT NAME="Walmart.com Operations Support" EMAIL="[email protected]" PHONE="6508375465" PHONEEXT=""/> </FH_FROM> </WMIFILEHEADER> <WMIORDERREQUEST> <OR_ORDER REQUESTNUMBER="66851611" ORDERNUMBER="2677127827645"> <OR_DATEPLACED DAY="10" MONTH="04" YEAR="2006"/> <OR_SHIPPING METHODCODE="MP" CARRIERMETHODCODE="22" STORENUMBER="" TOGETHERCODE="SC"> <OR_PHONE PRIMARY="6503555323" PRIMARYEXT="" SECOND="" SECONDEXT=""/> <OR_POSTAL NAME="Steve Kelley" ADDRESS1="112 Dry Creek Road" ADDRESS2="" ADDRESS3="" ADDRESS4="" CITY="Pacifica" STATE="CA" POSTALCODE="94044" COUNTRY="USA"/> <OR_DELIVERYDATE DAY="14" MONTH="04" YEAR="2006"/> <OR_EMAIL/> </OR_SHIPPING> <OR_BILLING ORDERPRICE="45.38"> <OR_PAYMENT METHOD="MC-3951"/> <OR_PHONE PRIMARY="2096011006" PRIMARYEXT="" SECOND="" SECONDEXT=""/> <OR_POSTAL NAME="John Furey" ADDRESS1="1234 Main St" ADDRESS2="" ADDRESS3="" ADDRESS4="" CITY="Stockton" STATE="CA" POSTALCODE="95207" COUNTRY="USA"/> <OR_EMAIL>[email protected]</OR_EMAIL> </OR_BILLING> <OR_RETURNS TCNUMBER="95675952991021084742" METHODCODE="RC"> <OR_POSTAL NAME=" " ADDRESS1="" ADDRESS2="" ADDRESS3="" ADDRESS4="" CITY="" STATE="" POSTALCODE="" COUNTRY=""/> <OR_PERMIT NUMBER="" CITY="" STATE="" POSTALCODE=""/> </OR_RETURNS> <OR_ORDERLINE LINENUMBER="1" LINEPRICE="45.38"> <OR_ITEM ITEMNUMBER="3866121" UPC="2345678902376" SKU="376" DESCRIPTION="Yellow Phalaenopsis Orchid in Blue Ceramic Pot" QUANTITY="1"/> <OR_PRICE RETAIL="29.97" TAX="2.47" SHIPPING="12.94"/> <OR_COST AMOUNT="21.00"/> </OR_ORDERLINE> <OR_LASTDELIVERYMSG LINE1="0" LINE2="0" LINE3="0" LINE4="0"/> <OR_MARKETINGMSG LINE1="0" LINE2="0" LINE3="0" LINE4="0"/> <OR_RETURNSMSG LINE1="0" LINE2="0" LINE3="0" LINE4="0"/> </OR_ORDER> </WMIORDERREQUEST>
</WMI>

Order Cancel XML File

The Order Cancel File contains customer requests to cancel a specific order request line. If it's possible to cancel the line (i.e. the order hasn't been shipped yet), then return a line STATUSCODE of “LC” in the next Order Status File. If the order line can't be stopped, send back the shipping information as usual.
Note: The supplier should only cancel the requested lines. For example, if an order request contains four lines and the supplier receives cancel requests for lines 1, 3, and 4, then line 2 should ship as requested. The request is for all items in the line.

Note: The customer knows there's no guarantee their line can be canceled. However, we expect the supplier to reasonably attempt to stop the shipment.

File Naming Convention
The file name contains the file type, creation date and time, the Supplier ID, and a six-digit random number. All filenames are case-sensitive. The naming convention is:
WMI_Order_Req_VVVVVVVVV_YYYYMMDD_HHMMSS_NNNNNN.xml

• VVVVVVVVV is the Supplier ID assigned by Walmart.com (up to 9 digits)
• YYYYMMDD is a formatted file creation date (GMT date)
• HHMMSS is a formatted file creation time (24-hour GMT time)
• NNNNNN is a six-digit random number to guarantee uniqueness.

Example: WMI_Order_Cancel_999999_20010418_163108_097981.xml
WMIORDERCANCEL Element
The WMIORDERCANCEL element contains a group of order cancel messages. If possible, each order cancel request message tells the supplier to cancel a specific order request line. If data is missing or invalid, OC_LINECANCEL elements can be individually rejected via a WMIFILEERROR file (see the previous error handling section).

Sample WMIORDERCANCEL File

---

<?xml version="1.0" encoding="UTF-8"?>
<WMI> <WMIFILEHEADER FILEID="185124.20080808.150816.000001" FILETYPE="FOC" VERSION="4.0.0"> <FH_TO ID="185124" NAME="Gloria"/> <FH_FROM ID="2677" NAME="Walmart.com"> <FH_CONTACT NAME="Walmart.com Operations Support" EMAIL="[email protected]" PHONE="6508375465" PHONEEXT=""/> </FH_FROM> </WMIFILEHEADER> <WMIORDERCANCEL> <OC_LINECANCEL REQUESTNUMBER="11809403" LINENUMBER="1"/> <OC_LINECANCEL REQUESTNUMBER="11809404" LINENUMBER="2"/> <OC_LINECANCEL REQUESTNUMBER="11809406" LINENUMBER="3"/> <OC_LINECANCEL REQUESTNUMBER="11809408" LINENUMBER="4"/> </WMIORDERCANCEL>
</WMI>

Order Status XML File

The Order Status File contains status updates for order request lines. There are two types of status updates:

• OS_LINESTATUS messages are for cases when an order request line has not been fulfilled. The status can acknowledge the receipt of the line for future fulfillment or indicate that the line can't be fulfilled for a specified reason.
• OS_PACKAGEINVOICE, messages indicate that items were sent to the customer. Within this message is an OS_PACKAGE element to identify the package, an OS_SHIPDATE element to indicate when the package was sent and an OS_INVOICE element to indicate what is contained in the package and how much it cost.

An Order Status File might contain only OS_PACKAGEINVOICE elements, only OS_LINESTATUS elements, or a combination of both element types.

File Naming Convention
The file name contains the file type, creation date and time, the Supplier ID, and a six-digit random number. All filenames are case-sensitive. The naming convention is:
WMI_Order_Req_VVVVVVVVV_YYYYMMDD_HHMMSS_NNNNNN.xml

• VVVVVVVVV is the Supplier ID assigned by Walmart.com (up to 9 digits)
• YYYYMMDD is a formatted file creation date (GMT date)
• HHMMSS is a formatted file creation time (24-hour GMT time)
• NNNNNN is a six-digit random number to guarantee uniqueness.

Example: WMI_Order_Status_999999_20010418_163108_097981.xml

WMIORDERSTATUS Element
The WMIORDERSTATUS element contains a group of order status messages. Each order status message from the supplier contains a status update for a specific set of order request lines. If data is missing or invalid, then OS_LINESTATUS or OS_PACKAGEINVOICE elements can be individually rejected via an Error File (see error handling section above).

Valid OS_LINESTATUS@STATUSCODE values are as follows:

• “LI” – An “initial” line acknowledgment that indicates the order request was loaded and will be fulfilled in the standard time window of 24 to 48 hours.
• “LH” – A “hold” line acknowledgment indicates the order request was loaded and will be fulfilled outside the standard time window.
• “LD” – The line SKU is recognized and has been discontinued, so this line can't be fulfilled.
• “LU” – The line SKU is not recognized, so this line can't be fulfilled.
• “LB” – The line SKU is not in stock and can't be fulfilled at this time, so the supplier has canceled this line.
• “LC” – The line has been canceled by an Order Cancel message, so it will not be fulfilled.
• “LW” – The line should be able to cancel until wm.com receives the status from the distributor that it is not possible to cancel anymore.

ASN(SSC18 barcode) number format rule of creation:

1. Walmart generated ASN number, the 20-digit ASN number is composed of the following:
   • 3-digit leading zeros (example: 000)
   • 7-digit distributor ID (example UPS: 593830; if the distributor ID is more than 7 digits, then we divide it by 1000 and pad leading zeros)
   • 9-digit sequence with a leading zero (example: 032000314)
   • 1-digit checksum, which is calculated using the MOD 10 algorithm.
2. Distributor generated ASN number; we only have IML at this time.
   • The first 10 digits of the ASN are 0000511873.
   • The next 10 digits comprise their warehouse ID (2-digit), followed by a sequence number and a checksum digit.