Site Logo

List Labels

To get a list of labels you've created in ShipEngine, you make a GET call to the /v1/labels endpoint.

By default, this endpoint returns all labels, 25 at a time, starting with those most recently created.

You can optionally use query parameters to filter the results as well as control their sort order and the number of results returned at a time.

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
Uses 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
Uses 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. See Extended Description for more details.
asc or desc (defaults to desc).
sort_byenumerated stringControls which property the query is sorted by. Defaults to created_at
modified_at, created_at

Extended Description: sort_dir

  • The sort_dir property determines which part of the data, oldest or newest, will be returned, not the order of the shipments in the response. The data is always from oldest to newest.
  • Page size behavior:
    • When the page_size is set to 100 and fewer than 100 shipments are created, no change will be visible in the returned data. The data will be from oldest to newest.
    • When the page_size is set to 5, in the case of asc, the system will return the five oldest shipments sorted from oldest to newest. While in the case of desc, the system will return the five most recently created shipments, sorted from oldest to newest.

Example Request & Response

The following example demonstrates how to query for the most recently 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

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
57
58
59
60
61
62
63
64
65
66
67
68
69
{
  "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
      },
      "rate_details": [
        {
          "rate_detail_type": "shipping",
          "carrier_description": null,
          "carrier_billing_code": "Base Rate",
          "carrier_memo": null,
          "amount": {
            "currency": "usd",
            "amount": 18.49
          },
          "billing_source": "Carrier"
        }
      ],
      "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"
    }
  }
}