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>