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.
Note that the parameter schemas outlined in this guide are the exact same as in the previous version of OMS, as the Unified Commerce platform supports backwards compatibility for this API. The only change to this request is the format of the base endpoint, as shown in the below table. Remember to provide the x-vol-tenant key for authentication in the headers.
| Production URL | https://{tenantId}-translation.mozu.com/api/v2/shipment/?{parameters} |
| Sandbox URL | https://{tenantId}-translation.sandbox.mozu.com/api/v2/shipment/?{parameters} |
| Supported Formats | JSON |
| HTTP Method | GET |
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://{tenantId}-translation.mozu.com/api/v2/shipment/?customerID=[Customer ID]&shipmentStatus=BACKORDER
In the case of performing a search with multiple terms of the same parameter, such as retrieving multiple customer IDs at once, use a comma-separated list as shown below.
- https://{tenantId}-translation.mozu.com/api/v2/shipment/?customerID=[Customer ID One],[Customer ID Two],[Customer 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://{tenantId}-translation.mozu.com/api/v2/shipment/?customerID=[Customer ID]&perPage=2&page=2
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 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 shipments. They must be positive integers. |
| customerID | string | A unique identifier for the customer, usually an integer. The minimum length is 1. |
| manufacturerID | string | A single or list of unique identifiers for manufacturers. They must be positive integers. |
| externalOrderID | string | A client-generated unique identifier for the order. The minimum length is 1 and the maximum length is 100. |
| orderNumberSearch | string | An order number to search for. This can be an orderID, externalOrderID, or clientOrderNumber. The minimum length is 1 and the maximum length is 100. |
| retailerID | string | A single or list of unique identifiers for retailers. They must be positive integers. |
| orderStatus | enum | The order’s current status in the fulfillment process. |
| shipmentStatus | enum | The shipment’s fulfillment status within Kibo. |
| 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 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.
| Parameter | Type | Description |
| catalogID | integer | The catalog number for a manufacturer. The minimum value is “0”. |
| readyDateStart | string | Find shipments that were ready on or after this date. Supports date-time format. |
| readyDateEnd | string | Find shipments that were ready on or before this date. Supports date-time format. |
| backorderDateStart | string | Find shipments that were put on backorder on or after this date. Supports date-time format. |
| backorderDateEnd | string | Find shipments that were put on backorder on or before this date. Supports date-time format. |
| backorderReleaseDateStart | string | Find shipments that are set to be released from backorder on or after this date. Supports date-time format. |
| backorderReleaseDateEnd | string | Find shipments that are set to be released from backorder on or before this date. Supports date-time format. |
| condensedResponse | boolean | Supplying “true” excludes orderItems, capabilities, and restrictions from the response. |
| deliveryMethod | enum | The method of delivery for the shipment (SHIP_TO_HOME, IN_STORE_PICKUP, SHIP_TO_STORE, SHIP_TO_STORE_PLUS, or DIGITAL). |
| excludeFraudulent | boolean | Supplying “true” causes all orders with potential fraud issues to be excluded from the response. |
| externalStoreID | string | A client-generated unique identifier for the fulfillment 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 this shipment belongs to (STS, STH, ISPU, TISPU, or TRANSFER). |
| shipmentStateCode | string | An identifier for the shipment’s specific status. |
| shipmentStateName | string | The name of the state code. |
| shipType | enum | The order’s shipping method (REGULAR, EXPRESS_1_DAY, EXPRESS_2_DAY, or EXPRESS_3_DAY). |
| perPage | integer | The (max) number of items to return per results 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 shipments matching the example’s parameters. Any amount of additional parameters could be appended if desired.
https://{tenantId}-translation.mozu.com/api/v2/shipment/?manufacturerID=00000&shipmentStatus=READYThe 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
},
],
}