v1

latestOpenAPI 3.0.02026-07-1397337495.2 KB

labels

List labels

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

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

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": "http://api.shipengine.com/v1/labels/se-28529731"
    },
    "last": {
      "href": "http://api.shipengine.com/v1/labels/se-28529731"
    },
    "prev": {
      "href": "http://api.shipengine.com/v1/labels/se-28529731"
    },
    "next": {
      "href": "http://api.shipengine.com/v1/labels/se-28529731"
    }
  }
}