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.