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:
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. 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. 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. 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 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. 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:
Element Required Parent Element Type Occurs Description username Yes None string 1 OMS username (must be a valid and active user account with System Admin or Order Admin permission). The maximum length is 50. password Yes None string 1 Password for OMS user account. The maximum length is 50. mfg_id Yes None Int 1 The OMS-assigned Manufacturer ID for which order data is being requested; the client can find this in their OMS account. catalog_id Yes None Int 1 The OMS-assigned Catalog ID for which order data is being requested; the client can find this in their OMS account. filters No None struct 0/1 Filters for orders being received. ShipType is the only supported filter. ShipType No filters string 1/filters The 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:
Code Description 0 Success 99 Invalid Authorization 2 Invalid Data. 5 No server or RPC name on file for this data_type. 7 Error 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:
Record the outgoing package and the associated fault code response from OMS. Test for connectivity to the server. Hold the XML package for future transmission to OMS servers. Send an email to OMS Merchant Support. Include the time and date of the failed transmission. 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 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. 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:
Element Required Parent Element Type Occurs Description method name Yes None 1 The specific RPC that the OMS server is to call. ManufacturerID Yes None int 1 The OMS-assigned Manufacturer ID. May be identified as a string. CatalogID Yes None int 1 The OMS-assigned Catalog ID. May be identified as a string. order_x Yes None struct num_orders An unnamed container for data about a single order. OrderID Yes order_x int 1/order OMS Order ID (also called the “Order Number”). Address1 Yes order_x string 1/order Line 1 of the ship-to Street Address for the order. The maximum length is 50. Address2 Optional order_x string 1/order Line 2 of the ship-to Street Address. The maximum length is 50. Address3 Optional order_x string 1/order Line 3 of the ship-to Street Address. The maximum length is 50. City Yes order_x string 1/order City of the ship-to address for the order. The maximum length is 50. State Yes order_x string 1/order State or province of the ship-to address for the order (US and Canada only). Zip Yes order_x string 1/order Zip or postal code of the ship-to address for the order. The maximum length is 50. Country Yes order_x string 1/order Country of the ship-to address for the order. The maximum length is 50. CountryCode Yes order_x string 1/order 2-character Country Code of the ship-to address for the order. Country Codes are listed at the end of this document. currency_id Yes order_x int 1/order The 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_id Yes order_x int 1/order The 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). ShipType Yes order_x string 1/order The 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). EstimatedShipping Yes order_x double 1/order The amount of money that the fulfiller will be paid for filling the complete order. EstimatedDistance Yes order_x double 1/order Approximate distance from the fulfiller’s primary location to the ship-to address. MfgID Yes order_x int 1/order OMS-assigned Manufacturer ID. CatalogID Yes order_x int 1/order OMS-assigned Catalog ID. Discount Optional order_x Struct 1/order Container for order discount information. DiscountDescription Yes Discount String 1/discount Description of the order discount. DiscountPercentage Yes Discount Double 1/discount The percentage discount off the order total in decimal form. For example, 50% will be shown as 0.5. DiscountTotal Yes Discount Double 1/discount The amount of discount from the order total. CheckDate Yes order_x Int 1/order The date (in microtime) the order was last updated. OrderDate Yes order_x Int 1/order The date (in microtime) the order was created. OrderItems Yes order_x Struct 1/order Container for all items in the order. item_num Yes OrderItems_x Struct 1/line item Substructure 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. ItemID Yes item_num_x Int 1/ line item The internal OMS-assigned ID for the item. ProdName Yes item_num_x String 1/line item The product name for the item, as assigned by the manufacturer. PartNumber Yes item_num_x String 1/line item The part number for the item, as assigned by the manufacturer. UPC Yes item_num_x String 1/line item The UPC for the item, as assigned by the manufacturer. Options Optional – Required if options are specified item_num_x Struct 1/line item A container for all product options for the item. Options_x Optional – Required if options are specified Options num_options/item Options_x is replaced by a sequential number, where the first option is 0, the second is 1, and so on. option_text Optional – Required if options are specified Options String num_options/item Text description of a product option, as specified by the manufacturer. Quantity Yes item_num_x Int 1/line item The quantity for this item. CustPrice Yes item_num_x Double 1/line item The price the consumer paid for this item. PaymentDisc Yes item_num_x Double 1/line item The amount of money retained by Kibo for payment of processing fees for this item. ShopatronDisc Yes item_num_x Double 1/line item The amount of money retained for the OMS Discount for this item. ManufacturerDisc Optional item_num_x Double 1/line item The 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> 
