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

Search for Customer

The Search Customer API allows the user to find a particular customer based on a number of variables.

Version2.0
Callhttps://integration.shopatron.com/api/v2/customer/
Supported FormatsJSON
HTTP MethodGET
Schemahttps://integration.shopatron.com/api/v2/schema/customerSearch.json

The .json address above can be used to access the schema within Postman. An example use of the Customer 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 customer with a particular first name from a specific manufacturer would use the following format:

  • https://integration.shopatron.com/api/v2/customer/?firstName=[Name]&manufacturerID=[Manufacturer ID]

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

  • https://integration.shopatron.com/api/v2/customer/?manufacturerID=[Manufacturer ID One],[Manufacturer ID Two],[Manufacturer 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/customer/?manufacturerID=[Manufacturer ID]&perPage=2&page=2

Example

In this example, the customer being searched for includes these particular properties:

  • Searching for customer based on their email
  • Resultant customer is Active, with one recent order

Required Parameters

A variety of possible properties can be used to locate an existing customer. The API call always requires at least one of the data points listed below to reference as search terms.

Note that this API will break down search terms such as email addresses based on punctuation and stopwords, meaning that similar results may be returned rather than exact matches. For instance, in a query based on an email address of “a-smith@gmail.com,” the “a’ and hyphen would be dropped and results for other customers with email addresses like “john-smith@gmail.com,” “jane-smith@gmail.com,” etc. would be returned. There is no filter that can be utilized to request for exact matches only, so it is best to provide multiple parameters when searching for a customer. Querying based on email, first name, and last name has a higher likelihood of returning the desired result rather than only based on email or a single name parameter.

ParameterTypeDescription
activeenumWhether the customer is active, inactive, or frozen.
customerIDstringA unique customer identifier, usually an integer. The minimum length is 1. Note that this value is an internal identifier assigned by OMS, not the external customer ID.
emailstringThe email of the customer. The minimum length is 1 and the maximum length is 250
firstNamestringThe customer’s first name. The minimum length is 1 and the maximum length is 300
lastNamestringThe customer’s last name. The minimum length is 1 and the maximum length is 300
phonestringThe customer’s phone number. The minimum length is 1 and the maximum length is 20.
addressstringThe customer’s street address. This can be partial; it is not required to be the entire street address.
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.
searchStringstringA string to search over all fields. The maximum length is 150.
totalOrdersintegerThe number of orders a customer has placed.
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.

The customer can also be searched for by their credit card number, but both of the associated values listed below depend on each other and thus must always be provided together.

ParameterTypeDescription
creditCardFirstFourstringThe first four digits of the customer’s credit card number. The minimum length is 4 and the maximum length is 4.
creditCardLastFourstringThe last four digits of the customer’s credit card number. The minimum length is 4 and the maximum length is 4.

Optional Parameters

ParameterTypeDescription
perPageinteger The (max) number of items to return per results page. The minimum value is “1” and the maximum value is “100”. The default is “10”.
sortBystring The 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 customers matching the example’s parameters. Any amount of additional parameters could be appended if desired.

https://integration.shopatron.com/api/v2/customer/?email=example.user@shopatron.com

The Full Response

This is the full response returned by the API.

{
 "collection": [
 {
  "active": "ACTIVE",
  "customerID": "00000000",
  "email": "EXAMPLE.USER@SHOPATRON.COM",
  "firstName": "example",
  "lastName": "user",
  "lastLogin": "2016-12-18T22:41:43+00:00",
  "phones": [
    "1110000000",
    "2220000000"
   ],
  "recentAddresses": [
   "111 TEST STREET, NEW YORK, US"
  ],
  "recentOrders": [
   0123456
  ],
  "totalOrders": 1
  }
 ]
}