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

# Get Return Details

> Get the details of a specific return based on a return's ID,
an order name, or an order ID from the commerce provider (e.g. Shopify) depending on the
query value of the call.

### Required API key scope
- Returns




## OpenAPI

````yaml get /warehouse/return/details
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/details:
    get:
      tags:
        - Return Data
      summary: Get Return Details
      description: >
        Get the details of a specific return based on a return's ID,

        an order name, or an order ID from the commerce provider (e.g. Shopify)
        depending on the

        query value of the call.


        ### Required API key scope

        - Returns
      operationId: getReturnDetails
      parameters:
        - name: return_id
          description: The unique identifier associated with the return.
          example: 37603922
          in: query
          schema:
            type: integer
        - name: order_id
          description: The unique identifier associated with the order.
          example: 2347613440760
          in: query
          schema:
            type: integer
        - name: order_name
          description: The order name from the commerce provider (e.g. Shopify).
          example: '2222'
          in: query
          schema:
            type: string
        - name: currency_type
          description: >
            The currency type of the return.


            If set to `shop`, all currency fields in the response will use the
            shop's currency.


            If set to `presentment`, all currency fields in the response will
            use the currency presented to the shopper when they made the
            purchase.
          in: query
          schema:
            type: string
            enum:
              - shop
              - presentment
      responses:
        '200':
          $ref: '#/components/responses/ReturnDetails'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - api_key: []
components:
  responses:
    ReturnDetails:
      description: Success
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ReturnDetails'
              - $ref: '#/components/schemas/NoMatchingReturnDetails'
              - $ref: '#/components/schemas/ReturnDetailsMissingParameters'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            required:
              - errors
            properties:
              errors:
                type: string
                examples:
                  - Unauthorized.
  schemas:
    ReturnDetails:
      type: object
      properties:
        id:
          type: integer
          examples:
            - 37603915
          description: The unique identifier associated with the return.
        created_at:
          type: string
          format: date-time
          examples:
            - '2023-08-22 14:08:31'
          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-08-22 15:05:15'
          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-08-22 15:05:15'
          description: >-
            The date and time at which the return was last edited, using the ISO
            8601 date format.
        order_id:
          examples:
            - 3838173
          description: The Loop order identifier associated with the return.
        order_name:
          examples:
            - '1138'
          description: The order name.
        order_number:
          examples:
            - 138
          description: The order number.
        provider_order_number:
          type: integer
          examples:
            - 1138
          description: The order number from the commerce provider (e.g. Shopify).
        provider_order_id:
          type: integer
          examples:
            - 5444175757553
          description: The order ID from the commerce provider (e.g. Shopify).
        total:
          examples:
            - '192.42'
          description: The total cost of the return.
        customer:
          type:
            - string
            - 'null'
          examples:
            - email@loopreturns.com
          description: The customer's email address.
        multi_currency:
          examples:
            - false
          description: |
            Whether the order was placed through Shopify Payments in
            some currency other than the default store currency.
        state:
          examples:
            - cancelled
          description: The status of the return.
        currency:
          examples:
            - USD
          description: The currency code of the store's default currency.
        exchange:
          examples:
            - '0.00'
          description: The value of the exchange.
        exchange_order_name:
          type: array
          items:
            type: string
          examples:
            - - EXC-4736272-1
              - EXC-4736272-2
          description: |
            The names of the exchange orders associated with the return.
        exchange_order_id:
          type: array
          items:
            type: integer
            format: int64
          examples:
            - - 2342352463453
              - 2342352463454
          description: |
            The unique identifiers associated with the exchange orders.
        gift_card_order_name:
          examples:
            - Gift Card Name
          description: The name of the gift card order.
        gift_card_order_id:
          examples:
            - 987651987684
          description: The unique identifier associated with the gift card order.
        gift_card:
          examples:
            - '0.00'
          description: The gift card amount.
        gift_card_presentment:
          $ref: '#/components/schemas/GiftCardPresentment'
        refund:
          examples:
            - '192.42'
          description: The refund amount in the presentment currency.
        refunds:
          $ref: '#/components/schemas/Refunds'
        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.
        handling_fee:
          examples:
            - '0.00'
          description: The handling fee charged by the merchant.
        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.
        upsell:
          examples:
            - '0.00'
          description: The upsell amount associated with the return.
        line_items:
          $ref: '#/components/schemas/ReturnDetailsLineItem'
        presentment:
          $ref: '#/components/schemas/Presentment'
        customer_email:
          type: string
          examples:
            - email@loopreturns.com
          description: The customer's email address.
        carrier:
          type: string
          examples:
            - USPS
          description: The carrier associated with the return.
        label_status:
          type: string
          examples:
            - out_for_delivery
          description: The delivery status of the return.
        label_updated_at:
          type: string
          format: date-time
          examples:
            - '2023-08-21T14:09:17.000Z'
          description: >-
            The date and time at which the label was last updated, using the ISO
            8601 date format.
        label_url:
          type: string
          examples:
            - >-
              https://test-bucket.s3-us-west-2.amazonaws.com/files/postage_label/01234567/0df7eea6147b44b7ac204e9eb8293cfa.pdf
          description: The link to the shipping label.
        label_rate:
          type: string
          examples:
            - '250'
          description: The shipping rate paid for the return label.
        outcome:
          $ref: '#/components/schemas/ReturnOutcome'
          description: >-
            The outcome of the return as limited by the merchant and as selected
            by the customer.
        tracking_number:
          type: string
          examples:
            - '9999999999999999999999'
          description: The tracking number associated with the return.
        destination_id:
          type: string
          examples:
            - '17'
          description: The unique identifier associated with the return's destination.
        status_page_url:
          type: string
          examples:
            - >-
              https://sample-store.loopreturns.com/#/return/beee8df-b948-4feb-8e23-8cfd2d1e3565
          description: The link to the return's status page.
        return_method:
          type: string
          examples:
            - happy-returns
          description: The return method.
        package_reference:
          type: string
          examples:
            - '9999999999999999999999'
          description: The package reference of the return.
        shopify_refund_object:
          type: array
          items:
            $ref: '#/components/schemas/ShopifyRefundObject'
        exchanges:
          type: array
          examples:
            - []
        customer_first_name:
          examples:
            - Alex
          type: string
        customer_last_name:
          examples:
            - Doe
          type: string
        type:
          $ref: '#/components/schemas/Type'
          description: The type of return submission.
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
    NoMatchingReturnDetails:
      type: object
      properties:
        error:
          type: object
          properties:
            data:
              type: object
            message:
              type: string
              examples:
                - No return found with this ID.
    ReturnDetailsMissingParameters:
      type: object
      properties:
        error:
          type: object
          properties:
            data:
              type: object
            message:
              type: string
              examples:
                - >-
                  Missing parameter. Please pass in: return_id, order_name, or
                  order_id.
    GiftCardPresentment:
      type: object
      description: >-
        The gift card credit issued in the return, in the currency the gift card
        was issued in (the order's presentment currency when available).
      properties:
        value:
          type: string
          examples:
            - '0.00'
          description: The total value of the gift card credit issued in the return.
        currency:
          type:
            - string
            - 'null'
          examples:
            - CAD
          description: The ISO 4217 currency code of `value`.
    Refunds:
      type: array
      items:
        type: object
        properties:
          gateway:
            type: string
            examples:
              - Stripe
          amount:
            type: string
            examples:
              - '78.00'
          currency:
            type: string
            examples:
              - USD
          provider_refund_id:
            type:
              - string
              - 'null'
            examples:
              - '12345'
          provider:
            type: string
            examples:
              - reshop
    ReturnDetailsLineItem:
      type: array
      items:
        type: object
        properties:
          line_item_id:
            type: number
            examples:
              - 293482039
          provider_line_item_id:
            type: number
            examples:
              - 23984238720
          product_id:
            type: number
            examples:
              - 29871298313
          variant_id:
            type: number
            examples:
              - 23498287203948
          sku:
            type: string
            examples:
              - 2039473-Y
          line_item_title:
            type: string
            examples:
              - Black Striped Shirt
          variant_title:
            type: string
            examples:
              - Small / Navy
          title:
            type: string
            examples:
              - Black Striped Shirt
          image:
            type: string
            examples:
              - >-
                https://cdn.shopify.com/s/files/1/0000/0000/0000/products/Black_Striped_Shirt.jpg
          price:
            type: string
            examples:
              - '78.00'
          discount:
            type: string
            examples:
              - '0.00'
          tax:
            type: string
            examples:
              - '4.29'
          refund:
            type: string
            examples:
              - '31.65'
          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
              - 'null'
          barcode:
            type: string
            examples:
              - ''
          provider_restock_location_id:
            type:
              - string
              - 'null'
          consolidation_tracking:
            type:
              - string
              - 'null'
            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.
          reason:
            type: string
            examples:
              - Item was too small
          parent_reason:
            type: string
            examples:
              - Item didn't fit
          refund_tax:
            type: string
            examples:
              - '4.29'
          refund_item:
            type: string
            examples:
              - '27.36'
          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`.
          outcome:
            type: string
            enum:
              - reject
              - donate
              - review
              - default
              - keep
            examples:
              - default
          condition:
            $ref: '#/components/schemas/Condition'
          disposition:
            $ref: '#/components/schemas/Disposition'
    Presentment:
      type: object
      description: >-
        Return totals in the order's presentment (customer) currency, sourced
        from the stored, provider-authoritative amounts rather than converted
        from the shop currency. Use this block to reconcile multi-currency
        returns to the cent; the amounts satisfy `refund + return_credit_total +
        handling_fee == return_total + return_shipping_total +
        credit_shipping_total`.
      properties:
        currency:
          type:
            - string
            - 'null'
          examples:
            - CAD
          description: The ISO 4217 code of the order's presentment (customer) 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
            (`return_product_total - return_discount_total + return_tax_total`).
            Items only — excludes reimbursed shipping.
        return_shipping_total:
          type: string
          examples:
            - '4.00'
          description: >-
            Reimbursed original-order shipping folded into the refund, tax
            inclusive.
        return_shipping_tax_total:
          type: string
          examples:
            - '0.40'
          description: >-
            The tax portion already included in `return_shipping_total`.
            Informational — not an additional amount.
        credit_shipping_total:
          type: string
          examples:
            - '0.00'
          description: >-
            Reimbursed original-order shipping folded into the store credit
            instead of the refund.
        handling_fee:
          type: string
          examples:
            - '0.00'
          description: The handling fee withheld by the merchant (`0.00` when waived).
        return_credit_total:
          type: string
          examples:
            - '0.00'
          description: The store credit issued to the shopper. Equal to `gift_card`.
        gift_card:
          type: string
          examples:
            - '0.00'
          description: >-
            The value of the gift card issued in the return. Equal to
            `return_credit_total`.
        refund:
          type: string
          examples:
            - '168.58'
          description: The total amount refunded to the original payment tender(s).
        refund_breakdown:
          type: array
          description: >-
            The per-tender split of `refund` — one entry per original payment
            tender (for example a gift card tender alongside a card).
          items:
            type: object
            properties:
              gateway:
                type: string
                examples:
                  - shopify_payments
                description: >-
                  The payment gateway of the original tender (for example
                  `shopify_payments` or `gift_card`).
              provider:
                type: string
                examples:
                  - shopify
                description: The commerce provider that processed the refund.
              amount:
                type: string
                examples:
                  - '168.58'
                description: >-
                  The amount refunded to this tender, in the presentment
                  currency.
              currency:
                type: string
                examples:
                  - CAD
                description: >-
                  The ISO 4217 currency code of `amount` (the presentment
                  currency).
        line_items:
          type: array
          description: Presentment amounts for each returning line item.
          items:
            type: object
            properties:
              line_item_id:
                type: string
                examples:
                  - '59989689'
                description: >-
                  The unique identifier of the returning line item (matches the
                  top-level `line_items` entries).
              price:
                type: string
                examples:
                  - '156.00'
                description: The price of the line item before discounts and tax.
              discount:
                type: string
                examples:
                  - '0.00'
                description: The discount on the line item.
              tax:
                type: string
                examples:
                  - '8.58'
                description: The tax on the line item.
    ReturnOutcome:
      type: string
      enum:
        - exchange
        - upsell
        - refund
        - credit
        - exchange+refund
        - exchange+credit
    ShopifyRefundObject:
      type: object
      properties:
        id:
          type: integer
          examples:
            - 1
          description: The unique identifier associated with the refund, assigned by Loop.
        return_id:
          type: integer
          examples:
            - 123456789
          description: The unique identifier associated with the return, assigned by Loop.
        provider_refund_id:
          type: integer
          examples:
            - 987654321
          description: >-
            The unique identifier associated with the refund, assigned by the
            commerce provider (e.g. Shopify).
        provider_created_at:
          type: string
          format: date-time
          examples:
            - '2023-01-01T20:18:04.000Z'
          description: >-
            The date and time at which the refund was created in the commerce
            provider (e.g. Shopify), using the ISO 8601 date format.
        created_at:
          type: string
          format: date-time
          examples:
            - '2023-01-01T22:27:18.000Z'
          description: >-
            The date and time at which the refund was created in Loop, 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 refund was last updated in Loop,
            using the ISO 8601 date format.
    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'
    Image:
      type: string
      format: uri
      examples:
        - https://example.com/image.jpg
  securitySchemes:
    api_key:
      type: apiKey
      name: X-Authorization
      in: header

````