OMS DOCUMENTATIONRESOURCE CENTER

These guides provide examples for many tasks that a developer will need to be familiar with during implementation.

KIBO OMS DEVELOPMENT

Documentation

Retrieve Order Status

The Retrieve Order Status API returns status information for OMS orders. This API can provide:

  • All information for orders created during a given date range
  • Status updates for orders created during a given date range
  • All information for specific orders, by order number
  • Status updates for specific orders, by order number

This API can also be used by fulfillment partners when they want to get status information for their orders (with permission).

Some limitations apply to this API:

  • A list of order numbers or a time range may be passed
  • A list can include 1000 order numbers or less
  • A time range can be five days or less
  • Information for order updates by time range is available for orders placed in the previous two weeks. To get updates for orders placed before that, use order numbers.
  • An order’s creation date determines if it falls in a specified time range.

Getting Started

System Requirements

To use the Retrieve Order Status API, there should be a server with Internet access that runs the client’s XML-RPC server to send data to the OMS server.

Writing the Application

The client needs to write the Immediate Retrieve Order Status application. This application lets the user create an XML package that sends data to the OMS server using a Remote Procedure Call (RPC).

The application can be written in any programming or scripting language that can handle a Remote Procedure Call (RPC), including PHP, ASP, Cold Fusion, JSP, JAVA, C, and so on.

Process Flow

The process for the Retrieve Order Status API is summarized here:

  1. Prepare the XML package to obtain order or update information.
  2. Call the immediate.retrieve_order_status method on OMS servers to transmit the XML package.
  3. This initiates the status inquiry. Send the single XML package to the OMS server.
  4. Receive a response with order data.
  5. Create an XML-RPC message that calls immediate.retrieve_order_status and passes an array of the parameters shown in the table for defining request elements, below.
  6. Create an XML-RPC client that connects to the following server:

Programming the Immediate Order Processing API

Server and RPC Information

  1. Create an XML-RPC message that calls immediate.retrieve_order_status and passes an array of the parameters shown in the table below for defining request elements.
  2. Create an XML-RPC client that connects to the following server:
    • Server file name: /xmlAdvServer.php
    • Server address: xml.shopatron.com
    • Server port: 443 (HTTPS)

Required and Optional Parameters

There are a number of possible parameters:

ElementRequiredParent ElementTypeOccursDescription
methodNameYesNone1immediate.retrieve_order_status
usernameYesNoneString1OMS username (must be a valid and active user account with System Admin or Order Admin permission). The maximum length is 50.
passwordYesNoneString1Password for OMS user account. The maximum length is 50.
manufacturer idYesNoneInt1The OMS-assigned Manufacturer ID that order data is being requested for; this can be found in the OMS account.
catalog idYesNoneInt1The OMS-assigned Catalog ID that order data is being requested for; this can be found in the OMS account.
DataTypeYesNoneString1The type of request being made, either OrderStatus or Updates.
OrderIDOptional. Include either OrderID and ExOrderID or DateTimeStart and DateTimeEnd.NoneStruct0 or 1A struct that contains the Order Numbers assigned by OMS when the order(s) were created. Each order number is in a substruct under OrderID.
ExOrderIDOptionalNoneStruct0 or 1A struct for the External Order ID(s) assigned by the client’s system. Each External Order ID is in a substruct under ExOrderID.
DateTimeStartOptional. Include either OrderID and ExOrderID or DateTimeStart and DateTimeEnd.NoneInt0 or 1The beginning of the date range for the inquiry. This must be a properly formatted UNIX timestamp. The maximum time range for when orders can be requested is five days.
DateTimeEndOptional. Include either OrderID and ExOrderID or DateTimeStart and DateTimeEnd.NoneInt0 or 1The end of the date range for the inquiry. This must be a properly formatted UNIX timestamp.

Example Requests and Responses

This first example obtains the order status for a list of order numbers.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
   <methodName>immediate.retrieve_order_status</methodName>
   <param>
      <value>
         <string>xml_user</string>
      </value>
   </param>
   <param>
      <value>
         <string>password</string>
      </value>
   </param>
   <param>
      <value>
         <int>mfg_id</int>
      </value>
   </param>
   <param>
      <value>
         <int>catalog_id</int>
      </value>
   </param>
   <param>
      <value>
         <struct>
            <member>
               <name>DataType</name>
               <value>
                  <string>OrderStatus</string>
               </value>
            </member>
            <member>
               <name>OrderID</name>
               <value>
                  <struct>
                     <member>
                        <name>0</name>
                        <value>
                           <string>4793437</string>
                        </value>
                     </member>
                     <member>
                        <name>1</name>
                        <value>
                           <string>4743943</string>
                        </value>
                     </member>
                  </struct>
               </value>
            </member>
            <member>
               <name>ExOrderID</name>
               <value>
                  <struct>
                     <member>
                        <name>0</name>
                        <value>
                           <string>331318440213534</string>
                        </value>
                     </member>
                     <member>
                        <name>1</name>
                        <value>
                           <string>1504404</string>
                        </value>
                     </member>
                  </struct>
               </value>
            </member>
         </struct>
      </value>
   </param>
</methodCall>

This is a possible response to the above request.

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
   <params>
      <param>
         <value>
            <struct>
               <member>
                  <name>Orders</name>
                  <value>
                     <struct>
                        <member>
                           <name>0</name>
                           <value>
                              <struct>
                                 <member>
                                    <name>OrderID</name>
                                    <value>
                                       <string>4791606</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ExOrderID</name>
                                    <value>
                                       <string>1532005</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>Parts</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>0</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>PartNumber</name>
                                                      <value>
                                                         <string>3064063000</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemId</name>
                                                      <value>
                                                         <string>6767162</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemState</name>
                                                      <value>
                                                         <string>Normal</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                          <member>
                                             <name>1</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>PartNumber</name>
                                                      <value>
                                                         <string>3028821000</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemId</name>
                                                      <value>
                                                         <string>6767160</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemState</name>
                                                      <value>
                                                         <string>Normal</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                          <member>
                                             <name>2</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>PartNumber</name>
                                                      <value>
                                                         <string>3071657000</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemId</name>
                                                      <value>
                                                         <string>6767161</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemState</name>
                                                      <value>
                                                         <string>Normal</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                                 <member>
                                    <name>Status</name>
                                    <value>
                                       <string>ready</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ShipmentID</name>
                                    <value>
                                       <int>3504831</int>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ShipperName</name>
                                    <value>
                                       <string>Sport Store</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ShipmentStatus</name>
                                    <value>
                                       <string>ready</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>RMAStatus</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>104501</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>Items</name>
                                                      <value>
                                                         <struct>
                                                            <member>
                                                               <name>0</name>
                                                               <value>
                                                                  <struct>
                                                                     <member>
                                                                        <name>ItemId</name>
                                                                        <value>
                                                                           <int>6489508</int>
                                                                        </value>
                                                                     </member>
                                                                     <member>
                                                                        <name>Quantity</name>
                                                                        <value>
                                                                           <int>1</int>
                                                                        </value>
                                                                     </member>
                                                                     <member>
                                                                        <name>Status</name>
                                                                        <value>
                                                                           <string>pending</string>
                                                                        </value>
                                                                     </member>
                                                                  </struct>
                                                               </value>
                                                            </member>
                                                         </struct>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>CurrentStatus</name>
                                                      <value>
                                                         <string>closed</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>Created</name>
                                                      <value>
                                                         <string>2011-11-01 20:49:41</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>Closed</name>
                                                      <value>
                                                         <string>2011-11-01 14:50:04</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>Cust_total</name>
                                                      <value>
                                                         <string>19.56</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>Fulfiller_total</name>
                                                      <value>
                                                         <string>18.48</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                              </struct>
                           </value>
                        </member>
                        <member>
                           <name>1</name>
                           <value>
                              <struct>
                                 <member>
                                    <name>OrderID</name>
                                    <value>
                                       <string>4793437</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ExOrderID</name>
                                    <value>
                                       <string>331318440213534</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>Parts</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>0</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>PartNumber</name>
                                                      <value>
                                                         <string>7772608803</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemId</name>
                                                      <value>
                                                         <string>6769764</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemState</name>
                                                      <value>
                                                         <string>Normal</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                          <member>
                                             <name>1</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>PartNumber</name>
                                                      <value>
                                                         <string>77726088032</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemId</name>
                                                      <value>
                                                         <string>6769763</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemState</name>
                                                      <value>
                                                         <string>Normal</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                                 <member>
                                    <name>Status</name>
                                    <value>
                                       <string>CheckShipmentStatus</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>RMAStatus</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>104500</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>Items</name>
                                                      <value>
                                                         <struct>
                                                            <member>
                                                               <name>0</name>
                                                               <value>
                                                                  <struct>
                                                                     <member>
                                                                        <name>ItemId</name>
                                                                        <value>
                                                                           <int>6769763</int>
                                                                        </value>
                                                                     </member>
                                                                     <member>
                                                                        <name>Quantity</name>
                                                                        <value>
                                                                           <int>1</int>
                                                                        </value>
                                                                     </member>
                                                                     <member>
                                                                        <name>Status</name>
                                                                        <value>
                                                                           <string>pending</string>
                                                                        </value>
                                                                     </member>
                                                                  </struct>
                                                               </value>
                                                            </member>
                                                         </struct>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>CurrentStatus</name>
                                                      <value>
                                                         <string>open</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>Created</name>
                                                      <value>
                                                         <string>2011-11-01 20:49:30</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>Cust_total</name>
                                                      <value>
                                                         <string>27.18</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>Fulfiller_total</name>
                                                      <value>
                                                         <string>25.68</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                                 <member>
                                    <name>CustomData</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>0</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>Name</name>
                                                      <value>
                                                         <string>Extradata</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>Value</name>
                                                      <value>
                                                         <string>struff</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                          <member>
                                             <name>1</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>Name</name>
                                                      <value>
                                                         <string>LoyaltyProgramID</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>Value</name>
                                                      <value>
                                                         <string>123456789</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                              </struct>
                           </value>
                        </member>
                     </struct>
                  </value>
               </member>
            </struct>
         </value>
      </param>
   </params>
</methodResponse>

This example obtains the order status for orders created within a time range.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
   <methodName>immediate.retrieve_order_status</methodName>
   <param>
      <value>
         <string>xml_user</string>
      </value>
   </param>
   <param>
      <value>
         <string>password</string>
      </value>
   </param>
   <param>
      <value>
         <int>mfg_id</int>
      </value>
   </param>
   <param>
      <value>
         <int>catalog_id</int>
      </value>
   </param>
   <param>
      <value>
         <struct>
            <member>
               <name>DataType</name>
               <value>
                  <string>OrderStatus</string>
               </value>
            </member>
            <member>
               <name>DateTimeStart</name>
               <value>
                  <int>1308591043</int>
               </value>
            </member>
            <member>
               <name>DateTimeEnd</name>
               <value>
                  <int>1308591643</int>
               </value>
            </member>
         </struct>
      </value>
   </param>
</methodCall>

This is a possible response to the above request.

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
   <params>
      <param>
         <value>
            <struct>
               <member>
                  <name>Orders</name>
                  <value>
                     <struct>
                        <member>
                           <name>0</name>
                           <value>
                              <struct>
                                 <member>
                                    <name>OrderID</name>
                                    <value>
                                       <string>4783219</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ExOrderID</name>
                                    <value>
                                       <string>1526907</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>Parts</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>0</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>PartNumber</name>
                                                      <value>
                                                         <string>3046183000</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemId</name>
                                                      <value>
                                                         <string>6752006</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemState</name>
                                                      <value>
                                                         <string>Normal</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                                 <member>
                                    <name>Status</name>
                                    <value>
                                       <string>payment error</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ShipmentID</name>
                                    <value>
                                       <int>3497205</int>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ShipperName</name>
                                    <value>
                                       <string>Sport Store</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ShipmentStatus</name>
                                    <value>
                                       <string>assigned</string>
                                    </value>
                                 </member>
                              </struct>
                           </value>
                        </member>
                     </struct>
                  </value>
               </member>
            </struct>
         </value>
      </param>
   </params>
</methodResponse>

This example obtains updates for a list of order numbers.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
   <methodName>immediate.retrieve_order_status</methodName>
   <param>
      <value>
         <string>xml_user</string>
      </value>
   </param>
   <param>
      <value>
         <string>password</string>
      </value>
   </param>
   <param>
      <value>
         <int>mfg_id</int>
      </value>
   </param>
   <param>
      <value>
         <int>catalog_id</int>
      </value>
   </param>
   <param>
      <value>
         <struct>
            <member>
               <name>DataType</name>
               <value>
                  <string>Updates</string>
               </value>
            </member>
            <member>
               <name>OrderID</name>
               <value>
                  <struct>
                     <member>
                        <name>0</name>
                        <value>
                           <string>4619361</string>
                        </value>
                     </member>
                     <member>
                        <name>1</name>
                        <value>
                           <string>4783196</string>
                        </value>
                     </member>
                  </struct>
               </value>
            </member>
            <member>
               <name>ExOrderID</name>
               <value>
                  <struct>
                     <member>
                        <name>0</name>
                        <value>
                           <string>1443113</string>
                        </value>
                     </member>
                     <member>
                        <name>1</name>
                        <value>
                           <string>1526805</string>
                        </value>
                     </member>
                  </struct>
               </value>
            </member>
         </struct>
      </value>
   </param>
</methodCall>

This is a possible response to the above request.

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
   <params>
      <param>
         <value>
            <struct>
               <member>
                  <name>Updates</name>
                  <value>
                     <struct>
                        <member>
                           <name>0</name>
                           <value>
                              <struct>
                                 <member>
                                    <name>OrderID</name>
                                    <value>
                                       <string>4619361</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ExOrderID</name>
                                    <value>
                                       <string>1443113</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>EventType</name>
                                    <value>
                                       <string>Ready</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>EventTime</name>
                                    <value>
                                       <int>1303510629</int>
                                    </value>
                                 </member>
                                 <member>
                                    <name>PartNumber</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>0</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>PartNumber</name>
                                                      <value>
                                                         <string>SPO3011537000</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemId</name>
                                                      <value>
                                                         <string>6449960</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                              </struct>
                           </value>
                        </member>
                        <member>
                           <name>1</name>
                           <value>
                              <struct>
                                 <member>
                                    <name>OrderID</name>
                                    <value>
                                       <string>1443113</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ExOrderID</name>
                                    <value>
                                       <string>1455706</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>EventType</name>
                                    <value>
                                       <string>RMACreated</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>EventTime</name>
                                    <value>
                                       <int>1320180570</int>
                                    </value>
                                 </member>
                                 <member>
                                    <name>PartNumber</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>0</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>PartNumber</name>
                                                      <value>
                                                         <string>SPO1501131013</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemId</name>
                                                      <value>
                                                         <string>6489511</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>Quantity</name>
                                                      <value>
                                                         <string>1.00</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                                 <member>
                                    <name>Customer</name>
                                    <value>
                                       <double>27.18</double>
                                    </value>
                                 </member>
                                 <member>
                                    <name>Retailer</name>
                                    <value>
                                       <double>-25.68</double>
                                    </value>
                                 </member>
                                 <member>
                                    <name>Mfg</name>
                                    <value>
                                       <double>0</double>
                                    </value>
                                 </member>
                                 <member>
                                    <name>Rma_id</name>
                                    <value>
                                       <int>104500</int>
                                    </value>
                                 </member>
                              </struct>
                           </value>
                        </member>
                        <member>
                           <name>2</name>
                           <value>
                              <struct>
                                 <member>
                                    <name>OrderID</name>
                                    <value>
                                       <string>4619361</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ExOrderID</name>
                                    <value>
                                       <string>1443113</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>EventType</name>
                                    <value>
                                       <string>Fulfilled</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>EventTime</name>
                                    <value>
                                       <int>1303765633</int>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ShipmentID</name>
                                    <value>
                                       <int>3344332</int>
                                    </value>
                                 </member>
                                 <member>
                                    <name>TrackingNr</name>
                                    <value>
                                       <string>1Z4AE1420349581104</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>Carrier</name>
                                    <value>
                                       <string>U.P.S./Common</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>PartNumber</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>0</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>PartNumber</name>
                                                      <value>
                                                         <string>SPO3011537000</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemId</name>
                                                      <value>
                                                         <string>6449960</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                              </struct>
                           </value>
                        </member>
                        <member>
                           <name>3</name>
                           <value>
                              <struct>
                                 <member>
                                    <name>OrderID</name>
                                    <value>
                                       <string>4783196</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ExOrderID</name>
                                    <value>
                                       <string>1526805</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>EventType</name>
                                    <value>
                                       <string>Ready</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>EventTime</name>
                                    <value>
                                       <int>1308592941</int>
                                    </value>
                                 </member>
                                 <member>
                                    <name>PartNumber</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>0</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>PartNumber</name>
                                                      <value>
                                                         <string>SPO1534590037</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemId</name>
                                                      <value>
                                                         <string>6751973</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                              </struct>
                           </value>
                        </member>
                        <member>
                           <name>4</name>
                           <value>
                              <struct>
                                 <member>
                                    <name>OrderID</name>
                                    <value>
                                       <string>4783196</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ExOrderID</name>
                                    <value>
                                       <string>1526805</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>EventType</name>
                                    <value>
                                       <string>Fulfilled</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>EventTime</name>
                                    <value>
                                       <int>1308781681</int>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ShipmentID</name>
                                    <value>
                                       <int>3497204</int>
                                    </value>
                                 </member>
                                 <member>
                                    <name>TrackingNr</name>
                                    <value>
                                       <string>1Z9X05860355119491</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>Carrier</name>
                                    <value>
                                       <string>U.P.S./Common</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>PartNumber</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>0</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>PartNumber</name>
                                                      <value>
                                                         <string>SPO1534590037</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemId</name>
                                                      <value>
                                                         <string>6751973</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                              </struct>
                           </value>
                        </member>
                     </struct>
                  </value>
               </member>
            </struct>
         </value>
      </param>
   </params>
</methodResponse>

This example obtains updates within a date range.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
   <methodName>immediate.retrieve_order_status</methodName>
   <param>
      <value>
         <string>xml_user</string>
      </value>
   </param>
   <param>
      <value>
         <string>password</string>
      </value>
   </param>
   <param>
      <value>
         <int>mfg_id</int>
      </value>
   </param>
   <param>
      <value>
         <int>catalog_id</int>
      </value>
   </param>
   <param>
      <value>
         <struct>
            <member>
               <name>DataType</name>
               <value>
                  <string>Updates</string>
               </value>
            </member>
            <member>
               <name>DateTimeStart</name>
               <value>
                  <int>1308591043</int>
               </value>
            </member>
            <member>
               <name>DateTimeEnd</name>
               <value>
                  <int>1308591643</int>
               </value>
            </member>
         </struct>
      </value>
   </param>
</methodCall>

This is a possible response to the above request.

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
   <params>
      <param>
         <value>
            <struct>
               <member>
                  <name>Updates</name>
                  <value>
                     <struct>
                        <member>
                           <name>0</name>
                           <value>
                              <struct>
                                 <member>
                                    <name>OrderID</name>
                                    <value>
                                       <string>4762777</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ExOrderID</name>
                                    <value>
                                       <string>1514120</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>EventType</name>
                                    <value>
                                       <string>Fulfilled</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>EventTime</name>
                                    <value>
                                       <int>1308591238</int>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ShipmentID</name>
                                    <value>
                                       <int>3472184</int>
                                    </value>
                                 </member>
                                 <member>
                                    <name>TrackingNr</name>
                                    <value>
                                       <string>1z1r570w0345555022</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>Carrier</name>
                                    <value>
                                       <string>UPS</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>PartNumber</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>0</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>PartNumber</name>
                                                      <value>
                                                         <string>SPO3043988001</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemId</name>
                                                      <value>
                                                         <string>6713248</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                          <member>
                                             <name>1</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>PartNumber</name>
                                                      <value>
                                                         <string>SPO3071642002</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemId</name>
                                                      <value>
                                                         <string>6713251</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                          <member>
                                             <name>2</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>PartNumber</name>
                                                      <value>
                                                         <string>SPO3067177002</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemId</name>
                                                      <value>
                                                         <string>6713247</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                          <member>
                                             <name>3</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>PartNumber</name>
                                                      <value>
                                                         <string>SPO3067048002</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemId</name>
                                                      <value>
                                                         <string>6713250</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                          <member>
                                             <name>4</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>PartNumber</name>
                                                      <value>
                                                         <string>SPO3067177001</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemId</name>
                                                      <value>
                                                         <string>6713249</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                              </struct>
                           </value>
                        </member>
                        <member>
                           <name>1</name>
                           <value>
                              <struct>
                                 <member>
                                    <name>OrderID</name>
                                    <value>
                                       <string>4763810</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ExOrderID</name>
                                    <value>
                                       <string>1515208</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>EventType</name>
                                    <value>
                                       <string>Fulfilled</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>EventTime</name>
                                    <value>
                                       <int>1308591324</int>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ShipmentID</name>
                                    <value>
                                       <int>3473304</int>
                                    </value>
                                 </member>
                                 <member>
                                    <name>TrackingNr</name>
                                    <value>
                                       <string>1ZE53A720344125606</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>Carrier</name>
                                    <value>
                                       <string>UPS</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>PartNumber</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>0</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>PartNumber</name>
                                                      <value>
                                                         <string>SPO0663950012</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemId</name>
                                                      <value>
                                                         <string>6714933</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                          <member>
                                             <name>1</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>PartNumber</name>
                                                      <value>
                                                         <string>SPO2092910013</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemId</name>
                                                      <value>
                                                         <string>6714934</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                          <member>
                                             <name>2</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>PartNumber</name>
                                                      <value>
                                                         <string>SPO3005094000</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemId</name>
                                                      <value>
                                                         <string>6714932</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                              </struct>
                           </value>
                        </member>
                     </struct>
                  </value>
               </member>
            </struct>
         </value>
      </param>
   </params>
</methodResponse>

This example obtains updates within both a time range and list of order numbers.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
   <methodName>immediate.retrieve_order_status</methodName>
   <params>
      <param>
         <value>
            <string>xml_user</string>
         </value>
      </param>
      <param>
         <value>
            <string>password</string>
         </value>
      </param>
      <param>
         <value>
            <int>mfg_id</int>
         </value>
      </param>
      <param>
         <value>
            <int>catalog_id</int>
         </value>
      </param>
      <param>
         <value>
            <struct>
               <member>
                  <name>DataType</name>
                  <value>
                     <string>Updates</string>
                  </value>
               </member>
               <member>
                  <name>OrderID</name>
                  <value>
                     <struct>
                        <member>
                           <name>0</name>
                           <value>
                              <string>5090493</string>
                           </value>
                        </member>
                     </struct>
                  </value>
               </member>
               <member>
                  <name>ExOrderID</name>
                  <value>
                     <struct>
                        <member>
                           <name>0</name>
                           <value>
                              <string>1135302</string>
                           </value>
                        </member>
                     </struct>
                  </value>
               </member>
               <member>
                  <name>DateTimeStart</name>
                  <value>
                     <int>1318607009</int>
                  </value>
               </member>
               <member>
                  <name>DateTimeEnd</name>
                  <value>
                     <int>1318952609</int>
                  </value>
               </member>
            </struct>
         </value>
      </param>
   </params>
</methodCall>

This is a possible response to the above request.

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
   <params>
      <param>
         <value>
            <struct>
               <member>
                  <name>Updates</name>
                  <value>
                     <struct>
                        <member>
                           <name>0</name>
                           <value>
                              <struct>
                                 <member>
                                    <name>OrderID</name>
                                    <value>
                                       <string>5090493</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ExOrderID</name>
                                    <value>
                                       <string>1135302</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>EventType</name>
                                    <value>
                                       <string>Fulfilled</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>EventTime</name>
                                    <value>
                                       <int>1318628862</int>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ShipmentID</name>
                                    <value>
                                       <int>3798928</int>
                                    </value>
                                 </member>
                                 <member>
                                    <name>TrackingNr</name>
                                    <value>
                                       <string>1z9999999999</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>Carrier</name>
                                    <value>
                                       <string>UPS</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>PartNumber</name>
                                    <value>
                                       <struct>
                                          <member>
                                             <name>0</name>
                                             <value>
                                                <struct>
                                                   <member>
                                                      <name>PartNumber</name>
                                                      <value>
                                                         <string>ZZLTest1234</string>
                                                      </value>
                                                   </member>
                                                   <member>
                                                      <name>ItemId</name>
                                                      <value>
                                                         <string>7306595</string>
                                                      </value>
                                                   </member>
                                                </struct>
                                             </value>
                                          </member>
                                       </struct>
                                    </value>
                                 </member>
                              </struct>
                           </value>
                        </member>
                     </struct>
                  </value>
               </member>
            </struct>
         </value>
      </param>
   </params>
</methodResponse>

Response Codes

Unlike REST APIs, the XML-RPC APIs do not return HTTP status codes to indicate success or failure. For success, the RPC returns the information requested. On an error, the RPC returns a response message with the faultCode and faultString.

A full list of faultCode and faultString options can be found below:

CodeDescription
readyOrder is ready for shipment.
biddingOrder is still being bid on, and is not assigned yet.
waiting for manufacturerOrder is waiting for manufacturer to accept or assign.
payment errorOrder is in payment error.
payment holdOrder is in payment hold.
canceledOrder has been canceled.
fulfilled.Order has been fulfilled.
CheckShipmentStatusThe order is complicated; check if the shipment status is available.
If empty or no shipment statusesThe order is in a state which cannot yet be determined (possibly in resolve.

ItemState can also return unique response codes:

CodeDescription
NormalItem is in a normal state.
CanceledItem is canceled.

RMA CurrentState can also return unique response codes:

CodeDescription
openReturn has been opened.
closedReturn is closed.

RMA Item Status can also return unique response codes:

CodeDescription
pendingReturn has been opened and is pending.
rejectedReturn is rejected.
acceptedReturn has been accepted.

The EventType can also return unique response codes:

CodeDescription
ReadyOrder moved to ready.
BiddingOrder placed in request.
CanceledOrder canceled.
FulfilledOrder fulfilled.
LineItemChangedOrder item changed.
RMAAcceptedReturn was accepted.
CustSatisfactionFeeCustomer satisfaction fee occurred.
RMACreatedReturn was created.
RMAClearedReturn was cleared.

The main error response codes that may be encountered are:

CodeDescription
2Invalid data of some Type.
99Invalid Authorization.

An example error response follows below.

<?xml version="1.0" encoding="UTF-8"?>
<methodResponse>
   <fault>
      <value>
         <struct>
            <member>
               <name>faultCode</name>
               <value>
                  <int>2</int>
               </value>
            </member>
            <member>
               <name>faultString</name>
               <value>
                  <string>Invalid Time Range, Must Be Under 5 Days</string>
               </value>
            </member>
         </struct>
      </value>
   </fault>
</methodResponse>

Handling Errors

If an error response fault code is recieved after sending the order information to OMS, follow these steps:

  1. Record the outgoing package and the associated fault code response from OMS.
  2. Test for connectivity to the server.
  3. Hold the XML package for future transmission to OMS servers.
  4. Send an email to OMS Merchant Support; include the time and date of the failed transmission.
  5. When OMS support staff responds, resend the failed attempts.