Site 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 stringOnly return labels that are currently in the specified status
ex: processing, completed, error, voided
carrier_idstringOnly return labels for a specific carrier account
ex: se-28529731
service_codestringOnly return labels for a specific carrier service
ex: usps_first_class_mail
tracking_numberstringOnly return labels with a specific tracking number
ex: 1Z5615280351136446
batch_idstringOnly return labels that were created in a specific batch
ex: se-28529731
warehouse_idstringOnly return labels that originate from a specific warehouse
ex: se-28529731
created_at_startdate stringOnly return labels that were created on or after a specific date/time
(ISO 8601 Standard)
ex: 2019-07-25T15:24:46.657Z
created_at_enddate stringOnly return labels that were created on or before a specific date/time
(ISO 8601 Standard)
ex: 2019-07-25T15:24:46.657Z
pageintegerReturn 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.
ex. 100
page_sizeintegerThe number of labels to return per response. Defaults to 25.
ex. 100
sort_direnumerated stringControls the sort order of the query. Defaults to desc.
asc or desc
See Extended Description
sort_byenumerated stringControls which property the query is sorted by. Defaults to created_at
modified_at, 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"
}
}
}