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.
The .json address above can be used to access the schema within Postman. An example use of the API follows below, or view the schema or the sample Postman collection.
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://integration.shopatron.com/api/v2/return/?orderID=[Order ID]&status=CLOSED
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://integration.shopatron.com/api/v2/return/?orderID=[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
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:
With at least one of the data points from above, the API can also search for any of these additional elements:
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).
"reason": "Product ran small/large",