KIBO OMS DOCUMENTATION

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.

Version2.0
Callhttps://integration.shopatron.com/api/v2/order/?{parameters}
Supported FormatsJSON
HTTP MethodGET
Schemahttps://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 here — or go directly to 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

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:

ParameterTypeDescription
orderIDstringA single or list of unique identifiers for orders. They must be positive integers.
shipmentIDstringA single or list of unique identifiers for orders. They must be positive integers.
retailerIDstringA single or list of unique identifiers for retailers. They must be positive integers.
manufacturerIDstringA single or list of unique identifiers for manufacturers. They must be positive integers.
customerIDstringA unique customer identifier, usually an integer. The minimum length is 1.
externalOrderIDstringA client-generated unique identifier for the order.
orderNumberSearchstringAn order number to search for. This could be an orderID, externalOrderID, or clientOrderNumber.
orderStatusenumThe order’s current state in the fulfillment process (AVAILABLE, BACKORDER, etc).

Optional Parameters

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

ParameterTypeDescription
catalogIDintegerThe catalog number for the manufacturer. The minimum value is "0".
deliveryMethodenumThe delivery method of the order (SHIP_TO_HOME, IN_STORE_PICKUP, etc.).
externalStoreIDstringA client-generated unique identifier for the store location.
orderDateStartstringUse in combination with orderDateEnd to search for orders created within a specific timeframe. Supports date-time format.
orderDateEndstringUse in combination with orderDateStart to search for orders created within a specific timeframe. Supports date-time format.
orderTypeenumThe type of order (STANDARD, GIFT_CARD, TRANSFER, etc.).
shipDateStartstringUse in combination with shipDateEnd to search for orders shipped within a specific timeframe. Supports date-time format.
shipDateEndstringUse in combination with shipDateStart to search for orders shipped within a specific timeframe. Supports date-time format.
shipmentStateTypeenumThe type of order that the shipment belongs to (STS, ISPU, etc.).
shipmentStateCodestringAn identifier for the shipment’s specific status.
shipmentStateNamestringThe name of the provided shipmentStateCode.
shipTypeenumThe order’s shipping method (REGULAR, EXPRESS_1_DAY, EXPRESS_2_DAY, or EXPRESS_3_DAY.)
orderFeatureenumSearch for orders with an allowed feature (OPEN_RETURNS).
condensedResponsebooleanSupplying "true" excludes shipments, orderItems, shippingAddressInformation, capabilities, and restrictions from response.
excludeFraudulentbooleanWhen enabled, this flag causes all orders with potential fraud issues to be excluded from the search results.
isGiftbooleanWhether this order is a gift or not.
isExternalPaymentbooleanWhether this order’s payment is external.
partNumberstringThe part number for this product, an identifier unique to the manufacturer. The minimum length is 1 and the maximum length is 50.
UPCstringThe Universal Product Code for this product. The maximum length is 50.
SKUstringThe Stock Keeping Unit code for this product. The maximum length is 50.
paymentTypeenum/stringThe payment type of the order. See the schema for all possible structures.
paymentSubTypeenum/stringThe payment subtype of the order. See the schema for all possible structures.
channelstringA custom channel of order creation.
orderSubtotalMinintegerThe order’s minimum subtotal. The minimum value is "0".
orderSubtotalMaxintegerThe order’s maximum subtotal. The minimum value is "0".

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”:{

            }
        },

Megan MayfieldOMS Dev: Search for Order