Query Shipments

Since shipments power most of our services, we allow you to query and manage them. By querying shipments, you expose a paged service that allows you to use multiple filters.

Query Parameters	Description
batch_id	string, See warning below this table when filtering by batch_id
tag	string
shipment_status	pending, processing, label_purchased, cancelled
modified_at_start	date string, (ISO 8601 Standard) 2019-07-25T15:24:46.657Z
modified_at_end	date string, (ISO 8601 Standard) 2019-07-25T15:24:46.657Z
created_at_start	date string, (ISO 8601 Standard) 2019-07-25T15:24:46.657Z
created_at_end	date string, (ISO 8601 Standard) 2019-07-25T15:24:46.657Z
page	integer, defaults to 1
page_size	integer, defaults to 100
sort_dir	asc or desc
sort_by	modified_at, created_at

Warning

Filtering by Batch ID

If you filter by batch, the API will ignore shipment_status, modified_at_start, modified_at_end, created_at_start, created_at_end, and tag. The API assumes you are opening a batch to view what's in the batch queue, and batch_id is the only relevant filter since there are no other filters when executing a batch operation.

Example

GET /v1/shipments

Let's get a list of the last letter created for Mickey using the Disney_Letters tag.

curl -iX GET https://api.shipengine.com/v1/shipments?tag=Disney_Letters&page=1&page_size=1&sort_dir=desc&sort_by=created_at \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__'

{
  "shipments": [
    {
      "shipment_id": "se-2102034",
      "carrier_id": "",
      "external_shipment_id": "1daa0c22-0519-46d0-8653-9f3dc62e7d2c",
      "ship_date": "2019-07-25T05:00:00.000Z",
      "created_at": "2019-07-25T15:24:46.657Z",
      "modified_at": "2019-07-25T15:24:46.657Z",
      "shipment_status": "pending",
      "ship_to": {
        "name": "Mickey and Minnie Mouse",
        "phone": "714-781-4565",
        "company_name": "The Walt Disney Company",
        "address_line1": "500 SOUTH BUENA VISTA STREET",
        "address_line2": "",
        "city_locality": "BURBANK",
        "state_province": "CA",
        "postal_code": "91521-0001",
        "country_code": "US",
        "address_residential_indicator": "No"
      },
      "ship_from": {
        "name": "Dade Murphy",
        "phone": "512-485-4282",
        "company_name": "Zero Cool",
        "address_line1": "345 Chambers Street",
        "address_line2": "Suite 100",
        "city_locality": "New York City",
        "state_province": "NY",
        "postal_code": "10282",
        "country_code": "US",
        "address_residential_indicator": "Unknown"
      },
      "return_to": {
        "name": "Dade Murphy",
        "phone": "512-485-4282",
        "company_name": "Zero Cool Returns",
        "address_line1": "345 Chambers Street",
        "address_line2": "Suite 100",
        "city_locality": "New York City",
        "state_province": "NY",
        "postal_code": "10282",
        "country_code": "US",
        "address_residential_indicator": "Unknown"
      },
      "confirmation": "none",
      "advanced_options": {
        "bill_to_account": null,
        "bill_to_country_code": null,
        "bill_to_party": null,
        "bill_to_postal_code": null,
        "contains_alcohol": false,
        "custom_field1": null,
        "custom_field2": null,
        "custom_field3": null,
        "non_machinable": false,
        "saturday_delivery": false
      },
      "insurance_provider": "",
      "tags": [
        {
          "name": "Disney_Letters"
        },
        {
          "name": "Santa_Letters"
        },
        {
          "name": "Kris_Kringle_Letters"
        }
      ],
      "total_weight": {
        "value": 9.60,
        "units": "ounce"
      },
      "packages": [
        {
          "weight": {
            "value": 9.60,
            "units": "ounce"
          },
          "dimensions": {
            "units": "inch",
            "length": 12.00,
            "width": 7.10,
            "height": 6.00
          },
          "insured_value": {
            "currency": "usd",
            "amount": 0.0
          }
        }
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "pages": 2,
  "links": {
    "first": {
      "href": "https://api.shipengine.com/v1/shipments?tag=Disney_Letters&shipment_status=any&sort_dir=desc&sort_by=created_at&page=1&page_size=1"
    },
    "last": {
      "href": "https://api.shipengine.com/v1/shipments?tag=Disney_Letters&shipment_status=any&sort_dir=desc&sort_by=created_at&page=2&page_size=1"
    },
    "prev": {},
    "next": {
      "href": "https://api.shipengine.com/v1/shipments?tag=Disney_Letters&shipment_status=any&sort_dir=desc&sort_by=created_at&page=2&page_size=1"
    }
  }
}