Search for Order
The Search Order API offers a means of locating an existing order by specifying one or more possible properties. A specific Order 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 orders with three particular characteristics as an example.
| Version | 2.0 |
| Call | https://integration.shopatron.com/api/v2/order/?{parameters} |
| Supported Formats | JSON |
| HTTP Method | GET |
| Schema | https://integration.shopatron.com/api/v2/schema/orderSearch.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 orders in the READY status from a particular manufacturer would use the following format:
- https://integration.shopatron.com/api/v2/order/?manufacturerID=[Manufacturer ID]&orderStatus=READY
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/order/?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/order/?manufacturerID=[Manufacturer ID]&perPage=2&page=2
Example
This example case creates a call that will search for all of the ready orders for a particular manufacturer in a specific date range. The request will specify the following properties:
- Manufacturer ID – 00000
- Order Status – READY
- Date Range – 05/01/2017 through 09/01/2017
Required Parameters
A variety of possible properties can be used to locate an existing order. 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. |
| shipmentID | string | A single or list of unique identifiers for orders. They must be positive integers. |
| retailerID | string | A single or list of unique identifiers for retailers. They must be positive integers. |
| manufacturerID | string | A single or list of unique identifiers for manufacturers. They must be positive integers. |
| customerID | string | A unique customer identifier, usually an integer. The minimum length is 1. |
| externalOrderID | string | A client-generated unique identifier for the order. |
| orderNumberSearch | string | An order number to search for. This could be an orderID, externalOrderID, or clientOrderNumber. |
| orderStatus | enum | The order’s current state in the fulfillment process (AVAILABLE, BACKORDER, etc). |
| shipmentStatus | enum | The shipment’s current state in the fulfillment process (READY, CANCELLED, etc.). |
| 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 |
| catalogID | integer | The catalog number for the manufacturer. The minimum value is “0”. |
| deliveryMethod | enum | The delivery method of the order (SHIP_TO_HOME, IN_STORE_PICKUP, etc.). |
| externalStoreID | string | A client-generated unique identifier for the store location. |
| orderDateStart | string | Use in combination with orderDateEnd to search for orders created within a specific timeframe. Supports date-time format. |
| orderDateEnd | string | Use in combination with orderDateStart to search for orders created within a specific timeframe. Supports date-time format. |
| orderType | enum | The type of order (STANDARD, GIFT_CARD, TRANSFER, etc.). |
| shipDateStart | string | Use in combination with shipDateEnd to search for orders shipped within a specific timeframe. Supports date-time format. |
| shipDateEnd | string | Use in combination with shipDateStart to search for orders shipped within a specific timeframe. Supports date-time format. |
| shipmentStateType | enum | The type of order that the shipment belongs to (STS, ISPU, etc.). |
| shipmentStateCode | string | An identifier for the shipment’s specific status. |
| shipmentStateName | string | The name of the provided shipmentStateCode. |
| shipType | enum | The order’s shipping method (REGULAR, EXPRESS_1_DAY, EXPRESS_2_DAY, or EXPRESS_3_DAY.) |
| orderFeature | enum | Search for orders with an allowed feature (OPEN_RETURNS). |
| condensedResponse | boolean | Supplying “true” excludes shipments, orderItems, shippingAddressInformation, capabilities, and restrictions from response. |
| excludeFraudulent | boolean | When enabled, this flag causes all orders with potential fraud issues to be excluded from the search results. |
| isGift | boolean | Whether this order is a gift or not. |
| isExternalPayment | boolean | Whether this order’s payment is external. |
| partNumber | string | The part number for this product, an identifier unique to the manufacturer. The minimum length is 1 and the maximum length is 50. |
| UPC | string | The Universal Product Code for this product. The maximum length is 50. |
| SKU | string | The Stock Keeping Unit code for this product. The maximum length is 50. |
| paymentType | enum/string | The payment type of the order. See the schema for all possible structures. |
| paymentSubType | enum/string | The payment subtype of the order. See the schema for all possible structures. |
| channel | string | A custom channel of order creation. The maximum length is 50. |
| orderSubtotalMin | integer | The order’s minimum subtotal. The minimum value is “0”. |
| orderSubtotalMax | integer | The order’s maximum subtotal. The minimum value is “0”. |
| perPage | integer | The (max) number of items to return per page of results. 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. |
A common use of this API is to query orders by orderDate. Combining orderDateStart and orderDateEnd allows the query to return orders that were created within a range of dates and/or times, such as in the below example:
https://integration.shopatron.com/api/v2/order/?manufacturerID=00000&orderDateStart=2020-09-01T00:00:00Z&orderDateEnd=2020-09-01T06:00:00Z
orderDate is also a sortable parameter, so orders can be searched for with any criteria and then sorted by ascending or descending order of the date they were created.
https://integration.shopatron.com/api/v2/order/?manufacturerID=00000&orderStatus=READY&sortBy=orderDate
The Full Request
Using the URL format as outlined above, the entire call is fairly simple to put together. This sample will search for orders matching the example’s parameters. Any amount of additional parameters could be appended if desired.
https://integration.shopatron.com/api/v2/order/?manufacturerID=00000&orderStatus=READY&orderDateStart=2017-05-01T00:00:00Z&orderDateEnd=2017-09-01T00:00:00Z
The Full Response
The API returns the following response. The object returned is a Collection, which contains all of the order results that fit the provided information. The response details all of the information associated with the order: items, shipment details, custom data, and so forth. It follows the same organizational structure as the standard Get Order Information response.
In this case, the search returned a single order (Order ID 1234567).
{ "collection":[
{
"orderID":1234567,
"orderType":"ISPU",
"isTestOrder":true,
"deliveryMethod":"IN_STORE_PICKUP",
"orderCurrency":"USD",
"orderDate": "2017-08-15T22:08:50+00:00",
"orderState":"READY",
"orderStatus":"READY",
"customerSubtotal":5.99,
"subtotal":5.99,
"estimatedShipping":0,
"customerTotal":6.47,
"customerTotalNet":5.99,
"total":6.47,
"singlePackageRequested":false,
"shippingAddress":"1234567",
"shippingAddressInformation":{
"addressID":"1234567",
"customerID":"0000001",
"firstName":"Test",
"lastName":"User",
"addressLine1":"000 Test St",
"phone":"000-000-0000",
"city":"San Luis Obispo",
"state":"CA",
"postalCode":"00000",
"countryCode":"US",
"fraudLock":false,
"active":true,
"latitude":35.2595,
"longitude":-120.653,
"isBilling":false,
"isShipping":false
},
"fraud":12,
"fraudLock":"WILL_CHARGE",
"tax":{
"orderTax":0.48,
"shippingTax":0,
"totalTax":0.48
},
"externalOrderID":"AM_0123456789_000",
"manufacturerID":00000,
"catalogID":0,
"customerID":"0000001",
"customer":{
"customerID":"0000001",
"firstName":"Test",
"lastName":"User",
"email”:"Test.User@kibocommerce.com",
"password”:"*****",
"phone1”:"0000000000",
"active”:"ACTIVE"
},
"shipments":[
{
"shipmentID":7654321,
"orderID":1234567,
"manufacturerID":00000,
"externalOrderID":"AM_0123456789_000",
"catalogID":0,
"shipmentStatus":"READY",
"shipmentStateCode":"4-100",
"shipmentStateName":"accept_order",
"shipmentStateType":"ISPU",
"shipType":"REGULAR",
"packingListLink":"https://www.shopatron.com/...",
"assignedLocation":000000,
"shipperName":"ZZZTest_Location 1",
"shippingAddress":"1234567",
"shippingAddressInformation":{
"addressID":"1234567",
"customerID":"0000001",
"firstName":"Test",
"lastName":"User",
"addressLine1":"000 Test St",
"phone":"000-000-0000",
"city":"San Luis Obispo",
"state":"CA",
"postalCode":"000000",
"countryCode":"US",
"fraudLock":false,
"active":true,
"latitude":35.2595,
"longitude":-120.653,
"isBilling":false,
"isShipping":false
},
"items":[
{
"orderItemID":0000000,
"itemState":"NORMAL",
"orderID":1234567,
"shipmentID":7654321,
"manufacturerID":00000,
"partNumber":"999999",
"sku":"999999",
"description":"Sunglasses",
"quantity":1,
"subtotal":5.99,
"subtotalTaxAmount":0.48,
"subtotalGross":6.47,
"retailPrice":10.99,
"mfgOfferPrice":5.99,
"lineDiscount":0,
"shipping":5,
"actualPrice":5.99,
"actualPriceTaxAmount":0.48,
"taxRate":0.08013,
"customData":{
"image_url":"",
"product code":"986753421"
},
"capabilities":[
"DUPLICATE_ORDER",
"CANCEL_SHIPMENT",
"REASSIGN_SHIPMENT",
"BACKORDER_SHIPMENT",
"REASSIGN_ITEM",
"BACKORDER_ITEM",
"CANCEL_ITEM",
"ADD_ITEM",
"INCREASE_ITEM_QUANTITY",
"DECREASE_ITEM_QUANTITY",
"INCREASE_ITEM_PRICE",
"DECREASE_ITEM_PRICE",
"INCREASE_ITEM_TAX",
"DECREASE_ITEM_TAX",
"OFFER_APPEASEMENT",
"ADD_PROMOTION",
"EDIT_CONSUMER_NAME",
"EDIT_CONSUMER_EMAIL",
"EDIT_CONSUMER_PHONE_NUMBER",
"EDIT_CONSUMER_BILLING_ADDRESS",
"ADD_PAYMENT_METHOD_CREDIT_CARD",
"ADD_PAYMENT_METHOD_GIFT_CARD",
"ADD_NOTE",
"VIEW_RESTRICTED_NOTE",
"ORDER_ROUTING_LOGS",
"ORDER_SNAPSHOTS"
],
"restrictions":[
"AUTO_ASSIGN_ORDER",
"AUTO_ASSIGN_SHIPMENT",
"INCREASE_SHIPPING_AND_HANDLING",
"DECREASE_SHIPPING_AND_HANDLING",
"VIEW_TRACKING_INFORMATION",
"ADD_TRACKING_TO_SHIPMENT",
"EDIT_TRACKING_NUMBER",
"DELETE_TRACKING_NUMBER",
"AUTO_ASSIGN_ITEM",
"EDIT_CONSUMER_SHIPPING_ADDRESS",
"CANCEL_ORDER",
"UNCANCEL_ORDER",
"REASSIGN_ORDER",
"UNCANCEL_SHIPMENT",
"UNFULFILL_SHIPMENT",
"UNCANCEL_ITEM",
"RETURN_ITEM",
"PROCESS_RETURN"
],
"discounts":[
]
}
],
"orderType":"ISPU",
"createDate":"2017-08-15T22:09:08+00:00",
"orderDate":"2017-08-15T22:08:50+00:00",
"subtotal":5.99,
"total":6.47,
"shippingFee":0,
"shippingTax":0,
"shippingTaxRate":0.196,
"shipmentItemTax":0.48,
"shopatronTotal":1.9,
"packageFee":1.29,
"fulfillerTotal":4.57,
"fulfillerShipping":0,
"fulfillerTax":0.45,
"readyDate":"2017-08-15T22:09:08+00:00",
"isLate":false,
"capabilities":[
"DUPLICATE_ORDER",
"CANCEL_SHIPMENT",
"REASSIGN_SHIPMENT",
"BACKORDER_SHIPMENT",
"REASSIGN_ITEM",
"BACKORDER_ITEM",
"CANCEL_ITEM",
"ADD_ITEM",
"INCREASE_ITEM_QUANTITY",
"DECREASE_ITEM_QUANTITY",
"INCREASE_ITEM_PRICE",
"DECREASE_ITEM_PRICE",
"INCREASE_ITEM_TAX",
"DECREASE_ITEM_TAX",
"OFFER_APPEASEMENT",
"ADD_PROMOTION",
"EDIT_CONSUMER_NAME",
"EDIT_CONSUMER_EMAIL",
"EDIT_CONSUMER_PHONE_NUMBER",
"EDIT_CONSUMER_BILLING_ADDRESS",
"ADD_PAYMENT_METHOD_CREDIT_CARD",
"ADD_PAYMENT_METHOD_GIFT_CARD",
"ADD_NOTE",
"VIEW_RESTRICTED_NOTE",
"ORDER_ROUTING_LOGS",
"ORDER_SNAPSHOTS"
],
"restrictions":[
"AUTO_ASSIGN_ORDER",
"AUTO_ASSIGN_SHIPMENT",
"INCREASE_SHIPPING_AND_HANDLING",
"DECREASE_SHIPPING_AND_HANDLING",
"VIEW_TRACKING_INFORMATION",
"ADD_TRACKING_TO_SHIPMENT",
"EDIT_TRACKING_NUMBER",
"DELETE_TRACKING_NUMBER",
"AUTO_ASSIGN_ITEM",
"EDIT_CONSUMER_SHIPPING_ADDRESS",
"CANCEL_ORDER",
"UNCANCEL_ORDER",
"REASSIGN_ORDER",
"UNCANCEL_SHIPMENT",
"UNFULFILL_SHIPMENT",
"UNCANCEL_ITEM",
"RETURN_ITEM",
"PROCESS_RETURN"
],
"isGift":false,
"isTestOrder":true
}
],
"customData":{
},
"orderManagementFee":1.9,
"shipType":"REGULAR",
"ipAddress":"0.1.2.3",
"capabilities":[
"DUPLICATE_ORDER",
"CANCEL_ORDER",
"UNCANCEL_ORDER",
"REASSIGN_ORDER",
"CANCEL_SHIPMENT",
"UNCANCEL_SHIPMENT",
"REASSIGN_SHIPMENT",
"BACKORDER_SHIPMENT",
"UNFULFILL_SHIPMENT",
"REASSIGN_ITEM",
"BACKORDER_ITEM",
"CANCEL_ITEM",
"UNCANCEL_ITEM",
"ADD_ITEM",
"INCREASE_ITEM_QUANTITY",
"DECREASE_ITEM_QUANTITY",
"INCREASE_ITEM_PRICE",
"DECREASE_ITEM_PRICE",
"INCREASE_ITEM_TAX",
"DECREASE_ITEM_TAX",
"RETURN_ITEM",
"PROCESS_RETURN",
"OFFER_APPEASEMENT",
"ADD_PROMOTION",
"EDIT_CONSUMER_NAME",
"EDIT_CONSUMER_EMAIL",
"EDIT_CONSUMER_PHONE_NUMBER",
"EDIT_CONSUMER_BILLING_ADDRESS",
"ADD_PAYMENT_METHOD_CREDIT_CARD",
"ADD_PAYMENT_METHOD_GIFT_CARD",
"ADD_NOTE",
"VIEW_RESTRICTED_NOTE",
"ORDER_ROUTING_LOGS",
"ORDER_SNAPSHOTS"
],
"restrictions":[
"AUTO_ASSIGN_ORDER",
"AUTO_ASSIGN_SHIPMENT",
"INCREASE_SHIPPING_AND_HANDLING".
"DECREASE_SHIPPING_AND_HANDLING",
"VIEW_TRACKING_INFORMATION",
"ADD_TRACKING_TO_SHIPMENT",
"EDIT_TRACKING_NUMBER",
"DELETE_TRACKING_NUMBER",
"AUTO_ASSIGN_ITEM",
"EDIT_CONSUMER_SHIPPING_ADDRESS"
],
"isInventory":true,
"isGift":false,
"isExternalPayment":false,
"discounts":[
],
"orderReferences":{
}
},