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

Cannot Ship Order

If a fulfiller has orders assigned to them that they can’t fulfill, using the Cannot Ship Order API may be the solution. Use the Cannot Ship Order API if there are orders that cannot be fulfilled because of insufficient stock for an item or an incorrect shipping amount. With this API, fulfillment partners can return one of their assigned orders to the Available Order pool (with permission).

This API can:

  • Cancel an order or cancel a product from an order
  • Place an order in the Available Order pool for fulfillment partners to request
  • Place an order in Waiting for Manufacturer Acceptance or Waiting for Retailer Acceptance (if there is a backup fulfiller)

Fulfillment partners can use the API to:

  • Return a qualified order to the Available Order pool so that another fulfillment partner can fulfill it. If other fulfillment partners requested the order, it is immediately assigned to the next closest fulfillment partner who placed a request. Otherwise, it is moved to the Available Order pool.

Eligible Order Types

Only qualified orders can be modified with this API. Orders are not qualified if they:

  • Have tracking information entered for them
  • Have been split
  • Are in Waiting for Retailer Acceptance, Waiting for Payment Confirmation, Attempting Charge, or Digital Charge status

Getting Started

System Requirements

To use the Cannot Ship 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 Cannot Ship 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.

Programming the Cannot Ship Order API

Required and Optional Parameters

There are a number of possible parameters:

ElementRequiredParent ElementTypeOccursDescription
methodNameYesNone1immediate.can_no_longer_ship_order
UserNameYesNoneString1A valid, active OMS username with correct (Advanced) permission.
PasswordYesNoneString1The OMS password for the user account.
MfgIDYesNoneInt1If the request is being sent by a merchant, this is the Manufacturer ID (MfgID) assigned by OMS. If the request is being sent by a fulfiller, MfgID is blank.
CatalogIDYesNoneInt1If the request is being sent by a merchant, CatalogID is the Catalog ID assigned by OMS. If the request is being sent by a fulfiller, CatalogID is blank.
Order BlockYesNoneStruct1Unnamed holder for information about the order being canceled or returned. The package includes one Order Block.
OrderIDYesOrder BlockInt1The OMS-assigned Order Number for the order being canceled or returned.
AfterActionYesOrder BlockString1The action being applied to the order. The following AfterAction values are available: default (return the order to the available order pool), WFMA (return the order to Waiting for Manufacturer Acceptance), WFRA (return the order to Waiting for Retailer Acceptance), Cancel -(cancel an order), and CancelItem (cancel an item from an order). Omit AfterAction to return the order to the Available Orders pool (or use default).
ReasonCodeYesOrder BlockInt1The reason the order or item is being canceled or returned. The following reason codes are available: 1 (shipment amount not correct), 2 (no stock on an item), and 3 (both).
ItemsYes, if ReasonCode is 2 or 3Order BlockString1A container with information about items that were not in stock.
Item BlockYes, if ReasonCode is 2 or 3ItemsInt1A container for the item or items that were not in stock.
ItemIDYes, if ReasonCode is 2 or 3Item BlockStruct1/itemThe internal OMS ID for this item.
ShipmentIDAvailable and required only if AfterAction is ItemCancelItem BlockString1/itemThe Shipment ID for the order that includes the canceled item.
QuantityAvailable and required only if AfterAction is ItemCancelItem BlockString1/itemThe number of this item that remains in the order for shipment; that is, if no items remain in the order, Quantity is 0.

Example Requests

This first example is a merchant returning an order to Available. This example shows the minimum option set. AfterAction is not specified because the order is being returned to available. Here, the ReasonCode is 1 (Shipment Amount not correct), so the Items struct is not included.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
   <methodName>immediate.can_no_longer_ship_order</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>OrderID</name>
                  <value>
                     <string>5546504</string>
                  </value>
               </member>
               <member>
                  <name>ReasonCode</name>
                  <value>
                     <string>1</string>
                  </value>
               </member>
            </struct>
         </value>
      </param>
   </params>
</methodCall>

This request is a merchant canceling an order. When canceling an order, a merchant must include the AfterAction parameter, as shown in this example. Here, the ReasonCode is 3 (both), so the Items struct is required.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
   <methodName>immediate.can_no_longer_ship_order</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>OrderID</name>
                  <value>
                     <string>5461393</string>
                  </value>
               </member>
               <member>
                  <name>AfterAction</name>
                  <value>
                     <string>Cancel</string>
                  </value>
               </member>
               <member>
                  <name>ReasonCode</name>
                  <value>
                     <string>3</string>
                  </value>
               </member>
               <member>
                  <name>Items</name>
                  <value>
                     <struct>
                        <member>
                           <name>0</name>
                           <value>
                              <struct>
                                 <member>
                                    <name>ItemID</name>
                                    <value>
                                       <string>7985744</string>
                                    </value>
                                 </member>
                              </struct>
                           </value>
                        </member>
                     </struct>
                  </value>
               </member>
            </struct>
         </value>
      </param>
   </params>
</methodCall>

In this example, a backup fulfiller cancels the order. A backup fulfiller leaves the ManufacturerID and CatalogID blank, as shown. Here, the ReasonCode is 2 (No stock on item), so the items struct is required.

<?xml version="1.0"?>
<methodCall>
  <methodName>immediate.can_no_longer_ship_order</methodName>
  <params>
    <param>
      <value>
        <string>xmluserModellRTL</string>
      </value>
    </param>
    <param>
      <value>
        <string>xmluserModell53308</string>
      </value>
    </param>
    <param>
      <value>
        <int></int>
      </value>
    </param>
    <param>
      <value>
        <int></int>
      </value>
    </param>
    <param>
      <value>
        <struct>
          <member>
            <name>OrderID</name>
            <value>
              <string>5546504</string>
            </value>
          </member>
          <member>
            <name>ReasonCode</name>
            <value>
              <string>2</string>
            </value>
          </member>
          <member>
            <name>Items</name>
            <value>
              <struct>
                <member>
                  <name>0</name>
                  <value>
                    <struct>
                      <member>
                        <name>ItemID</name>
                        <value>
                          <string>7985744</string>
                        </value>
                      </member>
                    </struct>
                  </value>
                </member>
              </struct>
            </value>
          </member>
        </struct>
      </value>
    </param>
  </params>
</methodCall>

In this example, the merchant cancels two items from an order. The Items struct is provided, and includes two additional required parameters: ShipmentID and Quantity of that item that should still be shipped (0). Two sets of ItemID/ShipmentID/Quantity values are included in order to cancel the two items.

<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
   <methodName>immediate.can_no_longer_ship_order</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>OrderID</name>
                  <value>
                     <string>5461393</string>
                  </value>
               </member>
               <member>
                  <name>AfterAction</name>
                  <value>
                     <string>CancelItem</string>
                  </value>
               </member>
               <member>
                  <name>ReasonCode</name>
                  <value>
                     <string>2</string>
                  </value>
               </member>
               <member>
                  <name>Items</name>
                  <value>
                     <struct>
                        <member>
                           <name>0</name>
                           <value>
                              <struct>
                                 <member>
                                    <name>ItemID</name>
                                    <value>
                                       <string>8496127</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ShipmentID</name>
                                    <value>
                                       <string>4454318</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>Quantity</name>
                                    <value>
                                       <string>0</string>
                                    </value>
                                 </member>
                              </struct>
                           </value>
                        </member>
                        <member>
                           <name>1</name>
                           <value>
                              <struct>
                                 <member>
                                    <name>ItemID</name>
                                    <value>
                                       <string>8496128</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>ShipmentID</name>
                                    <value>
                                       <string>4454318</string>
                                    </value>
                                 </member>
                                 <member>
                                    <name>Quantity</name>
                                    <value>
                                       <string>0</string>
                                    </value>
                                 </member>
                              </struct>
                           </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. On success, the RPC returns 0. On an error, the RPC returns a response message with a faultCode and faultString. The faultCode describes the error and may tell the user 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.
1Invalid data.
2Invalid current order state.
3Order not processed – detail in faultString.
4Order could not be moved, because it is not assigned to the user.
5Resolve currently running.
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>2</int>
               </value>
            </member>
            <member>
               <name>faultString</name>
               <value>
                  <string>invalid username or password, or insufficient permissions</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.