Create RMA
Use the Create RMA API to automate the return initiation process. The user can also accept returns with this API. Most of Kibo’s clients who use the Create RMA API to initiate returns use the Move RMA API to process product returns when they receive them.
Getting Started
System Requirements
To use the Create RMA API, there should be a server with Internet access that runs the client’s shopping cart software to gather the order data.
Writing the Application
The client needs to write the Immediate Create RMA application. This application assembles an XML package to request merchant Return (RMA) Numbers from OMS servers.
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 OMS Create RMA API XML-RPC is summarized here:
The Create RMA API issues a return request to the OMS XML-RPC Server. The request includes a user name and password for authentication, detailed information about all items included in the RMA, and, optionally, a requested action. The RPC authenticates the user name and password and verifies the server and RPC name information. Upon authentication, the server responds with a return number for the order.
Programming the Create RMA API
Server and RPC Information
Create an XML-RPC message that calls immediate.create_rma and passes an array of the parameters listed in the table that defines the data elements, below. Create an XML-RPC client that connects to the following server:Server file name: /xmlAdvServer.php Server address: xml.shopatron.com Server port: 80 (may use HTTPS port: default is 443)
Required and Optional Parameters
There are a number of possible parameters:
Element Required Parent Element Type Occurs Description UserName Yes None string 1 A valid and active OMS user name with correct permissions. Password Yes None string 1 The password for the user account. NumOrders Yes None int 1 The number of orders being submitted for return requests. Request Block Yes None struct 1 A container for all order information. 0-indexed array that increments for each order. Order Block Yes Request Block struct 1/order Unnamed holder for individual order information. There is one Order Block for each order in the package. OrderID Yes Order Block int 1/order The Order ID that was provided by the OMS system when the order was placed. ShipmentID Yes Order Block int 1/order The Shipment ID that was provided by the OMS system when the order was placed. Action Optional Order Block string 1/order The initial action to be applied to all items in the returned order. Acceptable values are: Open and Accept. If no action is specified, the default is Open. Include an action of Accept to automatically accept the items in the returned order. ReturnLocation Optional Order Block string 1/order External Store ID Items Yes Order Block struct 1/order A container for all item information in this return. Item Block Yes Items struct 1/item A container for information about an individual item in the return. 0-indexed array that increments for each order. There is one Item Block for each item in the returned order. ItemID Yes Item Block int 1/item The internal OMS ID for this item. Quantity Yes Item Block int 1/item The quantity of this specific item in the return.
Example Requests
The first example is a minimal XML-RPC message.
<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
<methodName>immediate.create_rma</methodName>
<params>
<param>
<value>
<string>xml_user</string>
</value>
</param>
<param>
<value>
<string>password</string>
</value>
</param>
<param>
<value>
<int>1</int>
</value>
</param>
<param>
<value>
<struct>
<member>
<name>0</name>
<value>
<struct>
<member>
<name>OrderID</name>
<value>
<int>1234567</int>
</value>
</member>
<member>
<name>ShipmentID</name>
<value>
<int>585677</int>
</value>
</member>
<member>
<name>Items</name>
<value>
<struct>
<member>
<name>0</name>
<value>
<struct>
<member>
<name>ItemID</name>
<value>
<string>7654321</string>
</value>
</member>
<member>
<name>Quantity</name>
<value>
<int>1</int>
</value>
</member>
</struct>
</value>
</member>
</struct>
</value>
</member>
</struct>
</value>
</member>
</struct>
</value>
</param>
</params>
</methodCall>
This request contains all of the elements.
<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
<methodName>immediate.create_rma</methodName>
<params>
<param>
<value>
<string>xml_user</string>
</value>
</param>
<param>
<value>
<string>password</string>
</value>
</param>
<param>
<value>
<int>2</int>
</value>
</param>
<param>
<value>
<struct>
<member>
<name>0</name>
<value>
<struct>
<member>
<name>OrderID</name>
<value>
<int>1585677</int>
</value>
</member>
<member>
<name>ShipmentID</name>
<value>
<int>585677</int>
</value>
</member>
<member>
<name>Action</name>
<value>
<string>accept</string>
</value>
</member>
<member>
<name>ReturnLocation</name>
<value>
<string>44325648</string>
</value>
</member>
<member>
<name>Items</name>
<value>
<struct>
<member>
<name>0</name>
<value>
<struct>
<member>
<name>ItemID</name>
<value>
<string>1585677</string>
</value>
</member>
<member>
<name>Quantity</name>
<value>
<int>2</int>
</value>
</member>
</struct>
</value>
</member>
<member>
<name>1</name>
<value>
<struct>
<member>
<name>ItemID</name>
<value>
<int>1585678</int>
</value>
</member>
<member>
<name>Quantity</name>
<value>
<int>1</int>
</value>
</member>
</struct>
</value>
</member>
</struct>
</value>
</member>
</struct>
</value>
</member>
<member>
<name>1</name>
<value>
<struct>
<member>
<name>OrderID</name>
<value>
<string>2197491</string>
</value>
</member>
<member>
<name>ShipmentID</name>
<value>
<string>975587</string>
</value>
</member>
<member>
<name>Items</name>
<value>
<struct>
<member>
<name>0</name>
<value>
<struct>
<member>
<name>ItemID</name>
<value>
<string>2076115</string>
</value>
</member>
<member>
<name>Quantity</name>
<value>
<int>0</int>
</value>
</member>
</struct>
</value>
</member>
<member>
<name>1</name>
<value>
<struct>
<member>
<name>ItemID</name>
<value>
<string>2076116</string>
</value>
</member>
<member>
<name>Quantity</name>
<value>
<int>2</int>
</value>
</member>
</struct>
</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 a struct containing return request information for each order package passed. On an error, the RPC returns a response message with the faultCode and faultString.
A full list of faultCode and faultString options can be found below:
Code Description 1 Invalid type of parameters. 2 Invalid username or password. 3 No orders to process.
Successful responses may look like the below sample:
<?xml version="1.0" encoding="UTF-8"?>
<methodresponse>
<params>
<param>
<value>
<struct>
<member>
<name>0</name>
<value>
<struct>
<member>
<name>OrderID</name>
<value>
<int>2197725</int>
</value>
</member>
<member>
<name>ShipmentID</name>
<value>
<int>975644</int>
</value>
</member>
<member>
<name>RMAID</name>
<value>
<int>23763</int>
</value>
</member>
<member>
<name>Response</name>
<value>
<int>0</int>
</value>
</member>
<member>
<name>ErrorMessage</name>
<value>
<string />
</value>
</member>
</struct>
</value>
</member>
</struct>
</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.
