Detailed Returns 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": "<any>",
    "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": "23984238720",
        "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
        ]
      }
    ]
  }
]

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 neither from nor to is passed, the response defaults to only contain returns from the previous 24 hours. See from and 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 below for more information.

Required API key scope

Returns

GET

warehouse

return

list

Detailed Returns 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": "<any>",
    "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": "23984238720",
        "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. If from is passed without to, returns created in the 24 hours after from are returned.

Examples:

"2022-01-01T00:00:00.000Z"

string

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.

Examples:

"2022-03-31T23:59:59.000Z"

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

Success

string

The unique identifier associated with the return.

Examples:

"12345678"

state

string

The current state of the return.

Examples:

"open"

created_at

string<date-time>

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

Examples:

"2023-01-01T22:27:15.000Z"

updated_at

string<date-time>

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

Examples:

"2023-01-01T22:27:18.000Z"

edited_at

string<date-time>

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

Examples:

"2023-01-03T22:34:17.000Z"

total

string

The total cost of the return.

Examples:

"63.30"

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.

Examples:

"98766312"

order_name

string

The order name.

Examples:

"#7382018"

provider_order_id

string

The Shopify order ID.

Examples:

"3248923479283"

order_number

string

The order number.

Examples:

"7381018"

provider_order_number

string

The Shopify order number.

Examples:

"7382018"

customer

string

The customer's email address.

Examples:

"example@example.com"

origin_country

string | null

The country of the customer's shipping address.

Examples:

"United States"

origin_country_code

string | null

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

Examples:

"US"

multi_currency

any

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.

Examples:

"USD"

return_product_total

string

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

Examples:

"156.00"

return_discount_total

string

The total value of the discounts on the returning items.

Examples:

"0.00"

return_tax_total

string

The total value of the taxes on the returning items.

Examples:

"8.58"

return_total

string

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

Examples:

"164.58"

return_credit_total

string

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

Examples:

"101.28"

exchange_product_total

string

The gross value of the exchange before discounts and tax.

Examples:

"96.00"

exchange_discount_total

string

The total value of discounts on the exchange.

Examples:

"0.00"

exchange_tax_total

string

The total value of the taxes on the exchange.

Examples:

"5.28"

exchange_total

string

The net value of the exchanges after discounts and tax.

Examples:

"101.28"

exchange_credit_total

string

The value of the return credit used by the shopper.

Examples:

"101.28"

gift_card

string

The value of the gift card issued in the return.

Examples:

"0.00"

gift_card_order_name

string | null

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

Examples:

"Gift Card Name"

gift_card_order_id

string | null

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

Examples:

"23141001200513"

handling_fee

string

The handling fee charged by the merchant.

Examples:

"0.00"

refund

string

The amount refunded in the return.

Examples:

"63.30"

upsell

string

The upsell amount associated with the return.

Examples:

"0.00"

line_items

object[]

Show child attributes

exchanges

object[]

Show child attributes

carrier

string

The carrier associated with the return.

Examples:

"N/A"

tracking_number

string

The return's tracking number.

Examples:

"N/A"

label_status

string

The status of the return shipping label.

Examples:

"N/A"

label_url

string | null

The link to the shipping label details.

Examples:

"http://example.label.url"

label_rate

string | null

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.

Examples:

"https://example.loopreturns.com/#/return/{uuid}"

label_updated_at

string<date-time>

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

Examples:

"N/A"

destination_id

string | null

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

Examples:

"67896541368765"

return_method

object

Show child attributes

package_reference

string | null

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[]

Show child attributes

Create Return Deep Link with QR Code Get Return Details

Using the API

APIs

Detailed Returns List

Required API key scope

Authorizations

Query Parameters

Response