labels

List labels

Changed on Oct 22, 2026

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. You can combine multiple filter options to narrow-down the results. For example, if you only want to get your UPS labels for your east coast warehouse you could query by both warehouse_id and carrier_id

get/v1/labels

Request

Base URL: https://api.shipengine.com
URL: https://api.shipengine.com/v1/labels
Auth: API key in header API-Key

Query parameters

label_status'processing' | 'completed' | 'error' | 'voided'

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

service_codestring

A carrier service, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.

Example:usps_first_class_mail

Only return labels for a specific carrier service

carrier_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

Example:se-28529731

Only return labels for a specific carrier account

tracking_numberstring

Only return labels with a specific tracking number

batch_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

Example:se-28529731

Only return labels that were created in a specific batch

rate_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

Example:se-28529731

Rate ID

shipment_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

Example:se-28529731

Shipment ID

external_shipment_idstring

Only return labels for a specific external shipment ID.

warehouse_idstring

A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.

Example:se-28529731

Only return labels that originate from a specific warehouse

created_at_startstring date-time

Only return labels that were created on or after a specific date/time

created_at_endstring date-time

Only return labels that were created on or before a specific date/time

refund_statusstring[]

Only return labels with specific refund status/es.

pageinteger

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.

page_sizeinteger

The number of results to return per response.

sort_dir'asc' | 'desc'

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.

sort_by'modified_at' | 'created_at' | 'voided_at'

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.

totalinteger required

The total number of items across all pages of results

pageinteger required

The current page number of results. For example, if there are 80 results, and the page size is 25, then page could be 1, 2, 3, or 4. The first three pages would contain 25 items each, and the fourth page would contain the five remaining items.

pagesinteger required

The total number of pages of results. For example, if there are 80 results, and the page size is 25, then pages would be 4. The first three pages would contain 25 items each, and the fourth page would contain the five remaining items. If there are no results, then pages will be zero.

Example response

{
  "total": 2750,
  "page": 1,
  "pages": 4,
  "links": {
    "first": {
      "href": "https://example.com/resource"
    },
    "last": {
      "href": "https://example.com/resource"
    },
    "prev": {
      "href": "https://example.com/resource"
    },
    "next": {
      "href": "https://example.com/resource"
    }
  }
}

Changes

Oct 22, 2026e998dffc42be Revision changes
- warning
  added the new bring_your_own_label_not_supported enum value to the // response property for the response status
- warning
  added the new bring_your_own_label_not_supported enum value to the // response property for the response status
- warning
  added the new multiple_sales_orders enum value to the // response property for the response status
- warning
  added the new multiple_sales_orders enum value to the // response property for the response status
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
- info
  added the optional property /////// to the response with the status
- info
  added subschema #2: shipment_sales_order_fields to the /// response property allOf list for the response status
Oct 9, 2026020f57d6f5b8 Revision changes
- breaking
  the / response's property type changed from no type to object for status
- breaking
  the / response's property type changed from no type to object for status
- breaking
  the / response's property type changed from no type to object for status
- breaking
  the //// response's property type changed from no type to string for status
- breaking
  the /////// response's property type changed from no type to string for status
- breaking
  the ///// response's property type changed from no type to object for status
- breaking
  the /////// response's property type changed from no type to string for status
- breaking
  the /// response's property type changed from no type to object for status
- breaking
  the //// response's property type changed from no type to string for status
- breaking
  the ////// response's property type changed from no type to string for status
- breaking
  the ///////// response's property type changed from no type to string for status
- breaking
  the //////// response's property type changed from no type to string for status
- breaking
  the ///////// response's property type changed from no type to string for status
- breaking
  the ////// response's property type changed from no type to string for status
- breaking
  the /////////// response's property type changed from no type to string for status
- breaking
  the /////// response's property type changed from no type to object for status
- breaking
  the /////// response's property type changed from no type to object for status
- breaking
  the ////// response's property type changed from no type to object for status
- breaking
  the ///// response's property type changed from no type to string for status
- breaking
  the ////// response's property type changed from no type to object for status
- breaking
  the ///////// response's property type changed from no type to string for status
- breaking
  the ///////// response's property type changed from no type to string for status
- breaking
  the ///////// response's property type changed from no type to string for status
- breaking
  the ////// response's property type changed from no type to object for status
- breaking
  the ////// response's property type changed from no type to object for status
- breaking
  the /////// response's property type changed from no type to string for status
- breaking
  the //// response's property type changed from no type to string for status
- warning
  added the new amazon_ca enum value to the ///// response property for the response status
- warning
  added the new amazon_us enum value to the ///// response property for the response status
- warning
  added the new any enum value to the //////// response property for the response status
- warning
  added the new brightpearl enum value to the ///// response property for the response status
- warning
  added the new cash enum value to the //////// response property for the response status
- warning
  added the new cash_equivalent enum value to the //////// response property for the response status
- warning
  added the new channel_advisor enum value to the ///// response property for the response status
- warning
  added the new cratejoy enum value to the ///// response property for the response status
- warning
  added the new ebay enum value to the ///// response property for the response status
- warning
  added the new etsy enum value to the ///// response property for the response status
- warning
  added the new gram enum value to the /////// response property for the response status
- warning
  added the new gram enum value to the ///////// response property for the response status
- warning
  added the new gram enum value to the /////////// response property for the response status
- warning
  added the new gram enum value to the /////// response property for the response status
- warning
  added the new groupon_goods enum value to the ///// response property for the response status
- warning
  added the new jane enum value to the ///// response property for the response status
- warning
  added the new kilogram enum value to the /////// response property for the response status
- warning
  added the new kilogram enum value to the ///////// response property for the response status
- warning
  added the new kilogram enum value to the /////////// response property for the response status
- warning
  added the new kilogram enum value to the /////// response property for the response status
- warning
  added the new magento enum value to the ///// response property for the response status
- warning
  added the new none enum value to the //////// response property for the response status
- warning
  added the new ounce enum value to the /////// response property for the response status
- warning
  added the new ounce enum value to the ///////// response property for the response status
- warning
  added the new ounce enum value to the /////////// response property for the response status
- warning
  added the new ounce enum value to the /////// response property for the response status
- warning
  added the new paypal enum value to the ///// response property for the response status
- warning
  added the new pound enum value to the /////// response property for the response status
- warning
  added the new pound enum value to the ///////// response property for the response status
- warning
  added the new pound enum value to the /////////// response property for the response status
- warning
  added the new pound enum value to the /////// response property for the response status
- warning
  added the new seller_active enum value to the ///// response property for the response status
- warning
  added the new shopify enum value to the ///// response property for the response status
- warning
  added the new squarespace enum value to the ///// response property for the response status
- warning
  added the new stitch_labs enum value to the ///// response property for the response status
- warning
  added the new three_dcart enum value to the ///// response property for the response status
- warning
  added the new tophatter enum value to the ///// response property for the response status
- warning
  added the new volusion enum value to the ///// response property for the response status
- warning
  added the new walmart enum value to the ///// response property for the response status
- warning
  added the new woo_commerce enum value to the ///// response property for the response status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //// to the response with the status
- info
  added the optional property //////// to the response with the status
- info
  added the optional property //////// to the response with the status
- info
  added the optional property //////// to the response with the status
- info
  added the optional property //////// to the response with the status
- info
  added the optional property //////// to the response with the status
- info
  added the optional property //////// to the response with the status
- info
  added the optional property //////// to the response with the status
- info
  added the optional property //////// to the response with the status
- info
  added the optional property //////// to the response with the status
- info
  added the optional property //////// to the response with the status
- info
  added the optional property //////// to the response with the status
- info
  added the optional property //////// to the response with the status
- info
  added the optional property //////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  added the optional property /////// to the response with the status
- info
  removed from the //////// response property allOf list for the response status
- info
  removed from the //// response property allOf list for the response status
- info
  removed from the /////// response property allOf list for the response status
- info
  removed from the //// response property allOf list for the response status
- info
  removed from the ///////// response property allOf list for the response status
- info
  removed from the //// response property allOf list for the response status
- info
  removed from the / response property allOf list for the response status
- info
  removed from the / response property allOf list for the response status
- info
  removed from the /////// response property allOf list for the response status
- info
  removed from the /////// response property allOf list for the response status
- info
  removed from the ///// response property allOf list for the response status
- info
  removed from the ///// response property allOf list for the response status
- info
  removed from the ////// response property allOf list for the response status
- info
  removed from the / response property allOf list for the response status
- info
  removed from the ////// response property allOf list for the response status
- info
  removed from the ///////// response property allOf list for the response status
- info
  removed from the ///////// response property allOf list for the response status
- info
  removed from the ///////// response property allOf list for the response status
- info
  removed from the /// response property allOf list for the response status
- info
  removed from the ////// response property allOf list for the response status
- info
  removed from the ////// response property allOf list for the response status
- info
  removed from the ////// response property allOf list for the response status
- info
  removed from the ////// response property allOf list for the response status
- info
  removed from the /////// response property allOf list for the response status
- info
  removed from the ///////// response property allOf list for the response status
- info
  removed from the /////////// response property allOf list for the response status
- info
  removed from the /////// response property allOf list for the response status
- info
  the ////// response's property pattern ^se(-[a-z0-9]+)+$ was added for the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property ////// to the response with the status
- info
  added the required property ////// to the response with the status
- info
  added the required property ////// to the response with the status
- info
  added the required property //////// to the response with the status
- info
  added the required property //////// to the response with the status
- info
  added the required property //////// to the response with the status
- info
  added the required property //////// to the response with the status
- info
  added the required property //////// to the response with the status
- info
  added the required property /////// to the response with the status
- info
  added the required property /////// to the response with the status
- info
  added the required property /////// to the response with the status
- info
  added the required property /////// to the response with the status
- info
  added the required property /////// to the response with the status
- info
  added the required property /////// to the response with the status

Operation history (11 revisions)