> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loopreturns.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Label Requests

> Retrieve a list of label requests.

#### Required API key scope
- Label Requests (Read)




## OpenAPI

````yaml get /label-requests
openapi: 3.1.0
info:
  title: Labels API
  description: API for managing label requests
  version: v1
servers:
  - url: https://api.loopreturns.com/api/v1
security: []
tags:
  - name: Label Requests
paths:
  /label-requests:
    get:
      tags:
        - Label Requests
      summary: List Label Requests
      description: |
        Retrieve a list of label requests.

        #### Required API key scope
        - Label Requests (Read)
      operationId: list-label-requests
      parameters:
        - in: query
          name: from
          description: Returns label requests after or equal to a minimum date.
          schema:
            $ref: '#/components/schemas/Date'
        - in: query
          name: to
          description: Returns label requests before a maximum date.
          schema:
            $ref: '#/components/schemas/Date'
        - in: query
          name: return_id
          description: Return label requests associated with a specific return_id.
          schema:
            type: integer
            example: 67329889100573
        - in: query
          name: status
          schema:
            $ref: '#/components/schemas/LabelRequestStatusEnum'
        - in: query
          name: limit
          description: The per page limit of label requests to return
          schema:
            type: integer
            default: 50
            minimum: 0
            maximum: 250
        - in: query
          name: offset
          description: The number of label requests to offset.
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/LabelRequestResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - oauth2:
            - label_requests:read
        - label-requests-read: []
components:
  schemas:
    Date:
      type: string
      description: The date the label was created.
      format: date-time
      example: '2023-04-25T13:25:00-05:00'
    LabelRequestStatusEnum:
      type: string
      description: The status of the label request.
      enum:
        - issued
        - cancelled
        - fulfilled
      example: issued
    LabelRequestResponse:
      type: object
      required:
        - id
        - addresses
        - parcel
        - products
        - errors
        - return_id
        - shop_id
        - status
        - created_at
      properties:
        id:
          type: string
          description: The unique identifier for the label request, created by Loop.
          example: '67329889100573'
        addresses:
          type: object
          required:
            - origin
            - destination
          properties:
            origin:
              $ref: '#/components/schemas/Address'
            destination:
              $ref: '#/components/schemas/Address'
        parcel:
          type: object
          required:
            - height
            - length
            - width
            - weight
          properties:
            height:
              type: number
              format: double
              description: The height of the parcel in inches.
              example: 5
            length:
              type: number
              format: double
              description: The length of the parcel in inches.
              example: 20.2
            width:
              type: number
              format: double
              description: The width of the parcel in inches.
              example: 10.9
            weight:
              type: number
              format: double
              description: The weight of the parcel in grams.
              example: 65.9
        products:
          type: array
          items:
            $ref: '#/components/schemas/Product'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/LabelRequestErrorResponse'
        return_id:
          type: integer
          format: int64
          description: The return id of the return.
          example: 1001
        shop_id:
          type: integer
          format: int64
          description: The id of the shop belonging to the merchant.
          example: 50
        status:
          $ref: '#/components/schemas/LabelRequestStatusEnum'
        created_at:
          $ref: '#/components/schemas/Date'
    Address:
      type: object
      properties:
        name:
          type:
            - string
            - 'null'
          maxLength: 100
          description: The recipient's name.
        company:
          type:
            - string
            - 'null'
          maxLength: 100
          description: The recipient's company.
        address1:
          type: string
          maxLength: 125
          description: The recipient's street address.
        address2:
          type:
            - string
            - 'null'
          maxLength: 125
          description: >-
            The recipient's secondary address details (such as unit number or PO
            box information).
        city:
          type: string
          maxLength: 100
          description: The city in which the address is located.
        state:
          type:
            - string
            - 'null'
          maxLength: 100
          description: The state or region in which the address is located.
        zip:
          type: string
          maxLength: 16
          description: The postal code associated with the address.
        country:
          type: string
          maxLength: 100
          description: The country in which the address is located.
        country_code:
          type: string
          maxLength: 2
          description: The two-letter country code associated with the address.
        phone:
          type:
            - string
            - 'null'
          description: The phone number associated with the address.
      required:
        - address1
        - city
        - zip
        - country
        - country_code
      example:
        name: John Smith
        company: Acme, Co
        address1: 123 Example St
        address2: Box 123
        city: Columbus
        state: OH
        zip: '12345'
        country: United States of America
        country_code: US
        phone: +1 555-555-5555
    Product:
      type: object
      required:
        - name
        - sku
        - price
      properties:
        name:
          type: string
          description: The name of the product.
          example: Product Name
        price:
          $ref: '#/components/schemas/MoneySet'
        country_of_origin:
          type:
            - string
            - 'null'
          description: The country of origin of the product.
          example: USA
        hs_code:
          type:
            - string
            - 'null'
          description: The HS (Harmonized System) code of the product.
          example: '61051000'
        sku:
          type: string
          description: The SKU of the product.
          example: '99999999'
    LabelRequestErrorResponse:
      type: object
      required:
        - reason
      properties:
        reason:
          $ref: '#/components/schemas/ErrorReasonEnum'
          description: The reason code associated with the label request error.
        message:
          type:
            - string
            - 'null'
          description: The message associated with the label request error.
          example: Failed to generate a label, the origin address is invalid
        created_at:
          $ref: '#/components/schemas/Date'
    MoneySet:
      type: object
      example:
        - amount: 50000
          currency: USD
        - amount: 25000
          currency: CAD
        - amount: 1500
          currency: EUR
      properties:
        amount:
          type: integer
          format: int32
          description: The amount represented in cents.
          example: 25000
        currency:
          type:
            - string
          default: USD
          example: EUR
          description: The 3 character (ISO 4217) currency code.
      required:
        - amount
        - currency
    ErrorReasonEnum:
      type: string
      description: The error reason.
      enum:
        - INSUFFICIENT_FUNDS
        - INVALID_ADDRESS
        - Other
      example: INVALID_ADDRESS
  responses:
    Unauthorized:
      description: The request could not be authorized.
      content:
        application/json:
          schema:
            type: object
            required:
              - errors
            properties:
              errors:
                type: string
                example: Unauthorized.
    NotFound:
      description: The requested entity could not be found.
      content:
        application/json:
          schema:
            type: object
            required:
              - message
            properties:
              message:
                type: string
                example: Resource not found.
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://oauth.loopreturns.com/authorize
          tokenUrl: https://oauth.loopreturns.com/oauth/token
          scopes:
            labels:read: Read access to labels
            labels:write: Create and modify labels
            label_requests:read: Read access to label requests
            label_requests:write: Create and modify label requests
            returns: Access to returns operations
    label-requests-read:
      type: apiKey
      in: header
      name: X-Authorization
      description: 'API Scope: "Label Requests (read)"'
      x-scope: Label Requests (Read)

````