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.