shipengine-logo

List Labels

GET /v1/labels

This endpoint returns a list of labels that you've created. You can optionally filter the results as well as control their sort order and the number of results returned at a time.

By default, all labels are returned, 25 at a time, starting with the most recently created ones.

Query Parameters

Query ParameterTypeDescription
label_statusenumerated string,
processing, completed, error, voided		Only return labels that are currently in the specified status
carrier_idstring
ex: se-28529731		Only return labels for a specific carrier account
service_codestring
ex: usps_first_class_mail		Only return labels for a specific carrier service
tracking_numberstring
ex: 1Z5615280351136446		Only return labels with a specific tracking number
batch_idstring
ex: se-28529731		Only return labels that were created in a specific batch
warehouse_idstring
ex: se-28529731		Only return labels that originate from a specific warehouse
created_at_startdate string
(ISO 8601 Standard)
ex: 2019-07-25T15:24:46.657Z		Only return labels that were created on or after a specific date/time
created_at_enddate string
(ISO 8601 Standard)
ex: 2019-07-25T15:24:46.657Z		Only return labels that were created on or before a specific date/time
pageinteger
ex. 100		Return a specific "page" of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page will be returned.
page_sizeinteger
ex. 100		The number of labels to return per response. Defaults to 25.
sort_direnumerated string
asc or desc		Controls the sort order of the query. Defaults to desc.
sort_byenumerated string
modified_at, created_at		Controls which property the query is sorted by. Defaults to created_at

Example Request

The following example demonstrates how to query for the most recent completed label.

The label_status parameter limits the results to completed labels. Setting the page_size parameter to 1 ensures that only the most recent label will be returned, since the default sort order is created_at desc.

1
2
3
4
GET /v1/labels?label_status=completed&page_size=1 HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Cache-Control: no-cache

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
{
  "labels": [
    {
      "label_id": "se-421357",
      "status": "completed",
      "shipment_id": "se-2129025",
      "ship_date": "2019-07-25T05:00:00.000Z",
      "created_at": "2019-07-25T15:24:46.657Z",
      "shipment_cost": {
        "currency": "usd",
        "amount": 18.49
      },
      "insurance_cost": {
        "currency": "usd",
        "amount": 0.0
      },
      "tracking_number": "1Z28A1R91201009738",
      "is_return_label": false,
      "is_international": false,
      "batch_id": "",
      "carrier_id": "se-123890",
      "service_code": "ups_3_day_select",
      "package_code": "package",
      "voided": false,
      "voided_at": null,
      "label_format": "pdf",
      "label_layout": "4x6",
      "trackable": false,
      "carrier_code": "ups",
      "tracking_status": "unknown",
      "label_download": {
        "pdf": "https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.pdf",
        "png": "https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.png",
        "zpl": "https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.zpl",
        "href": "https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.pdf"
      },
      "form_download": null,
      "insurance_claim": null
    }
  ],
  "total": 3820,
  "page": 1,
  "pages": 3820,
  "links": {
    "first": {
      "href": "https://api.shipengine.com/v1/labels?label_status=completed&page=1&page_size=1"
    },
    "last": {
      "href": "https://api.shipengine.com/v1/labels?label_status=completed&page=3820&page_size=1"
    },
    "prev": {},
    "next": {
      "href": "https://api.shipengine.com/v1/labels?label_status=completed&page=2&page_size=1"
    }
  }
}