OMS DOCUMENTATIONRESOURCE CENTER

These guides provide examples for many tasks that a developer will need to be familiar with during implementation.

KIBO OMS DEVELOPMENT

Documentation

Get Return Location Information

It is also possible to query directly for the return location information, which is accessed through an extension to the Return API. The results list all locations that are available for the specified order to be returned to, which facilitates return management. This is a faster alternative to the two-step process of calling the return order to get a returnLocation ID and then making a request to the Location API.

Version2.0
Callhttps://integration.shopatron.com/api/v2/return/locations/
Supported FormatsJSON
HTTP MethodGET
Schemahttps://integration.shopatron.com/api/v2/schema/returnLocationSearch.json

The .json address above can be used to access the schema within Postman. An example use of this 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 a location associated with an order and a particular manufacturer would use the following format:

  • https://integration.shopatron.com/api/v2/return/locations/?orderID={Order ID}&manufacturerID={Manufacturer ID}

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://integration.shopatron.com/api/v2/return/locations/?orderID=[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://integration.shopatron.com/api/v2/locations/?orderID=[Order ID]&perPage=2&page=2

Example

In this example, the location details include these particular properties:

  • Searching for return locations of Order ID 0123456
  • Results are two locations named “Example Location One” and “Example Location Two”
  • Both are taxable shipping locations in Dallas
  • One has a named primary contact with their additional phone and email, while the other only has the location’s phone

Required Parameters

The API call always requires this data point:

ParameterTypeDescription
orderIDintegerA unique identifier for the order. The minimum value is “1”.
pageinteger The 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.

Optional Parameters

The API can also search for any of these additional elements:

ParameterTypeDescription
manufacturerIDstringA single or list of unique identifiers for manufacturers. These should be positive integers. The minimum length is 1.
retailerIDstringA single or list of unique identifiers for retailers. These should be positive integers. The minimum length is 1.
perPage The (max) number of items to return. The minimum value is “1” and the maximum value is “100”. The default is “10”.

The Full Request

This is the full request that will obtain the particular return location.

https://integration.shopatron.com/api/v2/return/locations/?orderID=0123456

The Full Response

This is the full response returned by the API. This particular search returned two results, as seen in their separate data blocks.

{
 "collection": [
  {
   "locationID": 00001,
   "manufacturerID": 33333,
   "fulfillerID": 22222,
   "name": "Example Location One",
   "addressLine1": "1010 Example Ave",
   "city": "Dallas",
   "countryCode": "US",
   "contact": " ",
   "phone": "000-000-0000",
   "localSalesTax": 0.06075,
   "active": true,
   "shippingLocation": true,
   "restockEnabled": false,
   "pickupEnabled": false,
   "showInAggregateReport": false,
   "taxableLocation": true,
   "mainLocation": false,
   "lastUpdated": "2018-01-03T16:14:21+0000"
  },

  {
   "locationID": 00002,
   "retailerID": 88888,
   "fulfillerID": 99999,
   "name": "Example Location Two",
   "addressLine1": "0101 Example Rd",
   "city": "Dallas",
   "state": "TX",
   "countryCode": "US",
   "postalCode": "75201",
   "latitude": 29.4786,
   "longitude": -98.4872,
   "contact": "John Smith",
   "contactPhone": "0000000000",
   "phone": "0000000000",
   "email": "johnsmith@kibocommerce.com",
   "localSalesTax": 0.0825,
   "active": true,
   "shippingLocation": true,
   "restockEnabled": false,
   "pickupEnabled": false,
   "showInAggregateReport": true,
   "taxableLocation": true,
   "hasStorefront": true,
   "mainLocation": false,
   "express": true,
   "lastUpdated": "2018-01-01T00:20:51+0000"
  }
 ]
}