KIBO OMS DOCUMENTATION

Search for Shipment

The Search Shipment API offers a means of locating an existing shipment by specifying one or more possible properties. A specific Shipment 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 shipments with two particular characteristics as an example.

Version2.0
Callhttps://integration.shopatron.com/api/v2/shipment/?{parameters}
Supported FormatsJSON
HTTP MethodGET
Schemahttps://integration.shopatron.com/api/v2/schema/shipment.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 a particular customer’s backordered shipments would use the following format:

  • https://integration.shopatron.com/api/v2/shipment/?customerID=[Customer ID]&shipmentStatus=BACKORDER

Example

This example case creates a call that will search for all of the ready shipments for a particular manufacturer. The request will specify the following properties:

  • Manufacturer ID – 00000
  • Shipment Status – READY

Required Parameters

A variety of possible properties can be used to locate an existing shipment. 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 shipments. They must be positive integers.
customerIDstringA unique identifier for the customer, usually an integer. The minimum length is 1.
manufacturerIDstringA single or list of unique identifiers for manufacturers. They must be positive integers.
externalOrderIDstringA client-generated unique identifier for the order. The minimum length is 1 and the maximum length is 100.
orderNumberSearchstringAn order number to search for. This can be an orderID, externalOrderID, or clientOrderNumber. The minimum length is 1 and the maximum length is 100.
retailerIDstringA single or list of unique identifiers for retailers. They must be positive integers.
orderStatusenumThe order’s current status in the fulfillment process.
shipmentStatusenumThe shipment’s fulfillment status within Kibo.

Optional Parameters

The API can also search for any of the below additional elements. Besides information about the shipment itself, some of these parameters allow the search results to be filtered based on different criteria.

ParameterTypeDescription
catalogIDintegerThe catalog number for a manufacturer. The minimum value is "0".
readyDateStartstringFind shipments that were ready on or after this date. Supports date-time format.
readyDateEndstringFind shipments that were ready on or before this date. Supports date-time format.
backorderDateStartstringFind shipments that were put on backorder on or after this date. Supports date-time format.
backorderDateEndstringFind shipments that were put on backorder on or before this date. Supports date-time format.
backorderReleaseDateStartstringFind shipments that are set to be released from backorder on or after this date. Supports date-time format.
backorderReleaseDateEndstringFind shipments that are set to be released from backorder on or before this date. Supports date-time format.
condensedResponsebooleanSupplying "true" excludes orderItems, capabilities, and restrictions from the response.
deliveryMethodenumThe method of delivery for the shipment (SHIP_TO_HOME, IN_STORE_PICKUP, SHIP_TO_STORE, SHIP_TO_STORE_PLUS, or DIGITAL).
excludeFraudulentbooleanSupplying "true" causes all orders with potential fraud issues to be excluded from the response.
externalStoreIDstringA client-generated unique identifier for the fulfillment 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 this shipment belongs to (STS, STH, ISPU, TISPU, or TRANSFER).
shipmentStateCodestringAn identifier for the shipment’s specific status.
shipmentStateNamestringThe name of the state code.
shipTypeenumThe order’s shipping method (REGULAR, EXPRESS_1_DAY, EXPRESS_2_DAY, or EXPRESS_3_DAY).

The Full Request

Using the URL format as outlined above, the entire call is fairly simple to put together. This sample will search for shipments matching the example’s parameters. Any amount of additional parameters could be appended if desired.

https://integration.shopatron.com/api/v2/shipment/?manufacturerID=00000&shipmentStatus=READY

The Full Response

The API returns the following response. The object returned is a Collection, which contains all of the shipment results that fit the provided information. The response details all of the information associated with the shipment: the shipping information, included items, and so forth. It follows the same organizational structure as the standard Get Shipment Information response.

In this case, the search returned a single shipment (Shipment ID 1234567).

{
    "collection": [
        {
            "shipmentID": 1234567,
            "orderID": 7654321,
            "manufacturerID": 00000,
            "externalOrderID": "11111111111",
            "catalogID": 1,
            "shipmentStatus": "READY",
            "shipmentStateCode": "1-100",
            "shipmentStateName": "accept_order",
            "shipmentStateType": "STH",
            "shipType": "REGULAR",
            "packingListLink": "https://www.shopatron.com/...",
            "assignedLocation": 12345,
            "shipperName": "DISTRIBUTION CENTER",
            "shippingAddress": "11111111",
            "shippingAddressInformation": {
                "addressID": "0000000",
                "customerID": "1234567",
                "firstName": "Test",
                "lastName": "User",
                "addressLine1": "111 Test St",
                "phone": "000-000-0000",
                "city": "Testville",
                "state": "CA",
                "postalCode": "00000",
                "countryCode": "US",
                "fraudLock": false,
                "active": true,
                "latitude": 00.0000,
                "longitude": -0000,
                "isBilling": false,
                "isShipping": false
            },
            "items": [
                {
                    "orderItemID": 1122333,
                    "itemState": "NORMAL",
                    "orderID": 7654321,
                    "shipmentID": 1234567,
                    "manufacturerID": 00000,
                    "partNumber": "111-2222-33-S",
                    "upc": "0987654321",
                    "description": "Shirt",
                    "quantity": 1,
                    "subtotal": 20,
                    "subtotalTaxAmount": 1.06,
                    "subtotalGross": 21.06,
                    "retailPrice": 29.98,
                    "mfgOfferPrice": 20,
                    "lineDiscount": 0,
                    "shipping": 0,
                    "actualPrice": 20,
                    "actualPriceTaxAmount": 1.06,
                    "taxRate": 0.053,
                    "customData": {

                    },
                    "options": [
                        "color: Navy",
                        "size: S"
                    ],
                    "serialNumberRequired": true,
                    "capabilities": [
                        "DUPLICATE_ORDER",
                        "CANCEL_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",
                        "AUTO_ASSIGN_ITEM",
                        "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_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": [
                        "CANCEL_ORDER",
                        "UNCANCEL_ORDER",
                        "AUTO_ASSIGN_ORDER",
                        "REASSIGN_ORDER",
                        "UNCANCEL_SHIPMENT",
                        "UNFULFILL_SHIPMENT",
                        "UNCANCEL_ITEM",
                        "RETURN_ITEM",
                        "PROCESS_RETURN"
                    ],
                    "discounts": []
                }
            ],
            "orderType": "STANDARD",
            "createDate": "2017-09-08T12:36:05+00:00",
            "orderDate": "2017-08-31T22:37:02+00:00",
            "subtotal": 20,
            "total": 21.06,
            "shippingFee": 0,
            "shippingTax": 0,
            "shippingTaxRate": 0,
            "shipmentItemTax": 1.06,
            "shopatronTotal": 3.29,
            "packageFee": 1.29,
            "fulfillerTotal": 17.77,
            "fulfillerShipping": 0,
            "fulfillerTax": 0.99,
            "readyDate": "2017-09-08T12:36:05+00:00",
            "isLate": false,
            "capabilities": [
                "DUPLICATE_ORDER",
                "CANCEL_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",
                "AUTO_ASSIGN_ITEM",
                "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_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": [
                "CANCEL_ORDER",
                "UNCANCEL_ORDER",
                "AUTO_ASSIGN_ORDER",
                "REASSIGN_ORDER",
                "UNCANCEL_SHIPMENT",
                "UNFULFILL_SHIPMENT",
                "UNCANCEL_ITEM",
                "RETURN_ITEM",
                "PROCESS_RETURN"
            ],
            "isGift": false,
            "isTestOrder": false
        },
    ],

}

Megan MayfieldOMS Dev: Search for Shipment