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 ofasc
, the system will return the five oldest shipments sorted from oldest to newest. While in the case ofdesc
, the system will return the five most recently created shipments sorted from oldest to newest.
- When the
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" }