Search Shipments

Use this endpoint to retrieve previously booked shipments based on a keyword.

REST Endpoint

POST /restapi/v1/customers/:customerId/searchShipments

Request Content Type

application/json

Request JSON Example

POST /restapi/v1/customers/TEST00002/searchShipments

{
  "keyword": "2317948"
}

Explanation of Request Fields

Field	JSON Type	Required	Description
keyword	string	true	name, company, phone, email, tracking number, internal order id, book number, order id, order number, shipper reference

Response Status Code

200 OK

Response Content Type

application/json

Response JSON Example

This will return a maximum of 100 shipments.

{
  "shipments": [
    {
      "bookNumber": "2317948",
      "trackingNumber": "1ZA3R6625221693812",
      "trackingNumbers": ["1ZA3R6625221693812"],
      "voided": false,
      "carrierCode": "ups",
      "serviceCode": "ups_ground",
      "packageTypeCode": "ups_custom_package",
      "shipmentDate": "2015-04-21",
      "shipmentReference": "abc123",
      "contentDescription": "",
      "sender": {
        "name": "Albert Jones",
        "company": "Jones Co.",
        "address1": "123 Some Street",
        "address2": "#54",
        "city": "Holladay",
        "state": "UT",
        "zip": "84117",
        "country": "US"
      },
      "receiver": {
        "name": "Alice Jensen",
        "company": "",
        "address1": "54 Green St.",
        "address2": "",
        "city": "Salt Lake City",
        "state": "UT",
        "zip": "84106",
        "country": "US"
      },
      "residential": true,
      "signatureOptionCode": "direct",
      "weightUnit": "lb",
      "dimUnit": "in",
      "currency": "USD",
      "customsCurrency": "USD",
      "pieces": [
        {
          "weight": "1.4",
          "length": "5.1",
          "width": "4",
          "height": "2.5",
          "insuranceAmount": "12.15",
          "declaredValue": null
        }
      ],
      "fulfillment": null,
      "totalShippingCost": 8.75
    }
  ]
}

Explanation of Response Fields

Field	Type	Description
bookNumber	string	Unique ID for this shipment
trackingNumber	string	Carrier specific tracking number for this shipment
trackingNumbers	array of string	All tracking numbers (for multi-piece shipments)
voided	boolean	True if this shipment has been voided
carrierCode	string	The carrier code
serviceCode	string	The service code
packageTypeCode	string	The package type code
shipmentDate	date	The date of the shipment
shipperReference	string	Custom reference field provided from the original order
shipperReference2	string	Another custom reference field provided from the original order
contentDescription	string	Human readable description of content
sender.name	string	Name of sender
sender.company	string	Company name of sender
sender.address1	string	Sender street address line 1
sender.address2	string	Sender street address line 2
sender.city	string	Sender city
sender.state	string	Sender state/province (must be two-character code for US and CA)
sender.zip	string	Sender zip or postal code
sender.country	string	ISO two-character country code
receiver.name	string	Name of receiver
receiver.company	string	Company name of receiver
receiver.address1	string	Receiver street address line 1
receiver.address2	string	Receiver street address line 2
receiver.city	string	Receiver city
receiver.state	string	Receiver state/province (must be two-character code for US and CA)
receiver.zip	string	Receiver zip or postal code
receiver.country	string	ISO two-character country code
residential	boolean	Set to true of the receiver address is residential
signatureOptionCode	string or null	Signature option code for shipment. Null for no signature
weightUnit	string	Either "lb" for pounds or "kg" for kilograms
dimUnit	string or null	Either "in" for inches or "cm" for centimeters or null if packageType has preset dimensions
currency	string	The currency of the provided insuranceAmount, declaredValue, and customsValue (if customsCurrency is not present) fields. Must be "USD" for shippers in the US
customsCurrency	string	If present, is the currency of the provided customsValue. (USD, GBP, CAD, EUR)
pieces[n].weight	string	Numeric weight as a JSON string
pieces[n].length	string or null	Numeric length as a JSON string (set to null if packageType has preset dimensions)
pieces[n].width	string or null	Numeric width as a JSON string (set to null if packageType has preset dimensions)
pieces[n].height	string or null	Numeric height as a JSON string (set to null if packageType has preset dimensions)
pieces[n].insuranceAmount	decimal or null	The value of the piece to be covered by insurance. Must be null for no insurance
pieces[n].declaredValue	decimal or null	The declared value of the piece for international shipments. Must be null for domestic shipments
fulfillment.orderId	string	ID of order that this shipment is associated with
fulfillment.integrationId	string	ID of webship integration associated with order
fulfillment.items[n].productId	string	ID of fulfilled product
fulfillment.items[n].sku	string	Sku of fulfilled product
fulfillment.items[n].lineId	string	ID of fulfilled line item
fulfillment.items[n].quantity	integer	Quantity of items fulfilled
totalShippingCost	decimal	Total end-cost of the shipment