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

Request Orders

Orders can be requested using an XML-RPC process with the Request Orders API. This API lets the user place, modify, and delete order requests and integrate the request process with inventory matching processes. It also facilitates the management of backorders and backorder durations.

  • Backup fulfillers can use the Request Orders API to accept certain orders and enter backorder durations for them.
  • Fulfillment partners can also use this API to request available orders (with permission).

Most clients use the Request Order API with the Available Order Download API, which automates the process for viewing available orders. To fully automate the order request process, use the Available Order Download API, an inventory-matching process, and the Request Orders API together.

Getting Started

System Requirements

To use the Request Orders API, there must be a server with Internet access to run the client’s own XML-RPC server that sends data to the OMS server.

Writing the Application

The client needs to write the Send Request Data application. This application allows the user to create an XML package that sends the request data. The Send Request Data application uses a Remote Procedure Call (RPC) to pass the package to the OMS server. This application can also delete or update requests that have already been placed.

The application can be written in any programming or scripting language that can handle an RPC, including PHP, ASP, Cold Fusion, JSP, JAVA, C, and so on.

Process Flow

The process for the OMS Request Order API is summarized here:

  1. Prepare the XML package to request multiple orders and items, one catalog at a time.
  2. Call the immediate.create_order_bids method on OMS servers to transmit the XML package.
  3. This initiates the order request upload.
  4. A response code indicates whether or not the request was successful.

If inventory is no longer available, a similar request can delete or modify an existing request. Requests can only be deleted or modified for orders that have an Available Order status.

Programming the Request Orders API

Use the Send Request Data application to place a request, to delete a request, to modify a request, and to manage backorders and durations.

Server and RPC Information

  1. Create an XML-RPC message that calls immediate.create_order_bids and passes an array of the parameters shown in the table for defining request elements, below.
  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 XML package elements:

ElementRequiredParent ElementTypeOccursDescription
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.
mfg_idYesNoneint1The OMS-assigned Manufacturer ID for the order.
catalog_idYesNoneint1The OMS-assigned Catalog ID for the order.
order_xYesNonestructnum_ ordersAn unnamed container for data for a single order. Include one order_x container for each order in the package. Replace x with a number: 0, 1, 2, etc. This container includes the Order Number, the store’s Location ID in OMS, the tax that is applied to the shipping and handling fee, and, unless deleting a request, information about all items in the order.
OrderIDYesorder_xint1OMS-assigned Order Number.
LocationIDOptionalorder_xint1The OMS-assigned location ID where the order would be fulfilled. If LocationID is not specified, the default LocationID is used.
ShipmentTaxOptionalorder_xdouble1/orderThe tax that will be applied to shipping and handling if the order is fulfilled.
OrderItemsOptionalorder_xstructnum_ items/ orderA sequentially numbered array (beginning with 0) that provides the Item Number, Part Number, and tax for each item in the order. If a request is being deleted, omit OrderItems. Otherwise, this struct and all its parameters are required.
ItemIDYesitem_xint1/line itemThe OMS-assigned ID for Item ID for this item.
PartNumberYesitem_xstring1/line itemThe merchant-assigned part number for the item.
ItemTaxOptionalitem_xdouble1/line itemThe amount of tax that will be applied to the item if the order is fulfilled.
BOdurationYesitem_xint1/line itemThe backorder duration (or possible cancellation) for this item. Only include BOduration if Request Orders is being used to manage backorders. Use these values to indicate the duration of the backorder: 7 (0- 2 weeks), 21 (2-4 weeks), 49 (5-8 weeks), 50 (over 8 weeks), 998 (out of stock), and 999 (discontinued). Note: If an item is canceled by specifying 998 or 999, the customer is not notified as they would be if those options had been selected with the user interface.

Example Requests

In this example, two orders are requested. The first order has two items in it; the second order has one item, and specifies a backorder duration of 0 to 2 weeks.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
  <methodName>immediate.create_order_bids</methodName>
  <params>
    <param>
      <value>
        <string>xml_user</string>
      </value>
    </param>
    <param>
      <value>
        <string>2c93f30faf08977aa268e26aeebe1f54</string>
      </value>
    </param>
    <param>
      <value>
        <string>138</string>
      </value>
    </param>
    <param>
      <value>
        <string>0</string>
      </value>
    </param>
    <param>
      <value>
        <struct>
          <member>
            <name>0</name>
            <value>
              <struct>
                <member>
                  <name>OrderID</name>
                  <value>
                    <string>4103100</string>
                  </value>
                </member>
                <member>
                  <name>ShipmentTax</name>
                  <value>
                    <double>1.29</double>
                  </value>
                </member>
                <member>
                  <name>OrderItems</name>
                  <value>
                    <struct>
                      <member>
                        <name>0</name>
                        <value>
                          <struct>
                            <member>
                              <name>ItemID</name>
                              <value>
                                <string>809479</string>
                              </value>
                            </member>
                            <member>
                              <name>PartNumber</name>
                              <value>
                                <string>1002</string>
                              </value>
                            </member>
                            <member>
                              <name>ItemTax</name>
                              <value>
                                <double>0.11</double>
                              </value>
                            </member>
                          </struct>
                        </value>
                      </member>
                      <member>
                        <name>1</name>
                        <value>
                          <struct>
                            <member>
                              <name>ItemID</name>
                              <value>
                                <string>805815</string>
                              </value>
                            </member>
                            <member>
                              <name>PartNumber</name>
                              <value>
                                <string>1010</string>
                              </value>
                            </member>
                            <member>
                              <name>ItemTax</name>
                              <value>
                                <double>0.11</double>
                              </value>
                            </member>
                          </struct>
                        </value>
                      </member>
                    </struct>
                  </value>
                </member>
              </struct>
            </value>
          </member>
        </struct>
      </value>
    </param>
    <param>
      <value>
        <struct>
          <member>
            <name>1</name>
            <value>
              <struct>
                <member>
                  <name>OrderID</name>
                  <value>
                    <string>4103100</string>
                  </value>
                </member>
                <member>
                  <name>ShipmentTax</name>
                  <value>
                    <double>1.29</double>
                  </value>
                </member>
                <member>
                  <name>OrderItems</name>
                  <value>
                    <struct>
                      <member>
                        <name>0</name>
                        <value>
                          <struct>
                            <member>
                              <name>ItemID</name>
                              <value>
                                <string>810347</string>
                              </value>
                            </member>
                            <member>
                              <name>PartNumber</name>
                              <value>
                                <string>2202</string>
                              </value>
                            </member>
                            <member>
                              <name>ItemTax</name>
                              <value>
                                <double>0.11</double>
                              </value>
                              <member>
                                <name>BOduration</name>
                                <value>
                                  <int>7</int>
                                </value>
                              </member></member>
                            </struct>
                          </value>
                        </member>
                      </struct>
                    </value>
                  </member>
                </struct>
              </value>
            </member>
          </struct>
        </value>
      </param>
    </params>
  </methodCall>

In this example, a request is deleted. Note that the OrderItems struct is not included.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
  <methodName>immediate.create_order_bids</methodName>
  <params>
    <param>
      <value>
        <string>xml_user</string>
      </value>
    </param>
    <param>
      <value>
        <string>2c93f30faf08977aa268e26aeebe1f54</string>
      </value>
    </param>
    <param>
      <value>
        <string>138</string>
      </value>
    </param>
    <param>
      <value>
        <string>0</string>
      </value>
    </param>
    <param>
      <value>
        <struct>
          <member>
            <name>0</name>
            <value>
              <struct>
                <member>
                  <name>OrderID</name>
                  <value>
                    <string>1526761</string>
                  </value>
                </member>
                <member>
                  <name>LocationID</name>
                  <value>
                    <int>1</int>
                  </value>
                </member>
                <member>
                  <name>ShipmentTax</name>
                  <value>
                    <double>0</double>
                  </value>
                </member>
              </struct>
            </value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>

Example Responses

Unlike REST APIs, the XML-RPC APIs do not return HTTP status codes to indicate success or failure. For success, the RPC returns an OMS Order ID. 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
0Success. The request has been created/deleted.
2Invalid data.
99Invalid Authorization.

Successful responses may look like the below sample:

<?xml version="1.0" encoding="UTF-8"?>
 <methodResponse>
    <params>
       <param>
          <value>
             <int>0 </int>
          </value>>
       </param>
    </params>
 </methodResponse>

An error response includes an error code and reason.

<?xml version="1.0" encoding="UTF-8"?>
 <methodResponse>
    <fault>
       <value>
          <struct>
             <member>
                <name>faultCode </name>
                <value>
                   <int>99 </int>
                </value>
             </member>
             <member>
                <name>faultString </name>
                <value>
                   <string>Invalid authorization </string>
                </value>
             </member>
          </structv
       </valuev
    </fault>
 </methodResponse>

Handling Errors

If an error response fault code is received 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. Present an error screen to the consumer that states that the order is unable to be completed
    • Ask the consumer for the following information: First Name, Last Name, Phone Number, and Email Address.
  4. Bundle the consumer contact information and all order information, including order items quantity, and any promotions, and email the package to OMS Merchant Support