{"templateId":"markdown","versions":[{"version":"shipstation-v2","label":"ShipStation V2 API","link":"/apis/shipstation-v2/docs/reference/list-labels","default":true,"active":false,"folderId":"58c9a61d"},{"version":"shipengine","label":"ShipStation API (formerly ShipEngine)","link":"/apis/shipengine/docs/reference/list-labels","default":false,"active":true,"folderId":"58c9a61d"},{"version":"shipstation-v1","label":"ShipStation V1 API","link":"/apis/shipstation-v1/docs/reference/list-labels","default":false,"active":false,"folderId":"58c9a61d"}],"sharedDataIds":{"sidebar":"sidebar-apis/@shipengine/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"List Labels","keywords":"shipping, labels, shipstation, documentation, api","siteUrl":"https://docs.shipstation.com","lang":"en-US","llmstxt":{"hide":false,"title":"ShipStation API LLM Docs","description":"Find links and references to all markdown documentation for use with LLMs","excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"list-labels","__idx":0},"children":["List Labels"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To get a list of labels you've ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/labels/create-a-label"},"children":["created"]}," in ShipStation API, you make a GET call to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["/v1/labels"]}," endpoint."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, this endpoint returns all labels, 25 at a time, starting with those most recently created."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"query-parameters","__idx":1},"children":["Query Parameters"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Query Parameter"},"children":["Query Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label_status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["enumerated string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Only return labels that are currently in the specified status. ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ex: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processing"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["voided"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carrier_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Only return labels for a specific ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/carriers/setup"},"children":["carrier account"]}," ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ex: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["se-28529731"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["service_code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Only return labels for a specific ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/reference/list-carrier-services"},"children":["carrier service"]}," ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ex: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["usps_first_class_mail"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tracking_number"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Only return labels with a specific tracking number ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ex: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1Z5615280351136446"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["batch_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Only return labels that were created in a specific ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/labels/bulk"},"children":["batch"]}," ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ex: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["se-28529731"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["warehouse_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Only return labels that originate from a specific ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/shipping/ship-from-a-warehouse"},"children":["warehouse"]}," ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ex: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["se-28529731"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at_start"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["date string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Only return labels that were created on or after a specific date/time ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Uses ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://en.wikipedia.org/wiki/ISO_8601"},"children":["ISO 8601 Standard"]},", ex: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2019-07-25T15:24:46.657Z"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at_end"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["date string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Only return labels that were created on or before a specific date/time ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Uses ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://en.wikipedia.org/wiki/ISO_8601"},"children":["ISO 8601 Standard"]},", ex: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2019-07-25T15:24:46.657Z"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["integer"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["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. ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ex. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["100"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page_size"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["integer"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The number of labels to return per response. Defaults to 25. ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ex. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["100"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sort_dir"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["enumerated string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Controls the sort order of the query. See ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Extended Description"]}," for more details.  ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["asc"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["desc"]}," (defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["desc"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sort_by"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["enumerated string"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Controls which property the query is sorted by. Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at"]}," ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["modified_at"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"extended-description-sort_dir","__idx":2},"children":["Extended Description: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sort_dir"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Page size behavior:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["When the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["When the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page_size"]}," is set to 5, in the case of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["asc"]},", the system will return the five oldest shipments sorted from oldest to newest. While in the case of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["desc"]},", the system will return the five most recently created shipments, sorted from oldest to newest."]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-request--response","__idx":3},"children":["Example Request & Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example demonstrates how to query for the most recently completed label."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label_status"]}," parameter limits the results to completed labels. Setting the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page_size"]}," parameter to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}," ensures that only the most recent label will be returned since the default sort order is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["desc"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET /v1/labels?label_status=completed&page_size=1 HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __YOUR_API_KEY_HERE__\nCache-Control: no-cache\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"labels\": [\n    {\n      \"label_id\": \"se-421357\",\n      \"status\": \"completed\",\n      \"shipment_id\": \"se-2129025\",\n      \"ship_date\": \"2019-07-25T05:00:00.000Z\",\n      \"created_at\": \"2019-07-25T15:24:46.657Z\",\n      \"shipment_cost\": {\n        \"currency\": \"usd\",\n        \"amount\": 18.49\n      },\n      \"insurance_cost\": {\n        \"currency\": \"usd\",\n        \"amount\": 0.0\n      },\n      \"rate_details\": [\n        {\n          \"rate_detail_type\": \"shipping\",\n          \"carrier_description\": null,\n          \"carrier_billing_code\": \"Base Rate\",\n          \"carrier_memo\": null,\n          \"amount\": {\n            \"currency\": \"usd\",\n            \"amount\": 18.49\n          },\n          \"billing_source\": \"Carrier\"\n        }\n      ],\n      \"tracking_number\": \"1Z28A1R91201009738\",\n      \"is_return_label\": false,\n      \"is_international\": false,\n      \"batch_id\": \"\",\n      \"carrier_id\": \"se-123890\",\n      \"service_code\": \"ups_3_day_select\",\n      \"package_code\": \"package\",\n      \"voided\": false,\n      \"voided_at\": null,\n      \"label_format\": \"pdf\",\n      \"label_layout\": \"4x6\",\n      \"trackable\": false,\n      \"carrier_code\": \"ups\",\n      \"tracking_status\": \"unknown\",\n      \"label_download\": {\n        \"pdf\": \"https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.pdf\",\n        \"png\": \"https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.png\",\n        \"zpl\": \"https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.zpl\",\n        \"href\": \"https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.pdf\"\n      },\n      \"form_download\": null,\n      \"insurance_claim\": null\n    }\n  ],\n  \"total\": 3820,\n  \"page\": 1,\n  \"pages\": 3820,\n  \"links\": {\n    \"first\": {\n      \"href\": \"https://api.shipengine.com/v1/labels?label_status=completed&page=1&page_size=1\"\n    },\n    \"last\": {\n      \"href\": \"https://api.shipengine.com/v1/labels?label_status=completed&page=3820&page_size=1\"\n    },\n    \"prev\": {},\n    \"next\": {\n      \"href\": \"https://api.shipengine.com/v1/labels?label_status=completed&page=2&page_size=1\"\n    }\n  }\n}\n","lang":"json"},"children":[]}]},"headings":[{"value":"List Labels","id":"list-labels","depth":1},{"value":"Query Parameters","id":"query-parameters","depth":2},{"value":"Extended Description: sort_dir","id":"extended-description-sort_dir","depth":3},{"value":"Example Request & Response","id":"example-request--response","depth":2}],"frontmatter":{"seo":{"title":"List Labels"}},"lastModified":"2026-04-08T10:47:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/shipengine/docs/reference/list-labels","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}