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:
| Element | Required | Parent Element | Type | Occurs | Description |
| methodName | Yes | None | | 1 | immediate.can_no_longer_ship_order |
| UserName | Yes | None | String | 1 | A valid, active OMS username with correct (Advanced) permission. |
| Password | Yes | None | String | 1 | The OMS password for the user account. |
| MfgID | Yes | None | Int | 1 | If 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. |
| CatalogID | Yes | None | Int | 1 | If 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 Block | Yes | None | Struct | 1 | Unnamed holder for information about the order being canceled or returned. The package includes one Order Block. |
| OrderID | Yes | Order Block | Int | 1 | The OMS-assigned Order Number for the order being canceled or returned. |
| AfterAction | Yes | Order Block | String | 1 | The 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). |
| ReasonCode | Yes | Order Block | Int | 1 | The 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). |
| Items | Yes, if ReasonCode is 2 or 3 | Order Block | String | 1 | A container with information about items that were not in stock. |
| Item Block | Yes, if ReasonCode is 2 or 3 | Items | Int | 1 | A container for the item or items that were not in stock. |
| ItemID | Yes, if ReasonCode is 2 or 3 | Item Block | Struct | 1/item | The internal OMS ID for this item. |
| ShipmentID | Available and required only if AfterAction is ItemCancel | Item Block | String | 1/item | The Shipment ID for the order that includes the canceled item. |
| Quantity | Available and required only if AfterAction is ItemCancel | Item Block | String | 1/item | The 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:
| Code | Description |
| 0 | Success. |
| 1 | Invalid data. |
| 2 | Invalid current order state. |
| 3 | Order not processed – detail in faultString. |
| 4 | Order could not be moved, because it is not assigned to the user. |
| 5 | Resolve currently running. |
| 99 | Invalid 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:
- 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’s 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.