> ## 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.

# Detailed Returns List

> Pull a detailed list of returns created within a given timeframe.

This endpoint supports pagination. We _highly_
encourage using [pagination](https://docs.loopreturns.com/reference/paginated-requests)
for this endpoint. Read the guide on
[paginating requests](https://docs.loopreturns.com/reference/paginated-requests)
for details.

**Note**: If neither `from` nor `to` is passed,
the response defaults to only contain returns from the previous 24
hours. See [`from`](#parameter-from) and [`to`](#parameter-to) below for more information.

**Note**: The maximum number of days in the range of the from and to properties is 120 days.
If the number of days
in this range exceeds 120 days, a validation error will be returned.

**Note**: If no `state` is passed, the response defaults to only contain open, closed, and expired returns. See
[`state`](#parameter-state) below for more information.

### Required API key scope
- Returns




## OpenAPI

````yaml get /warehouse/return/list
openapi: 3.1.0
info:
  title: Returns API
  version: v1
  description: API used for performing operations on returns.
servers:
  - url: https://api.loopreturns.com/api/v1
security: []
tags:
  - name: Return Actions
  - name: Return Data
paths:
  /warehouse/return/list:
    get:
      tags:
        - Return Data
      summary: Detailed Returns List
      description: >
        Pull a detailed list of returns created within a given timeframe.


        This endpoint supports pagination. We _highly_

        encourage using
        [pagination](https://docs.loopreturns.com/reference/paginated-requests)

        for this endpoint. Read the guide on

        [paginating
        requests](https://docs.loopreturns.com/reference/paginated-requests)

        for details.


        **Note**: If neither `from` nor `to` is passed,

        the response defaults to only contain returns from the previous 24

        hours. See [`from`](#parameter-from) and [`to`](#parameter-to) below for
        more information.


        **Note**: The maximum number of days in the range of the from and to
        properties is 120 days.

        If the number of days

        in this range exceeds 120 days, a validation error will be returned.


        **Note**: If no `state` is passed, the response defaults to only contain
        open, closed, and expired returns. See

        [`state`](#parameter-state) below for more information.


        ### Required API key scope

        - Returns
      operationId: getDetailedReturnsList
      parameters:
        - name: from
          example: yyyy-mm-dd hh:mm:ss
          in: query
          description: >
            The start date and time for the returns list. If `from` is passed
            without `to`, returns created in the 24 hours after `from` are
            returned.
          schema:
            type: string
            examples:
              - '2022-01-01T00:00:00.000Z'
        - name: to
          example: yyyy-mm-dd hh:mm:ss
          in: query
          description: >
            The end date and time for the returns list. If `to` is provided
            without `from`, the parameter is ignored and returns from the last
            24 hours are returned.
          schema:
            type: string
            examples:
              - '2022-03-31T23:59:59.000Z'
        - name: filter
          in: query
          description: |
            The date used to filter results.
          schema:
            type: string
            enum:
              - created_at
              - updated_at
            default: created_at
        - name: state
          example: open
          in: query
          description: >
            The keywords used to filter the list to only include returns in a
            particular state.

            Defaults to only contain open, closed, and expired returns.
          schema:
            type: string
            enum:
              - open
              - closed
              - cancelled
              - expired
              - review
        - name: paginate
          in: query
          description: >
            When present, enables cursor-based pagination. The response is then
            wrapped in an object

            containing `returns` plus `nextPageUrl`/`previousPageUrl`, rather
            than a bare array.
          schema:
            type: boolean
        - name: pageSize
          in: query
          description: The number of returns to return per page when paginating.
          schema:
            type: integer
        - name: cursor
          in: query
          description: The cursor identifying the page to return when paginating.
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/DetailedReturnList'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableReturnListRequest'
      security:
        - api_key: []
components:
  responses:
    DetailedReturnList:
      description: Success
      content:
        application/json:
          schema:
            oneOf:
              - type: array
                items:
                  $ref: '#/components/schemas/DetailedReturnList'
              - type: object
                description: Returned when the `paginate` query parameter is present.
                properties:
                  returns:
                    type: array
                    items:
                      $ref: '#/components/schemas/DetailedReturnList'
                  nextPageUrl:
                    type:
                      - string
                      - 'null'
                  previousPageUrl:
                    type:
                      - string
                      - 'null'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: object
                properties:
                  code:
                    type: string
                    examples:
                      - '401'
                  http_code:
                    type: string
                    examples:
                      - GEN-UNAUTHORIZED
                  message:
                    type: string
                    examples:
                      - Unauthorized.
    UnprocessableReturnListRequest:
      description: Unprocessable
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/InvalidFromDate'
              - $ref: '#/components/schemas/InvalidToDate'
              - $ref: '#/components/schemas/InvalidState'
  schemas:
    DetailedReturnList:
      type: object
      properties:
        id:
          type: string
          examples:
            - '12345678'
          description: The unique identifier associated with the return.
        state:
          type: string
          examples:
            - open
          description: The current state of the return.
        created_at:
          type: string
          format: date-time
          examples:
            - '2023-01-01T22:27:15.000Z'
          description: >-
            The date and time at which the return was created, using the ISO
            8601 date format.
        updated_at:
          type: string
          format: date-time
          examples:
            - '2023-01-01T22:27:18.000Z'
          description: >-
            The date and time at which the return was last updated, using the
            ISO 8601 date format.
        edited_at:
          type: string
          format: date-time
          examples:
            - '2023-01-03T22:34:17.000Z'
          description: >-
            The date and time at which the return was last edited, using the ISO
            8601 date format.
        total:
          type: string
          examples:
            - '63.30'
          description: The total cost of the return.
        outcome:
          $ref: '#/components/schemas/ReturnOutcome'
          description: >-
            The outcome of the return as limited by the merchant and as selected
            by the customer.
        order_id:
          type: string
          examples:
            - '98766312'
          description: The Loop order identifier associated with the return.
        order_name:
          type: string
          examples:
            - '#7382018'
          description: The order name.
        provider_order_id:
          type: string
          examples:
            - '3248923479283'
          description: The Shopify order ID.
        order_number:
          type: string
          examples:
            - '7381018'
          description: The order number.
        provider_order_number:
          type: string
          examples:
            - '7382018'
          description: The Shopify order number.
        customer:
          type:
            - string
            - 'null'
          examples:
            - example@example.com
          description: The customer's email address.
        origin_country:
          type:
            - string
            - 'null'
          examples:
            - United States
          description: The country of the customer's shipping address.
        origin_country_code:
          type:
            - string
            - 'null'
          examples:
            - US
          description: >-
            The ISO 3166-1 alpha-2 country code of the customer's shipping
            address.
        multi_currency:
          examples:
            - false
          description: >
            Whether the order was placed through Shopify Payments in some
            currency other than the default store

            currency.
        currency:
          type: string
          examples:
            - USD
          description: The currency code of the store's default currency.
        return_product_total:
          type: string
          examples:
            - '156.00'
          description: The gross value of the returning items before discounts and tax.
        return_discount_total:
          type: string
          examples:
            - '0.00'
          description: The total value of the discounts on the returning items.
        return_tax_total:
          type: string
          examples:
            - '8.58'
          description: The total value of the taxes on the returning items.
        return_total:
          type: string
          examples:
            - '164.58'
          description: The net value of the returning items after discounts and tax.
        refund_shipping_total:
          type: string
          examples:
            - '4.00'
          description: >-
            Total original-order shipping reimbursement folded into the refund
            (the sum of each line item's `refund_shipping`).
        refund_shipping_tax_total:
          type: string
          examples:
            - '0.40'
          description: >-
            The tax portion of the reimbursed shipping folded into the refund
            (the sum of each line item's `refund_shipping_tax`).
        return_credit_total:
          type: string
          examples:
            - '101.28'
          description: >-
            The value of the returning items credited to the shopper after the
            refund has been issued.
        exchange_product_total:
          type: string
          examples:
            - '96.00'
          description: The gross value of the exchange before discounts and tax.
        exchange_discount_total:
          type: string
          examples:
            - '0.00'
          description: The total value of discounts on the exchange.
        exchange_tax_total:
          type: string
          examples:
            - '5.28'
          description: The total value of the taxes on the exchange.
        exchange_total:
          type: string
          examples:
            - '101.28'
          description: The net value of the exchanges after discounts and tax.
        exchange_credit_total:
          type: string
          examples:
            - '101.28'
          description: The value of the return credit used by the shopper.
        gift_card:
          type: string
          examples:
            - '0.00'
          description: The value of the gift card issued in the return.
        gift_card_order_name:
          type:
            - string
            - 'null'
          examples:
            - Gift Card Name
          description: The name of the gift card order issued in the return.
        gift_card_order_id:
          type:
            - string
            - 'null'
          examples:
            - '23141001200513'
          description: The unique identifier of the gift card issued in the return.
        handling_fee:
          type: string
          examples:
            - '0.00'
          description: The handling fee charged by the merchant.
        refund:
          type: string
          examples:
            - '63.30'
          description: The amount refunded in the return.
        upsell:
          type: string
          examples:
            - '0.00'
          description: The upsell amount associated with the return.
        line_items:
          $ref: '#/components/schemas/LineItem'
        exchanges:
          $ref: '#/components/schemas/Exchange'
        carrier:
          type: string
          examples:
            - N/A
          description: The carrier associated with the return.
        tracking_number:
          type: string
          examples:
            - N/A
          description: The return's tracking number.
        label_status:
          type: string
          examples:
            - N/A
          description: The status of the return shipping label.
        label_url:
          type:
            - string
            - 'null'
          examples:
            - http://example.label.url
          description: The link to the shipping label details.
        label_rate:
          type:
            - string
            - 'null'
          description: The shipping rate paid for the return label.
        status_page_url:
          type: string
          examples:
            - https://example.loopreturns.com/#/return/{uuid}
          description: >-
            The link to the Loop return tracking status page associated with the
            return.
        label_updated_at:
          type: string
          format: date-time
          examples:
            - N/A
          description: >-
            The date and time at which the label was last updated, using the ISO
            8601 date format.
        destination_id:
          type:
            - string
            - 'null'
          examples:
            - '67896541368765'
          description: >-
            The unique identifier associated with the shipping destination of
            the return.
        return_method:
          $ref: '#/components/schemas/ReturnMethod'
        package_reference:
          type:
            - string
            - 'null'
          description: The data used to look up package data in WMS software.
        type:
          $ref: '#/components/schemas/Type'
          description: The type of return submission.
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
    InvalidFromDate:
      type: object
      properties:
        message:
          type: string
          examples:
            - The `from attribute has an invalid date format.
        errors:
          type: object
          properties:
            from:
              type: array
              items:
                type: string
                examples:
                  - The `from` attribute has an invalid date format.
    InvalidToDate:
      type: object
      properties:
        message:
          type: string
          examples:
            - The `to` attribute has an invalid date format.
        errors:
          type: object
          properties:
            from:
              type: array
              items:
                type: string
                examples:
                  - The `to` attribute has an invalid date format.
    InvalidState:
      type: object
      properties:
        message:
          type: string
          examples:
            - The selected state is invalid.
        errors:
          type: object
          properties:
            from:
              type: array
              items:
                type: string
                examples:
                  - The selected state is invalid.
    ReturnOutcome:
      type: string
      enum:
        - exchange
        - upsell
        - refund
        - credit
        - exchange+refund
        - exchange+credit
    LineItem:
      type: array
      items:
        type: object
        properties:
          line_item_id:
            type: string
            examples:
              - '293482039'
            description: The unique identifier associated with the line item.
          provider_line_item_id:
            type: string
            examples:
              - '23984238720'
            description: >-
              The Shopify or other platform identifier associated with the line
              item.
          product_id:
            type: string
            examples:
              - '29871298310292'
            description: The unique identifier associated with the product.
          variant_id:
            type: string
            examples:
              - '23498287203948'
            description: The unique identifier associated with the product variant.
          sku:
            type: string
            examples:
              - 2039473-Y
            description: The SKU associated with the product.
          title:
            type: string
            examples:
              - Black Striped Shirt
            description: The product's name.
          price:
            type: string
            examples:
              - '78.00'
            description: The product's price.
          discount:
            type: string
            examples:
              - '0.00'
            description: The discount amount associated with the line item.
          tax:
            type: string
            examples:
              - '4.29'
            description: The tax amount associated with the line item.
          refund:
            type: string
            examples:
              - '31.65'
            description: The refund amount associated with the line item.
          refund_item:
            type: string
            examples:
              - '27.36'
            description: The refund amount minus the tax amount.
          refund_tax:
            type: string
            examples:
              - '4.29'
            description: Equal to the refund.
          refund_shipping:
            type: string
            examples:
              - '4.00'
            description: >-
              This line's share of the original-order shipping reimbursement
              folded into `refund`.
          refund_excluding_shipping:
            type: string
            examples:
              - '27.65'
            description: >-
              This line's `refund` with shipping removed (`refund` minus
              `refund_shipping`).
          refund_shipping_tax:
            type: string
            examples:
              - '0.40'
            description: The tax portion of `refund_shipping`.
          refund_excluding_shipping_tax:
            type: string
            examples:
              - '4.29'
            description: >-
              The tax on the items excluding shipping. The existing `refund_tax`
              already excludes shipping tax, so this value equals `refund_tax`;
              the corrected total refund tax is `refund_tax` plus
              `refund_shipping_tax`.
          returned_at:
            type: string
            format: date-time
            examples:
              - '2023-01-01T22:27:16.000Z'
            description: >-
              The date and time at which the item was returned, using the ISO
              8601 date format.
          exchange_variant:
            type: string
            examples:
              - ''
            description: >-
              The product variant selected by the customer for exchange (if
              applicable).
          return_reason:
            type: string
            examples:
              - I like another style more
            description: The specific reason for return given by the customer.
          parent_return_reason:
            type: string
            examples:
              - Didn't like it
            description: The general return reason category given by the customer.
          return_comment:
            type: string
            examples:
              - N/A
            description: >-
              The optional comment left by the customer when returning the
              product.
          barcode:
            type: string
            examples:
              - '290832428347'
            description: The barcode of the product.
          outcome:
            type: string
            enum:
              - reject
              - donate
              - review
              - default
              - keep
            examples:
              - default
            description: The return outcome, as permitted by the merchant's return policy.
          provider_restock_location_id:
            type:
              - string
              - 'null'
            description: The restock location for the return.
          consolidation_tracking:
            type: string
            examples:
              - MS6681181
            description: >
              If a line item is part of a consolidated shipment of many return
              items,

              this value holds the tracking value for the consolidated shipment

              that contains this item such as the Happy Returns Outbound
              Shipment tracking number.
          consolidation_destination_id:
            type:
              - string
              - 'null'
            examples:
              - '357'
            description: >
              If a line item is part of a consolidated shipment of many return
              items,

              this value holds the destination id for the consolidated shipment
              that

              contains this item such as the Happy Returns Outbound Shipment

              destination address id.
          condition:
            $ref: '#/components/schemas/Condition'
          disposition:
            $ref: '#/components/schemas/Disposition'
    Exchange:
      type: array
      items:
        type: object
        properties:
          exchange_id:
            type: string
            examples:
              - '23423423'
            description: The unique identifier associated with the exchange.
          exchange_order_id:
            type: integer
            format: int64
            examples:
              - 2342352463453
            description: The unique identifier associated with the exchange order.
          exchange_order_name:
            type: string
            examples:
              - EXC-4736272-1
            description: The name of the exchange order.
          product_id:
            type: string
            examples:
              - '2342342342344'
            description: The unique identifier associated with the product.
          variant_id:
            type: string
            examples:
              - '49483943473899'
            description: The unique identifier associated with the product variant.
          sku:
            type: string
            examples:
              - 2833928-Y
            description: The SKU associated with the product.
          type:
            type: string
            examples:
              - storefront
            description: The order type.
          title:
            type: string
            examples:
              - Grey Striped Shirt
            description: The product's name.
          price:
            type: string
            examples:
              - '48.00'
            description: The product's price.
          discount:
            type: string
            examples:
              - '0.00'
            description: The discount amount associated with the exchange.
          tax:
            type: string
            examples:
              - '2.64'
            description: The tax amount associated with the line item.
          total:
            type: string
            examples:
              - '50.64'
            description: >-
              The sum of the product's price and any tax, minus any discount
              applied.
          out_of_stock:
            type: boolean
            examples:
              - false
            description: Whether the product is in or out of stock.
          out_of_stock_resolution:
            type:
              - string
              - 'null'
          consolidation_tracking:
            type:
              - string
              - 'null'
            description: >
              If a line item is part of a consolidated shipment of many return
              items,

              this value holds the tracking value for the consolidated shipment
              that

              contains this item such as the Happy Returns Outbound Shipment
              tracking number.
    ReturnMethod:
      type: object
      properties:
        provider:
          type: string
          examples:
            - happy-returns
          description: The provider behind the return.
        method_type:
          type: string
          examples:
            - drop-off
          description: >-
            The method in which the return was physically initiated by the
            customer.
        address:
          $ref: '#/components/schemas/Address'
        state:
          type: string
          enum:
            - new
            - canceled
            - pre_transit
            - in_transit
            - out_for_delivery
            - delivered
            - needs_scheduled
            - skipped
            - pickup_failed
        rma_id:
          type: string
          examples:
            - HR12345
        qr_code_url:
          type: string
          examples:
            - https://partner.happyreturns.com/barcode/qr?code=HR12345
        updated_at:
          $ref: '#/components/schemas/UpdatedAt'
        scheduled_at:
          type: string
          format: date-time
        scannable_id:
          type:
            - string
            - 'null'
          description: The data used to scan and lookup return_method data in WMS software
    Type:
      type: string
      enum:
        - standard
        - warranty
    Label:
      type: object
      properties:
        status:
          type: string
          examples:
            - N/A
          description: The status of the return shipping label.
        updated_at:
          type: string
          format: date-time
          examples:
            - '2023-01-01T22:27:18.000Z'
          description: >-
            The date and time at which the label was last updated, using the ISO
            8601 date format.
        url:
          type: string
          format: url
          examples:
            - http://example.label.url
          description: The link to the shipping label details.
        rate:
          type:
            - integer
            - 'null'
          description: The shipping rate paid for the return label.
        carrier:
          type: string
          examples:
            - USPS
          description: The carrier associated with the return.
        tracking_number:
          type: string
          examples:
            - '9999999999999999999999'
          description: The tracking number associated with the return.
        line_items:
          type: array
          items:
            type: integer
          description: A list of line item ids associated with the label.
          examples:
            - - 1001
              - 1002
    Condition:
      type:
        - object
        - 'null'
      properties:
        description:
          type: string
          examples:
            - 'Grade A: No refurbishment needed'
        condition_category:
          type:
            - string
            - 'null'
          enum:
            - grade_a
            - grade_b
            - grade_c
            - grade_d
            - incorrect_item
            - missing
            - junk
          examples:
            - grade_c
        return_processor:
          type:
            - string
            - 'null'
          examples:
            - warehouse-operator@example.com
        note:
          type:
            - string
            - 'null'
          examples:
            - >-
              This item is missing the original packaging. Light refurbishment
              required. Scuff marks on the back of the item.
        inspected_at:
          type: string
          format: date-time
          examples:
            - '2023-07-19T15:11:32+00:00'
        images:
          type: array
          items:
            $ref: '#/components/schemas/Image'
    Disposition:
      type:
        - object
        - 'null'
      properties:
        disposition_outcome:
          type: string
          enum:
            - back_to_stock
            - resale_hold
            - recycle
            - donate
            - missing
        return_processor:
          type:
            - string
            - 'null'
          examples:
            - warehouse-operator@example.com
        note:
          type:
            - string
            - 'null'
          examples:
            - This item will be returned to stock after bagging and tagging
        inspected_at:
          type: string
          format: date-time
          examples:
            - '2023-07-19T15:11:32+00:00'
    Address:
      type: object
      properties:
        id:
          type: integer
          format: int32
          examples:
            - 23432434
        hash:
          type: string
          examples:
            - dd93hf99d83hdops9d8fhh38fhd03hh3
        created_at:
          type: string
          format: date-time
          examples:
            - '2021-10-01T03:30:15.000Z'
        updated_at:
          type: string
          format: date-time
          examples:
            - '2021-10-01T03:30:15.000Z'
        name:
          type: string
          examples:
            - Staples
        company:
          type:
            - string
            - 'null'
          examples:
            - Example Company
        address1:
          type: string
          examples:
            - 1747 Olentangy River Rd
        address2:
          type: string
          examples:
            - ''
        city:
          type: string
          examples:
            - Columbus
        state:
          type: string
          examples:
            - OH
        zip:
          type: string
          examples:
            - '43212'
        country:
          type: string
          examples:
            - United States of America
        country_code:
          type: string
          examples:
            - US
        phone:
          type: string
          examples:
            - ''
        latitude:
          type: number
          examples:
            - 39.995329
        longitude:
          type: number
          examples:
            - -83.026838
    UpdatedAt:
      type: object
      properties:
        date:
          type: string
        timezone_type:
          type: integer
          format: int32
        timezone:
          type: string
    Image:
      type: string
      format: uri
      examples:
        - https://example.com/image.jpg
  securitySchemes:
    api_key:
      type: apiKey
      name: X-Authorization
      in: header

````