Search for Appeasement

The Search Appeasement API offers a means of locating an existing appeasement by specifying one or more possible properties. A specific Appeasement ID does not have to be known to perform the search, as the response will return all results that fit the criteria. As this guide shows, however, an Order ID is necessary and thus appeasements cannot be searched for if the associated order is unknown.

Version	2.0
Call	https://integration.shopatron.com/api/v2/orderAppeasement/?{parameters}
Supported Formats	JSON
HTTP Method	GET
Schema	https://integration.shopatron.com/api/v2/schema/orderAppeasementSearch.json

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 an order’s appeasements from the same manufacturer would use the following format:

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

Example

This example case creates a call that will search for all of a particular order’s appeasements that are paid by the retailer. The request will specify the following properties:

• Order ID – 01010101
• Credit Payee – Retailer

Required Parameters

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

Parameter	Type	Description
orderID	string	A single or list of unique identifiers for orders. They must be positive integers.
externalOrderID	string	A single or list of unique client-generated identifiers for orders. The minimum length is 1 and the maximum length is 100.
page	integer	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. 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

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

Parameter	Type	Description
retailerID	string	A unique identifier for a retailer. The minimum value is “0”.
manufacturerID	string	A unique identifier for a manufacturer. The minimum value is “1”.
catalogID	integer	The catalog number for the manufacturer. The minimum value is “0”.
catalogIDs	string	A single or list of catalogIDs. They must be positive integers. The minimum value is “1”.
creditPayee	enum	The entity who will pay for the credit (KIBO, SHOPATRON, MANUFACTURER, or RETAILER).
perPage	integer	The (max) number of items to return per page. The minimum value is “1” and the maximum value is “100”. The default is “10”.
sortBy	string	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 appeasements matching the example’s parameters. Any amount of additional parameters could be appended if desired.

https://integration.shopatron.com/api/v2/orderAppeasement/?orderID=20326364&creditPayee=RETAILER

The Full Response

The API returns the following response. The object returned is a Collection, which contains all of the appeasement results that fit the provided information. The response details all of the information associated with the appeasement: payee and credit details, any connected entities such as a manufacturer, and so forth. It follows the same organizational structure as the standard Get Appeasement Information response.

In this case, the search returned two appeasements (Appeasement 123456 and Appeasement 654321). Their results are clearly separated.

{
    "collection": [
        {
            "orderAppeasementID": 123456,
            "orderID": 01010101,
            "externalOrderID": "Order_XX_111_22334455",
            "creditPayee": "RETAILER",
            "creditAmount": 10,
            "creditDescription": "No Inventory",
            "creditCreationTimestamp": "2017-08-24T22:37:46+00:00",
            "manufacturerID": 00000,
            "catalogID": 0
        },
        {
            "orderAppeasementID": 654321,
            "orderID": 01010101,
            "externalOrderID": "Order_XX_333_22221111",
            "creditPayee": "RETAILER",
            "creditAmount": 10,
            "creditDescription": "Shipment Delayed",
            "creditCreationTimestamp": "2017-08-24T22:37:59+00:00",
            "manufacturerID": 00000,
            "catalogID": 0
        },

    ],
}