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

Move Order

The Move Order API allows a merchant to move certain orders that have been placed on the OMS network. This changes the state of an order. This guide describes how to write and implement the Move Order API. It is intended for technical staff members who have experience building XML package and RPC-style transactions.

With the Move Order API, the user can:

  • Move an order to the Available pool, providing it has not been assigned or charged.
  • Assign an order for merchant fulfillment if it is Waiting for Manufacturer Acceptance. Sales tax can also be assigned for all items in the order or to the shipping costs.
  • Cancel an order if the consumer has not been charged.

Usage Considerations

Each merchant is solely responsible for programming the Move Order API application. Kibo is not responsible for programming, debugging, or supporting any functionality in the merchant’s software.

The Move Order API is executed over HTTPS using XML as the data format. This process can be performed by technical staff skilled in the art of server side scripting and XML data formation.

Getting Started

System Requirements

To use the Move Order 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 the Immediate Move Order application. This application lets the user create an XML package and send the 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 Move Order XML-RPC is summarized here:

  1. Prepare the XML package to obtain event or order information.
  2. Call the immediate.move_order method on OMS servers to transmit the XML package. This initiates the status inquiry. Send the single XML package to the OMS server.
  3. Receive a response from OMS when the request is processed.

Programming the Move Order API

Required and Optional Parameters

There are a number of possible parameters:

ElementRequiredParent ElementTypeOccursDescription
UserNameRequiredNoneString1/packageA valid and active OMS username with correct permissions.
PasswordRequiredNoneString1/packageThe password for the user account.
ManufacturerIDRequiredNoneInteger1/packageOMS manufacturer ID.
CatalogIDRequiredNoneInteger1/packageCatalog ID for this merchant.
Action BlockRequiredNoneStruct1/packageUnnamed holder for OrderID, ExOrderID, Action, ItemTax, ShippingTax.
OrderIDRequiredAction BlockInteger1/Action BlockThe OrderID that was returned by the OMS system when the order was placed.
ExOrderIDRequiredAction BlockString1/Action BlockThe External Order ID that was assigned by the system.
ActionRequiredAction BlockString1/Action BlockThe type of action being requested: SetToBidding (use this option to move the order to the Available Order Pool. This option is available only if the order has not been assigned or charged), AssignToManufacturer (use this option to assign this order to the merchant for fulfillment – in other words, to “accept” the order. This option is available only if the order is Waiting for Manufacturer Acceptance), CancelOrder (if the order is unassigned and uncharged, use this option to cancel the order), ReleaseBackorder (use this option to release an order in back order).
ItemSalesTaxOptionalAction BlockDouble1/Action BlockUsed to apply sales tax to all items in the order. Use this option only with AssignToManufacturer.
ShippingSalesTaxOptionaAction BlockDouble1/Action BlockUsed to apply sales tax to shipping charges for the order. Use this option with AssignToManufacturer.

Example Requests

This first example would cancel the specified order.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
   <methodName>immediate.move_order</methodName>
   <params>
      <param>
         <value>
            <string>username</string>
         </value>
      </param>
      <param>
         <value>
            <string>password</string>
         </value>
      </param>
      <param>
         <value>
            <int>138</int>
         </value>
      </param>
      <param>
         <value>
            <int>0</int>
         </value>
      </param>
      <param>
         <value>
            <struct>
               <member>
                  <name>OrderID</name>
                  <value>
                     <int>123456</int>
                  </value>
               </member>
               <member>
                  <name>ExOrderID</name>
                  <value>
                     <int>999999</int>
                  </value>
               </member>
               <member>
                  <name>Action</name>
                  <value>
                     <string>CancelOrder</string>
                  </value>
               </member>
            </struct>
         </value>
      </param>
   </params>
</methodCall>

This example would assign the specified order to the merchant for fulfillment, with a sales tax of 5.22% and a shipping sales tax of 3.12%.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
   <methodName>immediate.move_order</methodName>
   <params>
      <param>
         <value>
            <string>username</string>
         </value>
      </param>
      <param>
         <value>
            <string>password</string>
         </value>
      </param>
      <param>
         <value>
            <int>138</int>
         </value>
      </param>
      <param>
         <value>
            <int>0</int>
         </value>
      </param>
      <param>
         <value>
            <struct>
               <member>
                  <name>OrderID</name>
                  <value>
                     <int>123456</int>
                  </value>
               </member>
               <member>
                  <name>ExOrderID</name>
                  <value>
                     <int>999999</int>
                  </value>
               </member>
               <member>
                  <name>Action</name>
                  <value>
                     <string>AssignToManufacturer</string>
                  </value>
               </member>
               <member>
                  <name>ItemSalesTax</name>
                  <value>
                     <double>5.22</double>
                  </value>
               </member>
               <member>
                  <name>ShippingSalesTax</name>
                  <value>
                     <double>3.12</double>
                  </value>
               </member>
            </struct>
         </value>
      </param>
   </params>
</methodCall>

Example Responses

On success, the RPC returns a zero. On an error, the RPC returns a response message with a faultCode and faultString. The faultString describes the error and may describe what action to take. In some cases, an Error String is also included, which may be useful for troubleshooting purposes.

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

CodeDescription
0Success: All data received, Order moved and a 0 (Zero) returned.
99Error. Invalid Authorization.
2Error. Order data not correct. Examine error message.
3Error. Order does not belong to the user, or order does not exist.
5Error. Order resolve is currently running.

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>5</int>
               </value>
            </member>
            <member>
               <name>faultString</name>
               <value>
                  <string>Resolve Currently Running</string>
               </value>
            </member>
         </struct>
      </value>
   </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. Hold the XML package for future transmission to OMs’s 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.