APIs
- Return Actions
- Return Data
- Programmatic Webhooks
- Item Grading and Dispositioning
- Cart
- Destinations
- Blocklist
- Allowlist
- Fraud Reports
- Happy Returns Shipments
- Label Requests
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
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
Query Parameters
The start date and time for the returns list.
"2022-01-01T00:00:00.000Z"
The end date and time for the returns list.
"2022-03-31T23:59:59.000Z"
The date used to filter results.
created_at
, updated_at
The keywords used to filter the list to only include returns in a particular state.
Defaults to only contain open, closed, and expired returns.
open
, closed
, cancelled
, expired
, review
Response
Success
The response is of type object[]
.
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
]
}
]
}
]