List Labels

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

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

You can get labels in one of the following ways:

Use query parameters to filter the results as well as control their sort order and the number of results returned at a time.
Get by label ID if you have the label_id and need only your specified label details.
Get by external shipment ID if you have the external_shipment_id

Use Query Parameters Request & Response

GET /v2/labels

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.

GET /v2/labels?label_status=completed&page_size=1 HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Cache-Control: no-cache

Response

{
 "labels": [
   {
     "label_id": "se-421357",
     "status": "completed",
     "shipment_id": "se-2129025",
     "ship_date": "2024-07-25T05:00:00.000Z",
     "created_at": "2024-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.shipstation.com/v2/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.pdf",
       "png": "https://api.shipstation.com/v2/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.png",
       "zpl": "https://api.shipstation.com/v2/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.zpl",
       "href": "https://api.shipstation.com/v2/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.shipstation.com/v2/labels?label_status=completed&page=1&page_size=1"
   },
   "last": {
     "href": "https://api.shipstation.com/v2/labels?label_status=completed&page=3820&page_size=1"
   },
   "prev": {},
   "next": {
     "href": "https://api.shipstation.com/v2/labels?label_status=completed&page=2&page_size=1"
   }
 }
}

Query Parameters

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

Get Label by ID Request & Response

GET /v2/labels/:label_id

GET /v2/labels/se-28529731 HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

Response

{
 "label_id": "se-28529731",
 "status": "processing",
 "shipment_id": "se-28529731",
 "ship_date": "2024-09-23T00:00:00.000Z",
 "created_at": "2024-09-23T15:00:00.000Z",
 "shipment_cost":
    {
     "currency": "string",
     "amount": 0
    },
 "insurance_cost":
    {
     "currency": "string",
     "amount": 0
    },
 "requested_comparison_amount":
    {
     "currency": "string",
     "amount": 0
    },
 "rate_details":
    [
        {}
    ],
 "tracking_number": "782758401696",
 "is_return_label": true,
 "rma_number": "string",
 "is_international": true,
 "batch_id": "se-28529731",
 "carrier_id": "se-28529731",
 "charge_event": "carrier_default",
 "service_code": "usps_first_class_mail",
 "package_code": "small_flat_rate_box",
 "voided": false,
 "voided_at": "",
 "label_format": "pdf",
 "display_scheme": "label",
 "label_layout": "4x6",
 "trackable": true,
 "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK",
 "carrier_code": "dhl_express",
 "tracking_status": "unknown",
 "label_download":
    {
     "href": "http://api.shipstation.com/v2/labels/se-28529731",
     "pdf": "http://api.shipstation.com/v2/labels/se-28529731",
     "png": "http://api.shipstation.com/v2/labels/se-28529731",
     "zpl": "http://api.shipstation.com/v2/labels/se-28529731"
    },
 "form_download":
    {
     "href": "http://api.shipstation.com/v2/labels/se-28529731",
     "type": "string"
    },
 "paperless_download":
    {
     "href": "http://api.shipstation.com/v2/labels/se-28529731",
     "instructions": null,
     "handoff_code": null
    },
 "insurance_claim":
    {
     "href": "http://api.shipstation.com/v2/labels/se-28529731",
     "type": "string"
    },
 "packages":
    [
        {}
    ],
 "alternative_identifiers":
    [
        {}
    ],
 "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234"
}

Get Label by External Shipment ID Request & Response

GET /v2/labels/external_shipment_id/:external_shipment_id

GET /v2/labels/external_shipment_id/0bcb569d-1727-4ff9-ab49-b2fec0cee5ae HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

Response

{
 "label_id": "se-28529731",
 "status": "processing",
 "shipment_id": "se-28529731",
 "ship_date": "2024-09-23T00:00:00.000Z",
 "created_at": "2024-09-23T15:00:00.000Z",
 "shipment_cost":
    {
     "currency": "string",
     "amount": 0
    },
 "insurance_cost":
    {
     "currency": "string",
     "amount": 0
    },
 "requested_comparison_amount":
    {
     "currency": "string",
     "amount": 0
    },
 "rate_details":
    [
        {
         "rate_detail_type": "uncategorized",
         "carrier_description": "string",
         "carrier_billing_code": "string",
         "carrier_memo": "string",
         "amount":
            {
             "currency": "string",
             "amount": 0
            },
        "rate_detail_attributes":
            {
             "tax_type": "vat",
             "tax_code": "string",
             "tax_percentage": 0
            },
        "billing_source": "string"
        }
    ],
 "tracking_number": "782758401696",
 "is_return_label": false,
 "rma_number": "string",
 "is_international": false,
 "batch_id": "se-28529731",
 "carrier_id": "se-28529731",
 "charge_event": "",
 "service_code": "usps_first_class_mail",
 "package_code": "small_flat_rate_box",
 "voided": false,
 "voided_at": "",
 "label_format": "pdf",
 "display_scheme": "label",
 "label_layout": "4x6",
 "trackable": true,
 "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK",
 "carrier_code": "dhl_express",
 "tracking_status": "unknown",
 "label_download":
    {
     "href": "http://api.shipstation.com/v2/labels/se-28529731",
     "pdf": "http://api.shipstation.com/v2/labels/se-28529731",
     "png": "http://api.shipstation.com/v2/labels/se-28529731",
     "zpl": "http://api.shipstation.com/v2/labels/se-28529731"
    },
 "form_download":
    {
     "href": "http://api.shipstation.com/v2/labels/se-28529731",
     "type": "string"
    },
 "paperless_download":
    {
     "href": "http://api.shipstation.com/v2/labels/se-28529731",
     "instructions": null,
     "handoff_code": null
    },
 "insurance_claim":
    {
     "href": "http://api.shipstation.com/v2/labels/se-28529731",
     "type": "string"
    },
 "packages":
    [
        {
         "package_id": 0,
         "package_code": "small_flat_rate_box",
         "weight":
            {
             "value": 0,
             "unit": "pound"
            },
         "dimensions":
            {
             "unit": "inch",
             "length": 0,
             "width": 0,
             "height": 0
            },
         "insured_value":
            {
             "0":
              {
               "currency": "usd",
               "amount": 0
              },
             "currency": "string",
             "amount": 0
            },
         "tracking_number": "1Z932R800392060079",
         "label_download":
            {
             "href": "http://api.shipstation.com/v2/labels/se-28529731",
             "pdf": "http://api.shipstation.com/v2/labels/se-28529731",
             "png": "http://api.shipstation.com/v2/labels/se-28529731",
             "zpl": "http://api.shipstation.com/v2/labels/se-28529731"
            },
         "form_download":
            {
             "href": "http://api.shipstation.com/v2/labels/se-28529731",
             "type": "string"
            },
         "qr_code_download":
            {
             "href": "http://api.shipstation.com/v2/labels/se-28529731",
             "type": "string"
            },
         "paperless_download":
            {
             "href": "http://api.shipstation.com/v2/labels/se-28529731",
             "instructions": null,
             "handoff_code": null
            },
         "label_messages":
            {
             "reference1": null,
             "reference2": null,
             "reference3": null
            },
         "external_package_id": "string",
         "content_description": "Hand knitted wool socks",
         "sequence": 0,
         "has_label_documents": true,
         "has_form_documents": true,
         "has_qr_code_documents": true,
         "has_paperless_label_documents": true,
         "alternative_identifiers":
            [
             {
              "type": "last_mile_tracking_number",
              "value": "12345678912345678912"
             }
            ]
        }
    ],
 "alternative_identifiers":
    [
        {
         "type": "last_mile_tracking_number",
         "value": "12345678912345678912"
        }
    ],
 "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234"
}

List Labels

Use Query Parameters Request & Response

Query Parameters

Extended Description: sort_dir

Get Label by ID Request & Response

Get Label by External Shipment ID Request & Response

Was this helpful?

Extended Description: `sort_dir`