List 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	Type	Description
`batch_id`	string	Please note when 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.
`tag`	string
`shipment_status`	ennumerated string	`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 25
`sort_dir`	ennumerated string	`asc` or `desc`
`sort_by`	ennumerated string	`modified_at`, `created_at`

Pagination Limits

When listing shipments, there is a maximum pagination offset of 10,000 results. The pagination offset is calculated as page × page_size. If you attempt to request results beyond this offset, the API will return a 400 Bad Request error.

Examples:

If page_size=1, the maximum page you can request is 10,000
If page_size=25 (default), the maximum page you can request is 400 (400 × 25 = 10,000)
If page_size=500, the maximum page you can request is 20 (20 × 500 = 10,000)

Error Response Example:

{
  "request_id": "f41e6bc1-69f0-4b09-b0ab-cd2a3e4f5678",
  "errors": [
    {
      "error_source": "shipengine",
      "error_type": "validation",
      "error_code": "invalid_field_value",
      "message": "Pagination offset exceeds the maximum allowed value of 10000. Please narrow your query using filters such as modified_at_start/modified_at_end.",
      "field_name": "page",
      "field_value": "20000"
    }
  ]
}

How to work around this limit:

If you encounter this pagination limit, add filtering parameters to narrow your results:

Use date range filters like modified_at_start and modified_at_end or created_at_start and created_at_end
Filter by shipment_status, tag, or batch_id

Need Help?

If you're having trouble working within this pagination limit or need assistance optimizing your shipment queries, please contact our API Support team.

Example Request & Response

GET /v1/shipments

In this example, we'll get a list of the last package we sent using the east_warehouse tag.

GET /v1/shipments?tag=east_warehouse&page=1&page_size=1&sort_dir=desc&sort_by=created_at HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__

Response

{
  "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": "Amanda Miller",
        "phone": "555-555-5555",
        "email": "recipient@example.com",
        "address_line1": "525 S Winchester Blvd",
        "city_locality": "San Jose",
        "state_province": "CA",
        "postal_code": "95128",
        "country_code": "US",
        "address_residential_indicator": "yes"
      },
      "ship_from": {
        "company_name": "Example Corp.",
        "name": "John Doe",
        "phone": "111-111-1111",
        "email": "sender@example.com",
        "address_line1": "4009 Marathon Blvd",
        "address_line2": "Suite 300",
        "city_locality": "Austin",
        "state_province": "TX",
        "postal_code": "78756",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "return_to": {
        "company_name": "Example Corp.",
        "name": "John Doe",
        "phone": "111-111-1111",
        "address_line1": "4009 Marathon Blvd",
        "address_line2": "Suite 300",
        "city_locality": "Austin",
        "state_province": "TX",
        "postal_code": "78756",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "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": "east_warehouse"
        }
      ],
      "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=east_warehouse&shipment_status=any&sort_dir=desc&sort_by=created_at&page=1&page_size=1"
    },
    "last": {
      "href": "https://api.shipengine.com/v1/shipments?tag=east_warehouse&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=east_warehouse&shipment_status=any&sort_dir=desc&sort_by=created_at&page=2&page_size=1"
    }
  }
}

List Shipments

Pagination Limits

Example Request & Response

Was this helpful?