Move RMA Process product returns when items are received by using the Move RMA API. Use this API to:
Accept a return Reject a return Accept some returned items but reject others Reopen a closed return Clients who use the Move RMA API to process returned products often use the Create RMA API to initiate or accept return requests.
Getting Started System Requirements To use the Move 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 Move RMA, which assembles the XML package that initiates return processing on OMS servers. They will also need to write the Order Data Receive application, the XML-RPC server application used to receive the data. This is an XML-RPC server that OMS can call to send order data to.
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 RMA XML-RPC is summarized here:
The Move RMA API makes a request for return request processing to the OMS XML-RPC Server. The request includes a username and password for authentication, and a requested action for the entire return or detailed information about all items included in the return request and a requested action for each of them. The RPC authenticates the username and password and verifies the server and RPC name information. Upon authentication, the server responds with a Return (RMA) Number and a success response or an error message and a fault code for the error.
Programming the Move RMA API Server and RPC Information Create an XML RPC message that calls immediate.move_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: 443
Required and Optional Parameters There are a number of possible parameters:
Element Required Parent Element Type Occurs Description UserName Yes None string 1 OMS username (must be a valid and active user account with System Admin or Order Admin permission). Password Yes None string 1 Password for OMS user account. NumOrders Yes None int 1 The number of orders (returns) included in the package. RMA Block Yes None struct 1/RMA A container for information about an individual return. 0-indexed array that increments for each order. There is one Order Block for each order in the package. RMAID Optional RMA Block string 1/RMA The RMA number issued by OMS for this return. Action Optional RMA Block string 0 or 1/RMA The action to apply to the entire RMA: accept, reject, or reopen. If the RMA is reopened, any existing accepted or rejected status is cleared. Include this value if the same action is to be applied to all items in the return. If an action is specified, it will override any action specified for individual items. ReturnLocation Optional RMA Block string 0 or 1/RMA External Store ID Items Optional RMA Block struct 1/RMA A container for all item information in this return. 0-indexed array that increments for each item in the return. If the same action applies to all items in the return, item-level information does not have to be included. Item Block Optional Items struct 1/item Information on individual items in the return. ItemID Optional Item Block int 1/item The internal OMS ID for this item. Quantity Optional Item Block int 1/item The number of items in the return to which the action is being applied. If the Quantity specified here is less than the number of items with this ItemID in the return, the opposite status is assigned to remaining items with this ItemID. Action Optional Item Block string 1/item The action to apply to these items: accept or reject. An individual item cannot be reopened; the user must reopen the RMA itself. Note that if an action is applied to the entire RMA, this value is ignored.
Example Requests The same action (reopen) applies to all items in the RMA. Note that item-level information is not included.
<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
<methodName>immmediate.move_rma</methodName>
<params>
<param>
<value>
<string>xml_user</string>
</value>
</param>
<param>
<value>
<string>ABC123DEF456</string>
</value>
</param>
<param>
<value>
<int>1</int>
</value>
</param>
<param>
<value>
<struct>
<member>
<name>0</name>
<value>
<struct>
<member>
<name>RMAID</name>
<value>
<string>2444</string>
</value>
</member>
<member>
<name>Action</name>
<value>
<string>reopen</string>
</value>
</member>
<member>
<name>ReturnLocation</name>
<value>
<string>4445365852</string>
</value>
</member>
</struct>
</value>
</member>
</struct>
</value>
</param>
</params>
</methodCall>
In this sample, one item in a return is accepted, and the other is rejected.
<?xml version="1.0" encoding="UTF-8"?>
<methodCall>
<methodName>immmediate.move_rma</methodName>
<params>
<param>
<value>
<string>xml_user</string>
</value>
</param>
<param>
<value>
<string>ABC123DEF456</string>
</value>
</param>
<param>
<value>
<int>1</int>
</value>
</param>
<param>
<value>
<struct>
<member>
<name>0</name>
<value>
<struct>
<member>
<name>RMAID</name>
<value>
<string>2444</string>
</value>
</member>
<member>
<name>Items</name>
<member>
<name>0</name>
<value>
<struct>
<member>
<name>ItemID</name>
<value>
<int>1585677</int>
</value>
</member>
<member>
<name>Quantity</name>
<value>
<int>2</int>
</value>
</member>
<member>
<name>Action</name>
<value>
<string>accept</string>
</value>
</member>
</struct>
</value>
</member>
<member>
<name>1</name>
<value>
<struct>
<member>
<name>ItemID</name>
<value>
<string>1585678</string>
</value>
</member>
<member>
<name>Quantity</name>
<value>
<int>1</int>
</value>
</member>
<member>
<name>Action</name>
<value>
<string>reject</string>
</value>
</member>
</struct>
</value>
</member>
</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 matching the order struct passed in, but lists the next step for each order or an error message for each order. 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 number of parameters. 2 Invalid username or password. 3 Invalid type of parameters. 4 Invalid username or password.
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>RMAID</name>
<value>
<int>2197725</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 insuffucient 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. 
