Search for Return


This documentation is for translated APIs and intended only for some implementations who have upgraded from a previous version of Order Management. Verify whether your implementation uses translated APIs before making this call, as you will experience errors if your tenant is not configured to use these. If your implementation is not configured to do so, then refer to the standard API documentation instead.

The Search Return API offers a means of locating an existing return by specifying one or more possible properties. A specific Return ID does not have to be known to perform the search, as the response will return all results that fit the criteria. This guide demonstrates how to find returns based on parameters other than the Return ID.

Note that the parameter schemas outlined in this guide are the exact same as in the previous version of OMS, as the Unified Commerce platform supports backwards compatibility for this API. The only change to this request is the format of the base endpoint, as shown in the below table. Remember to provide the x-vol-tenant key for authentication in the headers.

Production URLhttps://{tenantId}{parameters}
Sandbox URLhttps://{tenantId}{parameters}
Supported FormatsJSON

The request itself is built within the URL by adding a “/?” to the call followed by specific parameters joined by the “&” symbol. For instance, searching for closed returns from a particular order would use the following format:

  • https://{tenantId}[Order ID]&status=CLOSED

In the case of performing a search with multiple terms of the same parameter, such as retrieving multiple order IDs at once, use a comma-separated list as shown below.

  • https://{tenantId}[Order ID One],[Order ID Two],[Order ID Three]

GET calls that support pagination for numerous results, such as when searching, also accept a perPage parameter that defines how many results can be returned on each page. The default is 10 and the maximum is 100. Switch between pages of results by appending the page parameter to the call. For example:

  • https://{tenantId}[Order ID]&perPage=2&page=2


This example case creates a call that will search for all standard returns from a particular manufacturer. The request will specify the following properties:

  • Manufacturer ID – 111111
  • Refund Status – CLOSED

Required Parameters

A variety of possible properties can be used to locate an existing return. The API call always requires at least one of these data points to reference as a search term:

returnIDintegerA unique identifier for a return. The minimum value is “1”.
orderIDstringA single or list of unique identifiers for orders. They must be positive integers.
externalOrderIDstringA client-generated unique identifier for the order. The minimum length is 1 and the maximum length is 100.
shipmentIDstringA single or list of unique identifiers for shipments. They must be positive integers.
manufacturerIDstringA single or list of unique identifiers for manufacturers. They must be positive integers.
retailerIDstringA single or list of unique identifiers for retailers. They must be positive integers.
pageintegerThe page number to begin listing the results from. The default and minimum value is “1”. While this parameter is technically required, this default means that it does not have to be provided in the request unless a different page is specifically desired. Also, note that the page cannot be the sole parameter in the search query – if provided, there must be at least one of the other parameters in this table.

Optional Parameters

With at least one of the data points from above, the API can also search for any of these additional elements:

statusenumThe status of the return (OPEN, PROCESSING, or CLOSED).
createdTimeFromstringSearch for returns created on or after this date. Supports date-time format.
createdTimeTostringSearch for returns created on or before this date. Supports date-time format.
perPageintegerThe (max) number of items to return per page. The minimum value is “1” and the maximum value is “100”. The default is “10”.
sortBystringThe field(s) to sort results by, use a minus (-) in front of field name for descending, a plus (+) for ascending. The minimum length is 1.

The Full Request

Using the URL format as outlined above, the entire call is fairly simple to put together. This sample will search for returns matching the example’s parameters. Any amount of additional parameters could be appended if desired.


The Full Response

The API returns the following response. The object returned is a Collection, which contains all of the return results that fit the provided information. The response details all of the information associated with the return: general information and item details. It follows the same organizational structure as the standard Get Return Information response.

In this case, the search returned a single return (Return ID 00000000).

    "collection": [
            "returnID": 00000000,
            "status": "CLOSED",
            "returnTotal": 148,
            "fulfillerTotal": 133.94,
            "createdTime": "2017-01-12T20:15:11+0000",
            "confirmTime": "2017-01-12T20:16:19+0000",
            "clearedTime": "2017-01-13T08:08:48+0000",
            "orderID": 1234567,
            "shipmentID": 15860660,7654321
            "returnLocation": 12345,
            "item": [
                    "returnItemID": 1111111,
                    "orderItemID": 1010101,
                    "quantity": 1,
                    "returnSubtotal": 148,
                    "fulfillerSubtotal": 133.94,
                    "partNumber": "000-11111-22-S",
                    "UPC": "0123456789",
                    "partName": "Sunglasses",
                    "status": "ACCEPTED",
                    "reason": "Product ran small/large",
                    "options": [
                        "color: Black",
                        "size: S"
            "externalOrderID": "121212121",
            "refundType": "STANDARD"