action shipengine_list_labels {
  label: "List labels"
  description: "This endpoint returns a list of labels that you've [created](https://www.shipengine.com/docs/labels/create-a-label/). You can optionally filter the results as well as control their sort order and the number of results returned at a time.\n\nBy 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`\n"
  provider: shipengine
  method: GET
  path: "/v1/labels"
  encoding: json
  input: {
    type: "object"
    properties: {
      batch_id: {
        type: "string"
        description: "A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc."
      }
      carrier_id: {
        type: "string"
        description: "A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc."
      }
      created_at_end: {
        type: "string"
        format: "date-time"
      }
      created_at_start: {
        type: "string"
        format: "date-time"
      }
      label_status: {
        type: "string"
        description: "The possible statuses that a [shipping label](https://www.shipengine.com/docs/labels/create-a-label/) can be in.\n\n|Status       |Description\n|:------------|:-----------------------------------------------------\n|`processing` |When labels are created in a [batch](https://www.shipengine.com/docs/labels/bulk/), 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.\n|`completed`  |The label was successfully created\n|`error`      |The label could not be created due to an error, such as an invalid delivery address\n|`voided`     |The label has been [voided](https://www.shipengine.com/docs/labels/voiding/)\n"
        enum: ["processing", "completed", "error", "voided"]
      }
      page: {
        type: "integer"
        format: "int32"
      }
      page_size: {
        type: "integer"
        format: "int32"
      }
      rate_id: {
        type: "string"
        description: "A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc."
      }
      service_code: {
        type: "string"
        description: "A [carrier service](https://www.shipengine.com/docs/shipping/use-a-carrier-service/), such as `fedex_ground`, `usps_first_class_mail`, `flat_rate_envelope`, etc.\n"
      }
      shipment_id: {
        type: "string"
        description: "A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc."
      }
      sort_by: {
        type: "string"
        enum: ["modified_at", "created_at"]
      }
      sort_dir: {
        type: "object"
      }
      tracking_number: {
        type: "string"
      }
      warehouse_id: {
        type: "string"
        description: "A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc."
      }
    }
    additionalProperties: false
  }
  output: {
    type: "object"
    description: "A list label response body"
    required: ["labels"]
    properties: {
      labels: {
        type: "array"
        description: "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`.\n"
        items: {
          type: "object"
          description: "A label represents the physical sticker that you affix to a package to ship it.  ShipEngine makes it easy for you to [create labels](https://www.shipengine.com/docs/labels/create-a-label/) and then download them in PDF, PNG, or ZPL format so you can print them.\n"
          properties: {
            alternative_identifiers: {
              type: "array"
              description: "Additional information some carriers may provide by which to identify a given label in their system. \n"
              items: {
                type: "object"
                description: "Additional information some carriers may provide by which to identify a given label in their system. \n"
                properties: {
                  type: {
                    type: "string"
                    description: "The type of alternative_identifier that corresponds to the value.\n"
                  }
                  value: {
                    type: "string"
                    description: "The value of the alternative_identifier.\n"
                  }
                }
                additionalProperties: false
              }
            }
            batch_id: {
              description: "If this label was created as part of a [batch](https://www.shipengine.com/docs/labels/bulk/), then this is the unique ID of that batch.\n"
              type: "object"
            }
            carrier_code: {
              description: "The [shipping carrier](https://www.shipengine.com/docs/carriers/setup/) who will ship the package, such as `fedex`, `dhl_express`, `stamps_com`, etc.\n"
              type: "object"
            }
            carrier_id: {
              description: "The unique ID of the [carrier account](https://www.shipengine.com/docs/carriers/setup/) that was used to create this label\n"
              type: "object"
            }
            charge_event: {
              description: "The label charge event.\n"
              type: "object"
            }
            created_at: {
              description: "The date and time that the label was created in ShipEngine."
              type: "object"
            }
            display_scheme: {
              description: "The display format that the label should be shown in."
              type: "object"
            }
            form_download: {
              description: "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.\n"
              type: "object"
            }
            insurance_claim: {
              description: "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.\n"
              type: "object"
            }
            insurance_cost: {
              description: "The insurance cost for this package.  Add this to the `shipment_cost` field to get the total cost.\n"
              type: "object"
            }
            is_international: {
              type: "boolean"
              description: "Indicates whether this is an international shipment.  That is, the originating country and destination country are different.\n"
            }
            is_return_label: {
              type: "boolean"
              description: "Indicates whether this is a return label.  You may also want to set the `rma_number` so you know what is being returned.\n"
            }
            label_download: {
              type: "object"
            }
            label_download_type: {
              type: "object"
            }
            label_format: {
              description: "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.\n"
              type: "object"
            }
            label_id: {
              description: "A string that uniquely identifies the label. This ID is generated by ShipEngine when the label is created.\n"
              type: "object"
            }
            label_image_id: {
              description: "The label image resource that was used to create a custom label image."
              type: "object"
            }
            label_layout: {
              description: "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.\n"
              type: "object"
            }
            outbound_label_id: {
              description: "The `label_id` of the original (outgoing) label that the return label is for. This associates the two labels together, which is\nrequired by some carriers.\n"
              type: "object"
            }
            package_code: {
              description: "The [package type](https://www.shipengine.com/docs/reference/list-carrier-packages/), such as `thick_envelope`, `small_flat_rate_box`, `large_package`, etc.  The code `package` indicates a custom or unknown package type.\n"
              type: "object"
            }
            packages: {
              type: "array"
              description: "The label's package(s).\n\n> **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.\n"
              items: {
                type: "object"
                description: "A package associated with a [shipping label](https://www.shipengine.com/docs/labels/create-a-label/)\n"
                required: ["weight"]
                properties: {
                  content_description: {
                    type: "string"
                    description: "A short description of the package content. Required for shipments moving to, from, and through Mexico.\n"
                  }
                  dimensions: {
                    description: "The package dimensions"
                    type: "object"
                  }
                  external_package_id: {
                    type: "string"
                    description: "An external package id."
                  }
                  form_download: {
                    description: "The form download for any customs that are needed"
                    type: "object"
                  }
                  insured_value: {
                    description: "The insured value of the package.  Requires the `insurance_provider` field of the shipment to be set.\n"
                    type: "object"
                  }
                  label_download: {
                    description: "The label download for the package"
                    type: "object"
                  }
                  label_messages: {
                    type: "object"
                  }
                  package_code: {
                    description: "The [package type](https://www.shipengine.com/docs/reference/list-carrier-packages/), such as `thick_envelope`, `small_flat_rate_box`, `large_package`, etc.  The code `package` indicates a custom or unknown package type.\n"
                    type: "object"
                  }
                  package_id: {
                    description: "A string that uniquely identifies this [package type](https://www.shipengine.com/docs/reference/list-carrier-packages/)"
                    type: "object"
                  }
                  sequence: {
                    type: "integer"
                    format: "int32"
                    description: "Package sequence"
                  }
                  tracking_number: {
                    description: "The tracking number for the package.  The format depends on the carrier.\n"
                    type: "object"
                  }
                  weight: {
                    description: "The package weight"
                    type: "object"
                  }
                }
                additionalProperties: false
              }
            }
            rma_number: {
              type: "string"
              description: "An optional Return Merchandise Authorization number.  This field is useful for return labels.  You can set it to any string value.\n"
            }
            service_code: {
              description: "The [carrier service](https://www.shipengine.com/docs/shipping/use-a-carrier-service/) used to ship the package, such as `fedex_ground`, `usps_first_class_mail`, `flat_rate_envelope`, etc.\n"
              type: "object"
            }
            ship_date: {
              description: "The date that the package was (or will be) shippped.  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.\n"
              type: "object"
            }
            shipment: {
              description: "The shipment information used to generate the label"
              type: "object"
            }
            shipment_cost: {
              description: "The cost of shipping, delivery confirmation, and other carrier charges.  This amount **does not** include insurance costs.\n"
              type: "object"
            }
            shipment_id: {
              description: "The shipment that this label is for.  ShipEngine can create a shipment for you automatically when you [create a label](https://www.shipengine.com/docs/labels/create-a-label/), or you can [create your own shipment](https://www.shipengine.com/docs/shipping/create-a-shipment/) and then [use it to print a label](https://www.shipengine.com/docs/labels/create-from-shipment/)\n"
              type: "object"
            }
            status: {
              type: "object"
            }
            test_label: {
              type: "boolean"
              description: "Indicate if this label is being used only for testing purposes. If true, then no charge will be added to your account."
            }
            trackable: {
              type: "boolean"
              description: "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`.\n"
            }
            tracking_number: {
              type: "string"
              description: "The tracking number for the package. Tracking number formats vary across carriers."
            }
            tracking_status: {
              description: "The current status of the package, such as `in_transit` or `delivered`"
              type: "object"
            }
            validate_address: {
              type: "object"
            }
            voided: {
              type: "boolean"
              description: "Indicates whether the label has been [voided](https://www.shipengine.com/docs/labels/voiding/)\n"
            }
            voided_at: {
              description: "The date and time that the label was [voided](https://www.shipengine.com/docs/labels/voiding/), or `null` if the label has not been voided\n"
              type: "object"
            }
          }
          additionalProperties: false
        }
      }
    }
    additionalProperties: false
  }
}