List labels
<aside class="access" aria-label="Endpoint access"> <table class="access__table"> <thead> <tr> <th class="access__table-header">Products</th> <th class="access__table-header">Plans</th> </tr> </thead> <tbody> <tr> <td class="access__table-cell access__product"> <img class="access__logo" src="/static/logos/shipstation-api-logo.svg" alt="ShipStation API Logo" loading="lazy" decoding="async"/> <div class="access__sub">Formerly ShipEngine</div> </td> <td class="access__table-cell access__plans"> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-free.md" class="access__plan">Free</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-advanced-enterprise.md" class="access__plan">Advanced</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-advanced-enterprise.md" class="access__plan">Enterprise</a> </td> </tr> <tr> <td class="access__table-cell"> <img class="access__logo" src="/static/logos/shipstation-logo.svg" alt="ShipStation Logo" loading="lazy" decoding="async"/> </td> <td class="access__table-cell access__plans"> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-free-starter.md" class="access__plan access__plan--off">Free</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-free-starter.md" class="access__plan access__plan--off">Starter</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-standard-premium.md" class="access__plan">Standard</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-standard-premium.md" class="access__plan">Premium</a> </td> </tr> </tbody> </table> <footer class="access__footer"> <a class="access__help" href="/apis/@shipstation-v2/docs/getting-started/products-and-plans.md"> Learn about products and plans <img src="/static/icons/external-link.svg" alt="External Link Icon" style="width: 16px;" loading="lazy" decoding="async"/> </a> </footer> </aside>This method 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. You can combine multiple filter options to narrow-down the results. For example, if you only want your UPS labels for your east coast warehouse you could query by both warehouse_id and carrier_id.
Query parameters
The possible statuses that a [shipping label] can be in.
| Status | Description |
|---|---|
| processing | When labels are created in a [batch], it may take a few minutes for all of the labels in the batch to be created. During this period, they will be in processing status. |
| completed | The label was successfully created |
| error | The label could not be created due to an error, such as an invalid delivery address |
| voided | The label has been [voided] |
Only return labels that are currently in the specified status.
A [carrier service], such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
Only return labels for a specific carrier service.
A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.
Carrier ID
The tracking number associated with a shipment
A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.
Batch ID
A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.
Rate ID
A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.
Shipment ID
Filter labels by external shipment ID.
A string that uniquely identifies a ShipStation resource, such as a carrier, label, shipment, etc.
Warehouse ID
Used to create a filter for when a resource was created (ex. A shipment that was created after a certain time)
Used to create a filter for when a resource was created, (ex. A shipment that was created before a certain time)
[ "request_scheduled" ]
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 is returned.
The number of results to return per response.
Controls the sort order of queries
| Value | Description |
|---|---|
| asc | Return results in ascending order |
| desc | Return results in descending order |
Controls the sort order of the query.
Controls which field the query is sorted by.
Response
The response includes a labels array containing a page of results (as determined by the page_size query parameter). It also includes other useful information, such as the total number of labels that match the query criteria, the number of pages of results, and the URLs of the first, last, next, and previous pages of results.
Example response
{
"total": 2750,
"page": 1,
"pages": 4,
"links": {
"first": {
"href": "https://example.com/resource",
"type": "child"
},
"last": {
"href": "https://example.com/resource",
"type": "child"
},
"prev": {
"href": "https://example.com/resource",
"type": "child"
},
"next": {
"href": "https://example.com/resource",
"type": "child"
}
}
}