# 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

Endpoint: GET /v1/labels
Version: 1.1.202604070904
Security: api_key

## Query parameters:

  - `label_status` (string)
    Only return labels that are currently in the specified status
    Enum: "processing", "completed", "error", "voided"

  - `service_code` (string)
    Only return labels for a specific carrier service
    Example: "usps_first_class_mail"

  - `carrier_id` (string)
    Only return labels for a specific carrier account
    Example: "se-28529731"

  - `tracking_number` (string)
    Only return labels with a specific tracking number
    Example: "9405511899223197428490"

  - `batch_id` (string)
    Only return labels that were created in a specific batch
    Example: "se-28529731"

  - `rate_id` (string)
    Rate ID
    Example: "se-28529731"

  - `shipment_id` (string)
    Shipment ID
    Example: "se-28529731"

  - `warehouse_id` (string)
    Only return labels that originate from a specific warehouse
    Example: "se-28529731"

  - `created_at_start` (string)
    Only return labels that were created on or after a specific date/time
    Example: "2019-03-12T19:24:13.657Z"

  - `created_at_end` (string)
    Only return labels that were created on or before a specific date/time
    Example: "2019-03-12T19:24:13.657Z"

  - `refund_status` (array)
    Only return labels with specific refund status/es.
    Enum: "request_scheduled", "pending", "approved", "rejected", "excluded"

  - `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 is returned.
    Example: 2

  - `page_size` (integer)
    The number of results to return per response.
    Example: 50

  - `sort_dir` (string)
    Controls the sort order of the query.
    Enum: "asc", "desc"

  - `sort_by` (string)
    Controls which field the query is sorted by.
    Enum: "modified_at", "created_at", "voided_at"

## Response 200 fields (application/json):

  - `labels` (array, required)
    The labels that matched the query criteria.  If no matching labels were found, then this array is empty; otherwise, it contains one page of results.  The last page of results may have fewer labels than the page_size.

  - `labels.label_id` (string)
    A string that uniquely identifies the label. This ID is generated by ShipEngine when the label is created.
    Example: "se-28529731"

  - `labels.status` (string)
    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
    Enum: "processing", "completed", "error", "voided"

  - `labels.shipment_id` (string)
    The shipment that this label is for.  ShipEngine can create a shipment for you automatically when you create a label, or you can create your own shipment and then use it to print a label
    Example: "se-28529731"

  - `labels.external_shipment_id` (string,null)
    A unique user-defined key to identify a shipment.  This can be used to retrieve the shipment.

  - `labels.external_order_id` (string,null)
    ID that the Order Source assigned

  - `labels.ship_date` (string)
    The date that the package was (or will be) shipped.  ShipEngine will take the day of week into consideration. For example, if the carrier does not operate on Sundays, then a package that would have shipped on Sunday will ship on Monday instead.
    Example: "2018-09-23T00:00:00.000Z"

  - `labels.created_at` (string)
    The date and time that the label was created in ShipEngine.
    Example: "2018-09-23T15:00:00.000Z"

  - `labels.shipment_cost` (object)
    The cost of shipping, delivery confirmation, and other carrier charges.  This amount does not include insurance costs.

  - `labels.shipment_cost.currency` (string, required)
    The currencies that are supported by ShipEngine are the ones that specified by ISO 4217: https://www.iso.org/iso-4217-currency-codes.html

  - `labels.shipment_cost.amount` (number, required)
    The monetary amount, in the specified currency.

  - `labels.insurance_cost` (object)
    The insurance cost for this package.  Add this to the shipment_cost field to get the total cost.

  - `labels.requested_comparison_amount` (object)
    The total shipping cost for the specified comparison_rate_type.

  - `labels.rate_details` (array)
    A list of rate details that are associated with shipping cost. This is useful for
displaying a breakdown of the rate to the user.

  - `labels.rate_details.rate_detail_type` (string)
    The possible rate detail type values
    Enum: "uncategorized", "shipping", "insurance", "confirmation", "discount", "fuel_charge", "additional_fees", "tariff", "tax", "delivery", "handling", "special_goods", "pickup", "location_fee", "oversize", "returns", "notifications", "tip", "duties_and_taxes", "brokerage_fee", "admin_fee", "adjustment"

  - `labels.rate_details.carrier_description` (string)
    A rate detail description defined by a carrier

  - `labels.rate_details.carrier_billing_code` (string)
    A rate detail code defined by a carrier

  - `labels.rate_details.carrier_memo` (string)
    Contains any additional information

  - `labels.rate_details.amount` (object)
    A monetary value, such as the price of a shipping label, the insured value of a package, or an account balance.

  - `labels.rate_details.rate_detail_attributes` (object)
    If applicable, contains additional data about a rate detail of a specific type, e.g. VAT

  - `labels.rate_details.rate_detail_attributes.tax_type` (string)
    Type of a tax added to shipping cost
    Enum: "vat"

  - `labels.rate_details.rate_detail_attributes.tax_percentage` (number)
    Tax percentage, e.g. 20 for 20%, added to the shipping cost

  - `labels.rate_details.billing_source` (string)
    The source of the billing information. This is typically the carrier, but could be a third party, e.g insurance

  - `labels.tracking_number` (string)
    The tracking number for the package. Tracking number formats vary across carriers.
    Example: "782758401696"

  - `labels.is_return_label` (boolean)
    Indicates whether this is a return label.  You may also want to set the rma_number so you know what is being returned.

  - `labels.rma_number` (string,null)
    An optional Return Merchandise Authorization number.  This field is useful for return labels.  You can set it to any string value.

  - `labels.is_international` (boolean)
    Indicates whether this is an international shipment.  That is, the originating country and destination country are different.

  - `labels.batch_id` (string)
    If this label was created as part of a batch, then this is the unique ID of that batch.
    Example: "se-28529731"

  - `labels.carrier_id` (string)
    The unique ID of the carrier account that was used to create this label
    Example: "se-28529731"

  - `labels.charge_event` (string)
    The label charge event.
    Enum: "carrier_default", "on_creation", "on_carrier_acceptance"

  - `labels.service_code` (string)
    The carrier service used to ship the package, such as fedex_ground, usps_first_class_mail, flat_rate_envelope, etc.
    Example: "usps_first_class_mail"

  - `labels.package_code` (string)
    The package type, such as thick_envelope, small_flat_rate_box, large_package, etc.  The code package indicates a custom or unknown package type.
    Example: "small_flat_rate_box"

  - `labels.voided` (boolean)
    Indicates whether the label has been voided

  - `labels.voided_at` (string,null)
    The date and time that the label was voided, or null if the label has not been voided
    Example: "2018-09-23T15:00:00.000Z"

  - `labels.label_format` (string)
    The file format that you want the label to be in.  We recommend pdf format because it is supported by all carriers, whereas some carriers do not support the png or zpl formats.
    Enum: "pdf", "png", "zpl"

  - `labels.display_scheme` (string)
    The display format that the label should be shown in.
    Enum: "label", "paperless", "label_and_paperless"

  - `labels.label_layout` (string)
    The layout (size) that you want the label to be in.  The label_format determines which sizes are allowed.  4x6 is supported for all label formats, whereas letter (8.5" x 11") is only supported for pdf format.
    Enum: "4x6", "letter", "A4", "A6"

  - `labels.trackable` (boolean)
    Indicates whether the shipment is trackable, in which case the tracking_status field will reflect the current status and each package will have a tracking_number.

  - `labels.label_image_id` (string,null)
    The label image resource that was used to create a custom label image.
    Example: "img_DtBXupDBxREpHnwEXhTfgK"

  - `labels.carrier_code` (string)
    The shipping carrier who will ship the package, such as fedex, dhl_express, stamps_com, etc.
    Example: "dhl_express"

  - `labels.tracking_status` (string)
    The current status of the package, such as in_transit or delivered
    Enum: "unknown", "in_transit", "error", "delivered"

  - `labels.confirmation` (string)
    The type of delivery confirmation that is required for this shipment.
    Enum: "none", "delivery", "signature", "adult_signature", "direct_signature", "delivery_mailed", "verbal_confirmation", "delivery_code", "age_verification_16_plus"

  - `labels.label_download` (object)
    Reference to the various downloadable file formats for the generated label

  - `labels.label_download.href` (string)
    The URL of the linked resource, if any
    Example: "http://api.shipengine.com/v1/labels/se-28529731"

  - `labels.label_download.pdf` (string)
    The URL for the pdf generated label
    Example: "http://api.shipengine.com/v1/labels/se-28529731"

  - `labels.label_download.png` (string)
    The URL for the png generated label
    Example: "http://api.shipengine.com/v1/labels/se-28529731"

  - `labels.label_download.zpl` (string)
    The URL for the zpl generated label
    Example: "http://api.shipengine.com/v1/labels/se-28529731"

  - `labels.form_download` (object,null)
    The link to download the customs form (a.k.a. commercial invoice) for this shipment, if any.  Forms are in PDF format. This field is null if the shipment does not require a customs form, or if the carrier does not support it.

  - `labels.form_download.type` (string)
    The type of resource, or the type of relationship to the parent resource

  - `labels.qr_code_download` (object,null)
    The QR code download for the package

  - `labels.paperless_download` (object,null)
    The paperless details which may contain elements like href, instructions and handoff_code.

  - `labels.paperless_download.instructions` (string,null)
    The instructions for the paperless download.

  - `labels.paperless_download.handoff_code` (string,null)
    The handoff code for the paperless download.

  - `labels.insurance_claim` (object,null)
    The link to submit an insurance claim for the shipment.  This field is null if the shipment is not insured or if the insurance provider does not support online claim submission.

  - `labels.packages` (array)
    The label's package(s).

> Note: Some carriers only allow one package per label.  If you attempt to create a multi-package label for a carrier that doesn't allow it, an error will be returned.

  - `labels.packages.package_id` (integer)
    The shipment package id

  - `labels.packages.weight` (object, required)
    The package weight

  - `labels.packages.weight.value` (number, required)
    The weight, in the specified unit

  - `labels.packages.weight.unit` (string, required)
    The possible weight unit values
    Enum: "pound", "ounce", "gram", "kilogram"

  - `labels.packages.dimensions` (object)
    The package dimensions

  - `labels.packages.dimensions.unit` (string, required)
    The dimension units that are supported by ShipEngine.
    Enum: "inch", "centimeter"

  - `labels.packages.dimensions.length` (number, required)
    The length of the package, in the specified unit

  - `labels.packages.dimensions.width` (number, required)
    The width of the package, in the specified unit

  - `labels.packages.dimensions.height` (number, required)
    The height of the package, in the specified unit

  - `labels.packages.insured_value` (object)
    The insured value of the package.  Requires the insurance_provider field of the shipment to be set.

  - `labels.packages.tracking_number` (string)
    The tracking number for the package.  The format depends on the carrier.
    Example: "1Z932R800392060079"

  - `labels.packages.label_download` (object)
    The label download for the package

  - `labels.packages.form_download` (object)
    The form download for any customs that are needed

  - `labels.packages.label_messages` (object)
    Custom messages to print on the shipping label for the package.  These are typically used to print invoice numbers, product numbers, or other internal reference numbers.  Not all carriers support label messages. The number of lines and the maximum length of each line also varies by carrier.

|Carrier            |Max lines |Max line length
|-------------------|----------|--------------------
|USPS (Stamps.com)  |3         |60
|FedEx              |3         |35 for the first line. 30 for additional lines.
|UPS                |2         |35
|OnTrac             |2         |25

  - `labels.packages.label_messages.reference1` (string,null, required)
    The first line of the custom label message.  Some carriers may prefix this line with something like "REF", "Reference", "Trx Ref No.", etc.

  - `labels.packages.label_messages.reference2` (string,null, required)
    The second line of the custom label message.  Some carriers may prefix this line with something like "INV", "Reference 2", "Trx Ref No.", etc.

  - `labels.packages.label_messages.reference3` (string,null, required)
    The third line of the custom label message.  Some carriers may prefix this line with something like "PO", "Reference 3", etc.

  - `labels.packages.external_package_id` (string)
    An external package id.

  - `labels.packages.content_description` (string,null)
    A short description of the package content. Required for shipments moving to, from, and through Mexico.
    Example: "Hand knitted wool socks"

  - `labels.packages.sequence` (integer)
    Package sequence

  - `labels.packages.has_label_documents` (boolean)
    Whether the package has label documents available for download

  - `labels.packages.has_form_documents` (boolean)
    Whether the package has form documents available for download

  - `labels.packages.has_qr_code_documents` (boolean)
    Whether the package has QR code documents available for download

  - `labels.packages.has_paperless_label_documents` (boolean)
    Whether the package has paperless documents available for download

  - `labels.packages.alternative_identifiers` (array,null)
    Alternative identifiers associated with this package.

  - `labels.packages.alternative_identifiers.type` (string)
    The type of alternative_identifier that corresponds to the value.
    Example: "last_mile_tracking_number"

  - `labels.packages.alternative_identifiers.value` (string)
    The value of the alternative_identifier.
    Example: "12345678912345678912"

  - `labels.alternative_identifiers` (array,null)
    Additional information some carriers may provide by which to identify a given label in their system.

  - `labels.tracking_url` (string,null)
    The URL to track the package. This URL is provided by the carrier and is unique to the tracking number.
    Example: "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234"

  - `labels.ship_to` (object)
    The recipient's mailing address

  - `labels.ship_to.name` (string, required)
    The name of a contact person at this address.  This field may be set instead of - or in addition to - the company_name field.
    Example: "John Doe"

  - `labels.ship_to.phone` (string)
    The phone number of a contact person at this address.  The format of this phone number varies depending on the country.
    Example: "+1 204-253-9411 ext. 123"

  - `labels.ship_to.email` (string,null)
    Email for the address owner.
    Example: "example@example.com"

  - `labels.ship_to.company_name` (string,null)
    If this is a business address, then the company name should be specified here.
    Example: "The Home Depot"

  - `labels.ship_to.address_line1` (string, required)
    The first line of the street address.  For some addresses, this may be the only line.  Other addresses may require 2 or 3 lines.
    Example: "1999 Bishop Grandin Blvd."

  - `labels.ship_to.address_line2` (string,null)
    The second line of the street address.  For some addresses, this line may not be needed.
    Example: "Unit 408"

  - `labels.ship_to.address_line3` (string,null)
    The third line of the street address.  For some addresses, this line may not be needed.
    Example: "Building #7"

  - `labels.ship_to.city_locality` (string, required)
    The name of the city or locality
    Example: "Winnipeg"

  - `labels.ship_to.state_province` (string, required)
    The state or province.  For some countries (including the U.S.) only abbreviations are allowed.  Other countries allow the full name or abbreviation.
    Example: "Manitoba"

  - `labels.ship_to.postal_code` (string, required)
    postal code
    Example: "78756-3717"

  - `labels.ship_to.country_code` (string)
    The two-letter [ISO 3166-1 country code](https://en.wikipedia.org/wiki/ISO_3166-1)
    Example: "CA"

  - `labels.ship_to.address_residential_indicator` (string)
    Indicates whether this is a residential address.
    Enum: "unknown", "yes", "no"

  - `labels.ship_to.instructions` (string,null)
    Additional text about how to handle the shipment at this address.

  - `labels.ship_to.geolocation` (array)

  - `labels.ship_to.geolocation.type` (string)
    Enum of available type of geolocation items:
  - 'what3words' functionality allows to specify a location by providing 3 words that have been assign to the specific location see [link](https://what3words.com/business) for more details.
    Enum: "what3words"

  - `labels.ship_to.geolocation.value` (string)
    value of the geolocation item
    Example: "cats.with.thumbs"

  - `total` (integer, required)
    The total number of items across all pages of results
    Example: 2750

  - `page` (integer, 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.
    Example: 1

  - `pages` (integer, 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: 4

  - `links` (object, required)
    Helpful links to other pages of results

  - `links.first` (object, required)
    The link to the first page of results.  This object will _always_ have an href field. If there are no results, then the first page will contain an empty array of items.

  - `links.last` (object, required)
    The link to the final page of results.  This object will _always_ have an href field. If there are no results, then the final page will contain an empty array of items.

  - `links.prev` (object, required)
    The link to the previous page of results.  The href field will only be set when the page is 2 or greater.

  - `links.next` (object, required)
    The link to the next page of results.  The href field will only be set when the page is less than pages.

## Response 400 fields (application/json):

  - `request_id` (string, required)
    A UUID that uniquely identifies the request id.
This can be given to the support team to help debug non-trivial issues that may occur
    Example: "aa3d8e8e-462b-4476-9618-72db7f7b7009"

  - `errors` (array, required)
    The errors associated with the failed API call

  - `errors.error_source` (string, required)
    The source of the error, as indicated by the name this informs us if the API call failed because of the
carrier, the order source, or the ShipEngine API itself.
    Enum: "carrier", "order_source", "shipengine"

  - `errors.error_type` (string, required)
    The type of error
    Enum: "account_status", "business_rules", "validation", "security", "system", "integrations"

  - `errors.error_code` (string, required)
    The error code specified for the failed API Call
    Enum: "auto_fund_not_supported", "batch_cannot_be_modified", "carrier_conflict", "carrier_disconnected", "carrier_not_connected", "carrier_not_supported", "confirmation_not_supported", "default_warehouse_cannot_be_deleted", "field_conflict", "field_value_required", "forbidden", "identifier_conflict", "identifiers_must_match", "insufficient_funds", "invalid_address", "invalid_billing_plan", "invalid_field_value", "invalid_identifier", "invalid_status", "invalid_string_length", "label_images_not_supported", "meter_failure", "order_source_not_active", "rate_limit_exceeded", "refresh_not_supported", "request_body_required", "return_label_not_supported", "settings_not_supported", "subscription_inactive", "terms_not_accepted", "tracking_not_supported", "trial_expired", "unauthorized", "unknown", "unspecified", "verification_failure", "warehouse_conflict", "webhook_event_type_conflict", "customs_items_required", "incompatible_paired_labels", "invalid_charge_event", "invalid_object", "no_rates_returned", "file_not_found", "shipping_rule_not_found", "service_not_determined", "no_rates_returned", "funding_source_registration_in_progress", "insurance_failure", "funding_source_missing_configuration", "funding_source_error"

  - `errors.message` (string, required)
    An error message associated with the failed API call
    Example: "Body of request cannot be null."

  - `errors.carrier_id` (string)
    A string that uniquely identifies the carrier that generated the error.
    Example: "se-28529731"

  - `errors.carrier_code` (string)
    The name of the shipping carrier that generated the error, such as fedex, dhl_express, stamps_com, etc.
    Example: "dhl_express"

  - `errors.field_name` (string)
    The name of the field that caused the error
    Example: "shipment.ship_to.phone_number"

## Response 500 fields (application/json):

  - `request_id` (string, required)
    A UUID that uniquely identifies the request id.
This can be given to the support team to help debug non-trivial issues that may occur
    Example: "aa3d8e8e-462b-4476-9618-72db7f7b7009"

  - `errors` (array, required)
    The errors associated with the failed API call

  - `errors.error_source` (string, required)
    The source of the error, as indicated by the name this informs us if the API call failed because of the
carrier, the order source, or the ShipEngine API itself.
    Enum: "carrier", "order_source", "shipengine"

  - `errors.error_type` (string, required)
    The type of error
    Enum: "account_status", "business_rules", "validation", "security", "system", "integrations"

  - `errors.error_code` (string, required)
    The error code specified for the failed API Call
    Enum: "auto_fund_not_supported", "batch_cannot_be_modified", "carrier_conflict", "carrier_disconnected", "carrier_not_connected", "carrier_not_supported", "confirmation_not_supported", "default_warehouse_cannot_be_deleted", "field_conflict", "field_value_required", "forbidden", "identifier_conflict", "identifiers_must_match", "insufficient_funds", "invalid_address", "invalid_billing_plan", "invalid_field_value", "invalid_identifier", "invalid_status", "invalid_string_length", "label_images_not_supported", "meter_failure", "order_source_not_active", "rate_limit_exceeded", "refresh_not_supported", "request_body_required", "return_label_not_supported", "settings_not_supported", "subscription_inactive", "terms_not_accepted", "tracking_not_supported", "trial_expired", "unauthorized", "unknown", "unspecified", "verification_failure", "warehouse_conflict", "webhook_event_type_conflict", "customs_items_required", "incompatible_paired_labels", "invalid_charge_event", "invalid_object", "no_rates_returned", "file_not_found", "shipping_rule_not_found", "service_not_determined", "no_rates_returned", "funding_source_registration_in_progress", "insurance_failure", "funding_source_missing_configuration", "funding_source_error"

  - `errors.message` (string, required)
    An error message associated with the failed API call
    Example: "Body of request cannot be null."

  - `errors.carrier_id` (string)
    A string that uniquely identifies the carrier that generated the error.
    Example: "se-28529731"

  - `errors.carrier_code` (string)
    The name of the shipping carrier that generated the error, such as fedex, dhl_express, stamps_com, etc.
    Example: "dhl_express"

  - `errors.field_name` (string)
    The name of the field that caused the error
    Example: "shipment.ship_to.phone_number"