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 Order Item

The Search Order Item API offers a means of locating an existing item by specifying one or more possible properties. A specific Order Item 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 items cannot be searched for if the associated order is unknown.

Version2.0
Callhttps://integration.shopatron.com/api/v2/orderItem/?{parameters}
Supported FormatsJSON
HTTP MethodGET
Schemahttps://integration.shopatron.com/api/v2/schema/orderItemSearch.json

The .json address above can be used to access the schema within Postman. An example use of the Order Item 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 canceled items from a particular order would use the following format:

  • https://integration.shopatron.com/api/v2/orderItem/?orderID=[Order ID]&itemState=CANCELED

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/orderItem/?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 20. Switch between pages of results by appending the page parameter to the call. For example:

  • https://integration.shopatron.com/api/v2/orderItem/?orderID=[Order ID]&perPage=2&page=2

Example

This example case creates a call that will search for all order items that belong to a specific shipment within a multi-package order. The request will specify the following properties:

  • Order ID 555555
  • Shipment ID 111111

This guide will demonstrate how to put together each section of the request to find the appropriate items.

Required Parameters

Only one parameter is necessary as a search term to query for Order Items:

ParameterTypeDescription
orderIDstringA single or list of orderIDs. They must be positive integers.

Optional Parameters

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

ParameterTypeDescription
shipmentIDstringA single or list of shipmentIDs. They must be positive integers.
retailerIDstringA single or list of retailerIDs. They must be positive integers. The minimum value is “1”.
manufacturerIDstringA single or list of manufacturerIDs. They must be positive integers. The minimum value is “1”.
catalogIDsstring A single or list of catalogIDs. They must be positive integers. The minimum value is “1”.
itemStateenumThe order item’s current state (NORMAL, PREORDER, PROMOTION, or CANCELED).
pageinteger The page number to begin listing the results from. The default and minimum value is “1”, so it will be automatically set as 1 even if not provided in the search request.
perPageinteger The (max) number of items to return per 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 order items matching the example’s parameters. Any amount of additional parameters could be appended if desired.

https://integration.shopatron.com/api/v2/orderItem/?orderID=555555&shipmentID=111111

The Full Response

The API returns the following response. The object returned is a Collection, which contains all of the order item results that fit the provided information. The response details all of the information associated with the order item: general order information, custom data, item options, and so forth. It follows the same organizational structure as the standard Get Order Item Information response.

In this case, the search returned two order items. Since the request used a Shipment ID as a search parameter, even if this order was split among multiple shipments then only the items in the specified shipment would be returned.

{  
    "collection":[  
        { 
            "orderItemID":10000001,
            "itemState":"NORMAL",
            "orderID":555555,
            "shipmentID":111111,
            "manufacturerID":222222,
            "partNumber":"333333",
            "description":"Leather Boot",
            "quantity":1,
            "subtotal":41.99,
            "subtotalTaxAmount":2.83,
            "subtotalGross":44.82,
            "retailPrice":69.99,
            "mfgOfferPrice":41.99,
            "lineDiscount":0,
            "shipping":0,
            "actualPrice":41.99,
            "actualPriceTaxAmount":2.94,
            "taxRate":0.07,
            "customData":{  
                "mlOrderId":"10101",
                "mlShipmentId":"20202",
                "mlItemId":"30303",
                "giftWrap":"no",
                "productCode":"2222-1111",
                "dateBackOrder":"2001-01-01 00:00:00.0",
                "image_url":""
            },
            "options":[ 
                "Color: Black",
                "Size: 6.5"
            ],
            "capabilities":[  
                "DUPLICATE_ORDER",
                "CANCEL_ORDER",
                "UNCANCEL_ORDER",
                "REASSIGN_ORDER",
                "AUTO_ASSIGN_ORDER",
                "CANCEL_SHIPMENT",
                "UNCANCEL_SHIPMENT",
                "AUTO_ASSIGN_SHIPMENT",
                "REASSIGN_SHIPMENT",
                "BACKORDER_SHIPMENT",
                "INCREASE_SHIPPING_AND_HANDLING",
                "DECREASE_SHIPPING_AND_HANDLING",
                "VIEW_TRACKING_INFORMATION",
                "ADD_TRACKING_TO_SHIPMENT",
                "EDIT_TRACKING_NUMBER",
                "DELETE_TRACKING_NUMBER",
                "UNFULFILL_SHIPMENT",
                "AUTO_ASSIGN_ITEM",
                "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_SHIPPING_ADDRESS",
                "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":[  

            ],
            "discounts":[  
                {  
                    "discountID":333333,
                    "code":"DISCOUNT*|*",
                    "externalDiscountID":"09876",
                    "description":"Your 40% off has been applied!",
                    "amount":28,
                    "type":"ORDER_ITEM_ID"
                }
            ]
        },
        {  
            "orderItemID":90000000,
            "itemState":"NORMAL",
            "orderID":555555,
            "shipmentID":111111,
            "manufacturerID":222222,
            "partNumber":"8888888",
            "description":"Brown Bootie",
            "quantity":1,
            "subtotal":29.99,
            "subtotalTaxAmount":2.02,
            "subtotalGross":32.01,
            "retailPrice":49.99,
            "mfgOfferPrice":29.99,
            "lineDiscount":0,
            "shipping":0,
            "actualPrice":29.99,
            "actualPriceTaxAmount":2.1,
            "taxRate":0.07,
            "customData":{  
                "mlOrderId":"10101",
                "mlShipmentId":"20202",
                "mlItemId":"40404",
                "giftWrap":"no",
                "productCode":"2222-3333",
                "dateBackOrder":"2001-01-01 00:00:00.0",
                "image_url":""
            },
            "options":[  
                "Size: 6.5",
                "Color: Black"
            ],
            "capabilities":[  
                "DUPLICATE_ORDER",
                "CANCEL_ORDER",
                "UNCANCEL_ORDER",
                "REASSIGN_ORDER",
                "AUTO_ASSIGN_ORDER",
                "CANCEL_SHIPMENT",
                "UNCANCEL_SHIPMENT",
                "AUTO_ASSIGN_SHIPMENT",
                "REASSIGN_SHIPMENT",
                "BACKORDER_SHIPMENT",
                "INCREASE_SHIPPING_AND_HANDLING",
                "DECREASE_SHIPPING_AND_HANDLING",
                "VIEW_TRACKING_INFORMATION",
                "ADD_TRACKING_TO_SHIPMENT",
                "EDIT_TRACKING_NUMBER",
                "DELETE_TRACKING_NUMBER",
                "UNFULFILL_SHIPMENT",
                "AUTO_ASSIGN_ITEM",
                "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_SHIPPING_ADDRESS",
                "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":[  

            ],
            "discounts":[  
                {  
                    "discountID":333333,
                    "code":"DISCOUNT*|*",
                    "externalDiscountID":"09876",
                    "description":"Your 40% off has been applied!",
                    "amount":20,
                    "type":"ORDER_ITEM_ID"
                }
            ]
        },
    ]   
}