Multi-Page Responses

Some ShipEngine API endpoints return paged results. This keeps response sizes manageable and prevents accidental over-fetching.

Examples of paginated endpoints include:

Pagination Options

All paginated API endpoints support the following fields, though the default values and allowed values may differ for each endpoint:

Query Parameter	Type	Description
`page`	integer	Which page of results you want. Defaults to 1.
`page_size`	integer	The number of resources returned per page. The default varies by API endpoint, as does the max value.
`sort_dir`	`asc` or `desc`	The sort order of results. Defaults to `desc` for most endpoints.
`sort_by`	enumerated string	Which field to sort by. The default value and available values differ by API endpoint.

Pagination Fields

Paginated responses include several fields to help you determine the total number of pages, which page you're on, and how to request other pages.

Field Name	Type	Description
`total`	integer	The total number of resources that match your search criteria
`page`	integer	The current page of results
`pages`	integer	The total number of pages
`links`	object	URLs of the first, last, previous, and next pages of results

Example Request

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

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
     "shipments": [],
     "total": 168,
     "page": 1,
     "pages": 7,
     "links": {
       "first": {
         "href": "https://api.shipengine.com/v1/shipments?sort_dir=desc&sort_by=created_at&page=1&page_size=25"
       },
       "last": {
         "href": "https://api.shipengine.com/v1/shipments?sort_dir=desc&sort_by=created_at&page=7&page_size=25"
       },
       "prev": {},
       "next": {
         "href": "https://api.shipengine.com/v1/shipments?sort_dir=desc&sort_by=created_at&page=2&page_size=25"
       }
     }
   }