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 Parameter Type Description
label_status enumerated string,
processing, completed, error, voided
Only return labels that are currently in the specified status
carrier_id string
ex: se-28529731
Only return labels for a specific carrier account
service_code string
ex: usps_first_class_mail
Only return labels for a specific carrier service
tracking_number string
ex: 1Z5615280351136446
Only return labels with a specific tracking number
batch_id string
ex: se-28529731
Only return labels that were created in a specific batch
warehouse_id string
ex: se-28529731
Only return labels that originate from a specific warehouse
created_at_start date 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_end date string
(ISO 8601 Standard)
ex: 2019-07-25T15:24:46.657Z
Only return labels that were created on or before a specific date/time
page integer
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_size integer
ex. 100
The number of labels to return per response. Defaults to 25.
sort_dir enumerated string
asc or desc
Controls the sort order of the query. Defaults to desc.
sort_by enumerated 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.

curl -iX GET https://api.shipengine.com/v1/labels?label_status=completed&page_size=1 \
-H 'Cache-Control: no-cache' \
-H 'API-Key: __YOUR_API_KEY_HERE__'
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
  • curl
  • http

Example Response

{
  "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"
    }
  }
}