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

Available Order Download

Use the Available Order Download API to download the Standard, Express, and Certified Partner orders that are currently in the OMS system and available (unassigned). Additionally, this API can display orders that have a Waiting for Manufacturer Acceptance status.

  • The backup fulfiller (if one exists) can view the assigned order, backorder, and direct shipment information with this API.
  • The fulfillment partners can download available orders (with permission) and incorporate this API into their inventory-matching processes.

Most clients use the Available Order Download API with the Request Order API, which automates the order request process. 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 Available Order Download API, there needs to 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 two applications:

  • Request Order Data Application – This application assembles an XML package to request the available orders for a specific manufacturer. It then uses a Remote Procedure Call (RPC) to pass the package to the OMS server. This creates a queued event for OMS to respond to.
  • Receive Order Data Application – This application receives an XML package that contains the specified manufacturer’s available order data from OMS servers. The client system accepts this package and incorporates it into the stock-matching process to place order requests via the Request Order Tool.

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 Available Order Download API occurs as summarized here:

  1. To initiate the download, make a request to the OMS XML-RPC server.The RPC authenticates the user name and password, verifies the server and RPC name information, and verifies that the account is authorized to receive orders for the specific manufacturer for which order data is being requested.
  2. If all of these conditions are met, the request is placed in a send queue.This send queue runs four times per hour. The API returns a response code that indicates whether the request was successful.
  3. An application on our server checks the send queue at periodic intervals.This application assembles order data for the manufacturer that has been requested and sends the data in an XML-RPC package to the client server. It logs the data sent, the time sent, the client response, and any error messages.
  4. If OMS receives a success response from the client server, the OMS server deletes the request from the queue. If OMS receives an error code response from the client server, an email is sent to Kibo administrators who will follow up and attempt to resolve the issue before another data send is attempted.

Programming the Request Order Information Application

Server and RPC Information

  1. Create an XML-RPC message that calls queue.get_available_orders and passes an array of the parameters listed in the table below that defines the 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

Required and Optional Parameters

There are a number of possible parameters:

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 which order data is being requested; the client can find this in their OMS account.
catalog_idYesNoneInt1The OMS-assigned Catalog ID for which order data is being requested; the client can find this in their OMS account.
filtersNoNonestruct0/1Filters for orders being received. ShipType is the only supported filter.
ShipTypeNofiltersstring1/filtersThe type of shipping for orders being received. Supported values are: ispu (in-store pick up), 1day (1-day express shipping), 2day (2-day express shipping), 3d (express shipping), and standard (standard shipping).

Example Request

This example is a minimal XML-RPC message that features a single order with one item.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
   <methodName>queue.get_available_orders</methodName>
   <params>
      <param>
         <value>
            <string>xml_user_name</string>
         </value>
      </param>
      <param>
         <value>
            <string>xml_user_password</string>
         </value>
      </param>
      <param>
         <value>
            <int>138</int>
         </value>
      </param>
      <param>
         <value>
            <int>0</int>
         </value>
      </param>
      <param>
         <value>
            <struct>
               <member>
                  <name>ShipType</name>
                  <value>
                     <string>ispu</string>
                  </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.

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

CodeDescription
0Success
99Invalid Authorization
2Invalid Data.
5No server or RPC name on file for this data_type.
7Error adding request to queue.

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>2</int>
               </value>
            </member>
            <member>
               <name>faultString</name>
               <value>
                  <string>Invalid return payload: enabling debugging to examine incoming payload</string>
               </value>
            </member>
         </struct>
      </value>
   </fault>
</methodResponse>

Handling Errors

If an error response is received, 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 Kibo support staff responds, resend the failed attempts.

Programming the Receive Order Information Application

The Receive Order Data application receives a call from the OMS server with the parameters listed in the table below that defines the receive elements.

Server and RPC Information

  1. Create an XML-RPC server with an RPC method that accepts a single XML package as a parameter. The parameters listed previously are extracted from this function parameter.
  2. Email OMS Merchant Support and provide the following information:
    • Server file name – the path and name of the file (for example, /myXMLServer.php)
    • Server address – the URL of the server (for example, xml.shopatron.com)
    • Server port – the port number to which the server is connected (for example, 80 or 443)
    • RPC name – the name of the remote procedure (for example, get_my_orders)

Required and Optional Parameters

There are a number of possible parameters:

ElementRequiredParent ElementTypeOccursDescription
method nameYesNone1The specific RPC that the OMS server is to call.
ManufacturerIDYesNoneint1The OMS-assigned Manufacturer ID. May be identified as a string.
CatalogIDYesNoneint1The OMS-assigned Catalog ID. May be identified as a string.
order_xYesNonestructnum_ordersAn unnamed container for data about a single order.
OrderIDYesorder_xint1/orderOMS Order ID (also called the “Order Number”).
Address1Yesorder_xstring1/orderLine 1 of the ship-to Street Address for the order. The maximum length is 50.
Address2Optionalorder_xstring1/orderLine 2 of the ship-to Street Address. The maximum length is 50.
Address3Optionalorder_xstring1/orderLine 3 of the ship-to Street Address. The maximum length is 50.
CityYesorder_xstring1/orderCity of the ship-to address for the order. The maximum length is 50.
StateYesorder_xstring1/orderState or province of the ship-to address for the order (US and Canada only).
ZipYesorder_xstring1/orderZip or postal code of the ship-to address for the order. The maximum length is 50.
CountryYesorder_xstring1/orderCountry of the ship-to address for the order. The maximum length is 50.
CountryCodeYesorder_xstring1/order2-character Country Code of the ship-to address for the order. Country Codes are listed at the end of this document.
currency_idYesorder_xint1/orderThe Currency Type for the order. These Currency Types are supported: 1 (US Dollar), 2 (Canadian Dollar), 3 (British Pound), 5 (German Euro), 6 (French Euro), 7 (Italian Euro), 8 (Spanish Euro), 9 (British Euro), and 10 (Dutch Euro).
language_idYesorder_xint1/orderThe Language ID for the order. These Language IDs are supported: 1 (US English), 3 (Canadian French), 4 (UK English), 5 (DE German), and 7 (IT Italian).
ShipTypeYesorder_xstring1/orderThe requested shipping method for the order. These shipping methods are supported: sts (ship to store), sts+ (shopper’s choice), ispu (in-store pick up), 2day (2-day express shipping), 3day (3-day express shipping), and standard (standard shipping).
EstimatedShippingYesorder_xdouble1/orderThe amount of money that the fulfiller will be paid for filling the complete order.
EstimatedDistanceYesorder_xdouble1/orderApproximate distance from the fulfiller’s primary location to the ship-to address.
MfgIDYesorder_xint1/orderOMS-assigned Manufacturer ID.
CatalogIDYesorder_xint1/orderOMS-assigned Catalog ID.
DiscountOptionalorder_xStruct1/orderContainer for order discount information.
DiscountDescriptionYesDiscountString1/discountDescription of the order discount.
DiscountPercentageYesDiscountDouble1/discountThe percentage discount off the order total in decimal form. For example, 50% will be shown as 0.5.
DiscountTotalYesDiscountDouble1/discountThe amount of discount from the order total.
CheckDateYesorder_xInt1/orderThe date (in microtime) the order was last updated.
OrderDateYesorder_xInt1/orderThe date (in microtime) the order was created.
OrderItemsYesorder_xStruct1/orderContainer for all items in the order.
item_numYesOrderItems_xStruct1/line itemSubstructure with information about one item in the order. Item_num is replaced by a sequential number; where the first substructure is 0, the second is 1, and so on.
ItemIDYesitem_num_xInt1/ line itemThe internal OMS-assigned ID for the item.
ProdNameYesitem_num_xString1/line itemThe product name for the item, as assigned by the manufacturer.
PartNumberYesitem_num_xString1/line itemThe part number for the item, as assigned by the manufacturer.
UPCYesitem_num_xString1/line itemThe UPC for the item, as assigned by the manufacturer.
OptionsOptional – Required if options are specifieditem_num_xStruct1/line itemA container for all product options for the item.
Options_xOptional – Required if options are specifiedOptionsnum_options/itemOptions_x is replaced by a sequential number, where the first option is 0, the second is 1, and so on.
option_textOptional – Required if options are specifiedOptionsStringnum_options/itemText description of a product option, as specified by the manufacturer.
QuantityYesitem_num_xInt1/line itemThe quantity for this item.
CustPriceYesitem_num_xDouble1/line itemThe price the consumer paid for this item.
PaymentDiscYesitem_num_xDouble1/line itemThe amount of money retained by Kibo for payment of processing fees for this item.
ShopatronDiscYesitem_num_xDouble1/line itemThe amount of money retained for the OMS Discount for this item.
ManufacturerDiscOptionalitem_num_xDouble1/line itemThe amount of money held as the Manufacturer’s fee for this item.

Example Response

In the following sample message, two orders are returned. The first order includes one item with options and discounts. The second order includes two items; neither have options or discounts.

Note that ManufacturerID and CatalogID may be identified as integers or as strings in the download.

<?xml version="1.0" encoding="ISO-8859-1" ?>
<methodCall>
  <methodName>method_name_of_client_server</methodName>
  <params>
    <param>
      <value>
        <struct>
          <member>
            <name>ManufacturerID</name>
            <value>
              <int>138</int>
            </value>
          </member>
          <member>
            <name>CatalogID</name>
            <value>
              <int>0</int>
            </value>
          </member>
        </struct>
      </value>
    </param>
    <param>
      <value>
        <struct>
          <member>
            <name>OrderID</name>
            <value>
              <int>4103100</int>
            </value>
          </member>
          <member>
            <name>Address1</name>
            <value>
              <string>1026 Red Oak Drive</string>
            </value>
          </member>
          <member>
            <name>Address2</name>
            <value>
              <string>Apt. 256</string>
            </value>
          </member>
          <member>
            <name>City</name>
            <value>
              <string>Cherry Hill</string>
            </value>
          </member>
          <member>
            <name>State</name>
            <value>
              <string>NJ</string>
            </value>
          </member>
          <member>
            <name>Zip</name>
            <value>
              <string>08003</string>
            </value>
          </member>
          <member>
            <name>Country</name>
            <value>
              <string>United States of America</string>
            </value>
          </member>
          <member>
            <name>CountryCode</name>
            <value>
              <string>US</string>
            </value>
          </member>
          <member>
            <name>currency_id</name>
            <value>
              <int>1</int>
            </value>
          </member>
          <member>
            <name>language_id</name>
            <value>
              <int>1</int>
            </value>
          </member>
          <member>
            <name>ShipType</name>
            <value>
              <string>sts</string>
            </value>
          </member>
          <member>
            <name>EstimatedShipping</name>
            <value>
              <double>8.9</double>
            </value>
          </member>
          <member>
            <name>EstimatedDistance</name>
            <value>
              <double>2491.38288904</double>
            </value>
          </member>
          <member>
            <name>MfgID</name>
            <value>
              <int>138</int>
            </value>
          </member>
          <member>
            <name>CatalogID</name>
            <value>
              <int>0</int>
            </value>
          </member>
          <member>
            <name>Discount</name>
            <value>
              <struct>
                <member>
                  <name>DiscountDescription</name>
                  <value>
                    <string>Charity Giveback</string>
                  </value>
                </member>
                <member>
                  <name>DiscountPercentage</name>
                  <value>
                    <double>0.1</double>
                  </value>
                </member>
                <member>
                  <name>DiscountTotal</name>
                  <value>
                    <double>10.51</double>
                  </value>
                </member>
              </struct>
            </value>
          </member>
          <member>
            <name>CheckDate</name>
            <value>
              <int>156478887</int>
            </value>
          </member>
          <member>
            <name>OrderDate</name>
            <value>
              <int>156478887</int>
            </value>
            <member>
              <name>OrderItems</name>
              <value>
                <struct>
                  <member>
                    <name>0</name>
                    <value>
                      <struct>
                        <member>
                          <name>ItemID</name>
                          <value>
                            <string>809479</string>
                          </value>
                        </member>
                        <member>
                          <name>ProdName</name>
                          <value>
                            <string>Great Product </string>
                          </value>
                        </member>
                        <member>
                          <name>PartNumber</name>
                          <value>
                            <string>1002</string>
                          </value>
                        </member>
                        <member>
                          <name>UPC</name>
                          <value>
                            <string>123456789991</string>
                          </value>
                        </member>
                        <member>
                          <name>Options</name>
                          <value>
                            <struct>
                              <member>
                                <name>0</name>
                                <value>
                                  <string>Texture: Rough </string>
                                </value>
                              </member>
                              <member>
                                <name>1</name>
                                <value>
                                  <string>Color: Orange </string>
                                </value>
                              </member>
                              <member>
                                <name>2</name>
                                <value>
                                  <string>Styles 2: Birds </string>
                                </value>
                              </member>
                            </struct>
                          </value>
                        </member>
                        <member>
                          <name>Quantity</name>
                          <value>
                            <int>1</int>
                          </value>
                        </member>
                        <member>
                          <name>CustPrice</name>
                          <value>
                            <double>5.65</double>
                          </value>
                        </member>
                        <member>
                          <name>PaymentDisc</name>
                          <value>
                            <double>0.1695</double>
                          </value>
                        </member>
                        <member>
                          <name>ShopatronDisc</name>
                          <value>
                            <double>0.26103</double>
                          </value>
                        </member>
                        <member>
                          <name>ManufacturerDisc</name>
                          <value>
                            <double>0.1695</double>
                          </value>
                        </member>
                      </struct>
                    </value>
                  </member>
                </struct>
              </value>
            </member>
          </struct>
        </value>
      </param>
      <param>
        <value>
          <struct>
            <member>
              <name>OrderID</name>
              <value>
                <int>4103279</int>
              </value>
            </member>
            <member>
              <name>Address1</name>
              <value>
                <string>123 Main Street</string>
              </value>
            </member>
            <member>
              <name>City</name>
              <value>
                <string>Cambria</string>
              </value>
            </member>
            <member>
              <name>State</name>
              <value>
                <string>CA</string>
              </value>
            </member>
            <member>
              <name>Zip</name>
              <value>
                <string>93428</string>
              </value>
            </member>
            <member>
              <name>Country</name>
              <value>
                <string>United States of America</string>
              </value>
            </member>
            <member>
              <name>CountryCode</name>
              <value>
                <string>US</string>
              </value>
            </member>
            <member>
              <name>currency_id</name>
              <value>
                <int>1</int>
              </value>
            </member>
            <member>
              <name>language_id</name>
              <value>
                <int>1</int>
              </value>
            </member>
            <member>
              <name>ShipType</name>
              <value>
                <string>standard</string>
              </value>
            </member>
            <member>
              <name>EstimatedShipping</name>
              <value>
                <double>0.0</double>
              </value>
            </member>
            <member>
              <name>EstimatedDistance</name>
              <value>
                <double>35.38288904</double>
              </value>
            </member>
            <member>
              <name>MfgID</name>
              <value>
                <int>138</int>
              </value>
            </member>
            <member>
              <name>CatalogID</name>
              <value>
                <int>0</int>
              </value>
            </member>
            <member>
              <name>CheckDate</name>
              <value>
                <int>156478887</int>
              </value>
            </member>
            <member>
              <name>OrderDate</name>
              <value>
                <int>156478887</int>
              </value>
              <member>
                <name>OrderItems</name>
                <value>
                  <struct>
                    <member>
                      <name>0</name>
                      <value>
                        <struct>
                          <member>
                            <name>ItemID</name>
                            <value>
                              <string>809479</string>
                            </value>
                          </member>
                          <member>
                            <name>ProdName</name>
                            <value>
                              <string>Amazing Product 1</string>
                            </value>
                          </member>
                          <member>
                            <name>PartNumber</name>
                            <value>
                              <string>1220</string>
                            </value>
                          </member>
                          <member>
                            <name>UPC</name>
                            <value>
                              <string>123456789992</string>
                            </value>
                          </member>
                          <member>
                            <name>Quantity</name>
                            <value>
                              <int>1</int>
                            </value>
                          </member>
                          <member>
                            <name>CustPrice</name>
                            <value>
                              <double>11.30 </double>
                            </value>
                          </member>
                          <member>
                            <name>PaymentDisc</name>
                            <value>
                              <double>0.3390 </double>
                            </value>
                          </member>
                          <member>
                            <name>ShopatronDisc</name>
                            <value>
                              <double>0.52206</double>
                            </value>
                          </member>
                          <member>
                            <name>ManufacturerDisc</name>
                            <value>
                              <double>0.3390</double>
                            </value>
                          </member>
                        </struct>
                      </value>
                      <member>
                        <name>1</name>
                        <value>
                          <struct>
                            <member>
                              <name>ItemID</name>
                              <value>
                                <string>809358</string>
                              </value>
                            </member>
                            <member>
                              <name>ProdName</name>
                              <value>
                                <string>Amazing Product 2</string>
                              </value>
                            </member>
                            <member>
                              <name>PartNumber</name>
                              <value>
                                <string>1234</string>
                              </value>
                            </member>
                            <member>
                              <name>UPC</name>
                              <value>
                                <string>123456789993</string>
                              </value>
                            </member>
                            <member>
                              <name>Quantity</name>
                              <value>
                                <int>1</int>
                              </value>
                            </member>
                            <member>
                              <name>CustPrice</name>
                              <value>
                                <double>22.60 </double>
                              </value>
                            </member>
                            <member>
                              <name>PaymentDisc</name>
                              <value>
                                <double>0.6780 </double>
                              </value>
                            </member>
                            <member>
                              <name>ShopatronDisc</name>
                              <value>
                                <double>1.04412</double>
                              </value>
                            </member>
                            <member>
                              <name>ManufacturerDisc</name>
                              <value>
                                <double>0.7780</double>
                              </value>
                            </member>
                          </struct>
                        </value>
                      </member>
                    </struct>
                  </value>
                </member>
              </struct>
            </value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>