Return Data

Detailed Returns List

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

This endpoint supports pagination. We highly encourage using pagination for this endpoint.

Read the guide on paginating requests for details.

Note: If no datetimes are passed, the response defaults to only contain returns from the previous 24 hours. See Query Params 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 Query Params below for more information.

Required API key scope

Returns

GET

warehouse

return

list

curl --request GET \
  --url https://api.loopreturns.com/api/v1/warehouse/return/list \
  --header 'X-Authorization: <api-key>'

[
  {
    "id": "12345678",
    "state": "open",
    "created_at": "2023-01-01T22:27:15.000Z",
    "updated_at": "2023-01-01T22:27:18.000Z",
    "edited_at": "2023-01-03T22:34:17.000Z",
    "total": "63.30",
    "outcome": "exchange",
    "order_id": "98766312",
    "order_name": "#7382018",
    "provider_order_id": "3248923479283",
    "order_number": "7381018",
    "provider_order_number": "7382018",
    "customer": "example@example.com",
    "origin_country": "United States",
    "origin_country_code": "US",
    "multi_currency": false,
    "currency": "USD",
    "return_product_total": "156.00",
    "return_discount_total": "0.00",
    "return_tax_total": "8.58",
    "return_total": "164.58",
    "return_credit_total": "101.28",
    "exchange_product_total": "96.00",
    "exchange_discount_total": "0.00",
    "exchange_tax_total": "5.28",
    "exchange_total": "101.28",
    "exchange_credit_total": "101.28",
    "gift_card": "0.00",
    "gift_card_order_name": "Gift Card Name",
    "gift_card_order_id": "23141001200513",
    "handling_fee": "0.00",
    "refund": "63.30",
    "upsell": "0.00",
    "line_items": [
      {
        "line_item_id": "293482039",
        "provider_line_item_id": "23984238720340",
        "product_id": "29871298310292",
        "variant_id": "23498287203948",
        "sku": "2039473-Y",
        "title": "Black Striped Shirt",
        "price": "78.00",
        "discount": "0.00",
        "tax": "4.29",
        "refund": "31.65",
        "refund_item": "27.36",
        "refund_tax": "4.29",
        "returned_at": "2023-01-01T22:27:16.000Z",
        "exchange_variant": "",
        "return_reason": "I like another style more",
        "parent_return_reason": "Didn't like it",
        "return_comment": "N/A",
        "barcode": "290832428347",
        "outcome": "default",
        "provider_restock_location_id": "<string>",
        "consolidation_tracking": "N/A",
        "condition": {
          "description": "Grade A: No refurbishment needed",
          "condition_category": "grade_c",
          "return_processor": "warehouse-operator@example.com",
          "note": "This item is missing the original packaging. Light refurbishment required. Scuff marks on the back of the item.",
          "inspected_at": "2023-07-19T15:11:32+00:00",
          "images": [
            "https://example.com/image.jpg"
          ]
        },
        "disposition": {
          "disposition_outcome": "back_to_stock",
          "return_processor": "warehouse-operator@example.com",
          "note": "This item will be returned to stock after bagging and tagging",
          "inspected_at": "2023-07-19T15:11:32+00:00"
        }
      }
    ],
    "exchanges": [
      {
        "exchange_id": "23423423",
        "exchange_order_id": 2342352463453,
        "exchange_order_name": "EXC-4736272-1",
        "product_id": "2342342342344",
        "variant_id": "49483943473899",
        "sku": "2833928-Y",
        "type": "storefront",
        "title": "Grey Striped Shirt",
        "price": "48.00",
        "discount": "0.00",
        "tax": "2.64",
        "total": "50.64",
        "out_of_stock": false,
        "out_of_stock_resolution": "<string>",
        "consolidation_tracking": "<string>"
      }
    ],
    "carrier": "N/A",
    "tracking_number": "N/A",
    "label_status": "N/A",
    "label_url": "http://example.label.url",
    "label_rate": "<string>",
    "status_page_url": "https://example.loopreturns.com/#/return/{uuid}",
    "label_updated_at": "N/A",
    "destination_id": "67896541368765",
    "return_method": {
      "provider": "happy-returns",
      "method_type": "drop-off",
      "address": {
        "id": 23432434,
        "hash": "dd93hf99d83hdops9d8fhh38fhd03hh3",
        "created_at": "2021-10-01T03:30:15.000Z",
        "updated_at": "2021-10-01T03:30:15.000Z",
        "name": "Staples",
        "company": "Example Company",
        "address1": "1747 Olentangy River Rd",
        "address2": "",
        "city": "Columbus",
        "state": "OH",
        "zip": "43212",
        "country": "United States of America",
        "country_code": "US",
        "phone": "",
        "latitude": 39.995329,
        "longitude": -83.026838
      },
      "state": "new",
      "rma_id": "HR12345",
      "qr_code_url": "https://partner.happyreturns.com/barcode/qr?code=HR12345",
      "updated_at": {
        "date": "<string>",
        "timezone_type": 123,
        "timezone": "<string>"
      },
      "scheduled_at": "2023-11-07T05:31:56Z",
      "scannable_id": "<string>"
    },
    "package_reference": "<string>",
    "type": "standard",
    "labels": [
      {
        "status": "N/A",
        "updated_at": "2023-01-01T22:27:18.000Z",
        "url": "http://example.label.url",
        "rate": 123,
        "carrier": "USPS",
        "tracking_number": "9999999999999999999999",
        "line_items": [
          1001,
          1002
        ]
      }
    ]
  }
]

Authorizations

X-Authorization

string

header

required

Query Parameters

from

string

The start date and time for the returns list.

string

The end date and time for the returns list.

filter

enum<string>

default:

created_at

The date used to filter results.

Available options:

created_at,

updated_at

state

enum<string>

The keywords used to filter the list to only include returns in a particular state.

Defaults to only contain open, closed, and expired returns.

Available options:

open,

closed,

cancelled,

expired,

review

Response

200

application/json

Success

string

The unique identifier associated with the return.

state

string

The current state of the return.

created_at

string

The date and time at which the return was created, using the ISO 8601 date format.

updated_at

string

The date and time at which the return was last updated, using the ISO 8601 date format.

edited_at

string

The date and time at which the return was last edited, using the ISO 8601 date format.

total

string

The total cost of the return.

outcome

enum<string>

The outcome of the return as limited by the merchant and as selected by the customer.

Available options:

exchange,

upsell,

refund,

credit,

exchange+refund,

exchange+credit

order_id

string

The Loop order identifier associated with the return.

order_name

string

The order name.

provider_order_id

string

The Shopify order ID.

order_number

string

The order number.

provider_order_number

string

The Shopify order number.

customer

string

The customer's email address.

origin_country

string | null

The country of the customer's shipping address.

origin_country_code

string | null

The ISO 3166-1 alpha-2 country code of the customer's shipping address.

multi_currency

boolean

Whether the order was placed through Shopify Payments in some currency other than the default store currency.

currency

string

The currency code of the store's default currency.

return_product_total

string

The gross value of the returning items before discounts and tax.

return_discount_total

string

The total value of the discounts on the returning items.

return_tax_total

string

The total value of the taxes on the returning items.

return_total

string

The net value of the returning items after discounts and tax.

return_credit_total

string

The value of the returning items credited to the shopper after the refund has been issued.

exchange_product_total

string

The gross value of the exchange before discounts and tax.

exchange_discount_total

string

The total value of discounts on the exchange.

exchange_tax_total

string

The total value of the taxes on the exchange.

exchange_total

string

The net value of the exchanges after discounts and tax.

exchange_credit_total

string

The value of the return credit used by the shopper.

gift_card

string

The value of the gift card issued in the return.

gift_card_order_name

string

The name of the gift card order issued in the return.

gift_card_order_id

string

The unique identifier of the gift card issued in the return.

handling_fee

string

The handling fee charged by the merchant.

refund

string

The amount refunded in the return.

upsell

string

The upsell amount associated with the return.

line_items

object[]

line_items.line_item_id

string

The unique identifier associated with the line item.

line_items.provider_line_item_id

string

The Shopify or other platform identifier associated with the line item.

line_items.product_id

string

The unique identifier associated with the product.

line_items.variant_id

string

The unique identifier associated with the product variant.

line_items.sku

string

The SKU associated with the product.

line_items.title

string

The product's name.

line_items.price

string

The product's price.

line_items.discount

string

The discount amount associated with the line item.

line_items.tax

string

The tax amount associated with the line item.

line_items.refund

string

The refund amount associated with the line item.

line_items.refund_item

string

The refund amount minus the tax amount.

line_items.refund_tax

string

Equal to the refund.

line_items.returned_at

string

The date and time at which the item was returned, using the ISO 8601 date format.

line_items.exchange_variant

string

The product variant selected by the customer for exchange (if applicable).

line_items.return_reason

string

The specific reason for return given by the customer.

line_items.parent_return_reason

string

The general return reason category given by the customer.

line_items.return_comment

string

The optional comment left by the customer when returning the product.

line_items.barcode

string

The barcode of the product.

line_items.outcome

enum<string>

The return outcome, as permitted by the merchant's return policy.

Available options:

reject,

donate,

review,

default,

keep

line_items.provider_restock_location_id

string

The restock location for the return.

line_items.consolidation_tracking

string

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.

line_items.condition

object

line_items.disposition

object

exchanges

object[]

carrier

string

The carrier associated with the return.

tracking_number

string

The return's tracking number.

label_status

string

The status of the return shipping label.

label_url

string

The link to the shipping label details.

label_rate

string

The shipping rate paid for the return label.

status_page_url

string

The link to the Loop return tracking status page associated with the return.

label_updated_at

string

The date and time at which the label was last updated, using the ISO 8601 date format.

destination_id

string

The unique identifier associated with the shipping destination of the return.

return_method

object

package_reference

string

The data used to look up package data in WMS software.

type

enum<string>

The type of return submission.

Available options:

standard,

warranty

labels

object[]

Create Return Deep Link with QR Code Get Return Details

curl --request GET \
  --url https://api.loopreturns.com/api/v1/warehouse/return/list \
  --header 'X-Authorization: <api-key>'

[
  {
    "id": "12345678",
    "state": "open",
    "created_at": "2023-01-01T22:27:15.000Z",
    "updated_at": "2023-01-01T22:27:18.000Z",
    "edited_at": "2023-01-03T22:34:17.000Z",
    "total": "63.30",
    "outcome": "exchange",
    "order_id": "98766312",
    "order_name": "#7382018",
    "provider_order_id": "3248923479283",
    "order_number": "7381018",
    "provider_order_number": "7382018",
    "customer": "example@example.com",
    "origin_country": "United States",
    "origin_country_code": "US",
    "multi_currency": false,
    "currency": "USD",
    "return_product_total": "156.00",
    "return_discount_total": "0.00",
    "return_tax_total": "8.58",
    "return_total": "164.58",
    "return_credit_total": "101.28",
    "exchange_product_total": "96.00",
    "exchange_discount_total": "0.00",
    "exchange_tax_total": "5.28",
    "exchange_total": "101.28",
    "exchange_credit_total": "101.28",
    "gift_card": "0.00",
    "gift_card_order_name": "Gift Card Name",
    "gift_card_order_id": "23141001200513",
    "handling_fee": "0.00",
    "refund": "63.30",
    "upsell": "0.00",
    "line_items": [
      {
        "line_item_id": "293482039",
        "provider_line_item_id": "23984238720340",
        "product_id": "29871298310292",
        "variant_id": "23498287203948",
        "sku": "2039473-Y",
        "title": "Black Striped Shirt",
        "price": "78.00",
        "discount": "0.00",
        "tax": "4.29",
        "refund": "31.65",
        "refund_item": "27.36",
        "refund_tax": "4.29",
        "returned_at": "2023-01-01T22:27:16.000Z",
        "exchange_variant": "",
        "return_reason": "I like another style more",
        "parent_return_reason": "Didn't like it",
        "return_comment": "N/A",
        "barcode": "290832428347",
        "outcome": "default",
        "provider_restock_location_id": "<string>",
        "consolidation_tracking": "N/A",
        "condition": {
          "description": "Grade A: No refurbishment needed",
          "condition_category": "grade_c",
          "return_processor": "warehouse-operator@example.com",
          "note": "This item is missing the original packaging. Light refurbishment required. Scuff marks on the back of the item.",
          "inspected_at": "2023-07-19T15:11:32+00:00",
          "images": [
            "https://example.com/image.jpg"
          ]
        },
        "disposition": {
          "disposition_outcome": "back_to_stock",
          "return_processor": "warehouse-operator@example.com",
          "note": "This item will be returned to stock after bagging and tagging",
          "inspected_at": "2023-07-19T15:11:32+00:00"
        }
      }
    ],
    "exchanges": [
      {
        "exchange_id": "23423423",
        "exchange_order_id": 2342352463453,
        "exchange_order_name": "EXC-4736272-1",
        "product_id": "2342342342344",
        "variant_id": "49483943473899",
        "sku": "2833928-Y",
        "type": "storefront",
        "title": "Grey Striped Shirt",
        "price": "48.00",
        "discount": "0.00",
        "tax": "2.64",
        "total": "50.64",
        "out_of_stock": false,
        "out_of_stock_resolution": "<string>",
        "consolidation_tracking": "<string>"
      }
    ],
    "carrier": "N/A",
    "tracking_number": "N/A",
    "label_status": "N/A",
    "label_url": "http://example.label.url",
    "label_rate": "<string>",
    "status_page_url": "https://example.loopreturns.com/#/return/{uuid}",
    "label_updated_at": "N/A",
    "destination_id": "67896541368765",
    "return_method": {
      "provider": "happy-returns",
      "method_type": "drop-off",
      "address": {
        "id": 23432434,
        "hash": "dd93hf99d83hdops9d8fhh38fhd03hh3",
        "created_at": "2021-10-01T03:30:15.000Z",
        "updated_at": "2021-10-01T03:30:15.000Z",
        "name": "Staples",
        "company": "Example Company",
        "address1": "1747 Olentangy River Rd",
        "address2": "",
        "city": "Columbus",
        "state": "OH",
        "zip": "43212",
        "country": "United States of America",
        "country_code": "US",
        "phone": "",
        "latitude": 39.995329,
        "longitude": -83.026838
      },
      "state": "new",
      "rma_id": "HR12345",
      "qr_code_url": "https://partner.happyreturns.com/barcode/qr?code=HR12345",
      "updated_at": {
        "date": "<string>",
        "timezone_type": 123,
        "timezone": "<string>"
      },
      "scheduled_at": "2023-11-07T05:31:56Z",
      "scannable_id": "<string>"
    },
    "package_reference": "<string>",
    "type": "standard",
    "labels": [
      {
        "status": "N/A",
        "updated_at": "2023-01-01T22:27:18.000Z",
        "url": "http://example.label.url",
        "rate": 123,
        "carrier": "USPS",
        "tracking_number": "9999999999999999999999",
        "line_items": [
          1001,
          1002
        ]
      }
    ]
  }
]

Using the API

APIs

Detailed Returns List

Required API key scope

Authorizations

Query Parameters

Defaults to only contain open, closed, and expired returns.

Response