v1
latestOpenAPI 3.1.02026-07-2689175245.8 KBDetailed 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
Query parameters
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.
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.
The date used to filter results.
The keywords used to filter the list to only include returns in a particular state. Defaults to only contain open, closed, and expired returns.
When present, enables cursor-based pagination. The response is then wrapped in an object containing returns plus nextPageUrl/previousPageUrl, rather than a bare array.
The number of returns to return per page when paginating.
The cursor identifying the page to return when paginating.
Response
Success
Example response
[
{
"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",
"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",
"currency": "USD",
"return_product_total": "156.00",
"return_discount_total": "0.00",
"return_tax_total": "8.58",
"return_total": "164.58",
"refund_shipping_total": "4.00",
"refund_shipping_tax_total": "0.40",
"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",
"gift_card_presentment": {
"value": "0.00",
"currency": "CAD"
},
"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",
"refund_shipping": "4.00",
"refund_excluding_shipping": "27.65",
"refund_shipping_tax": "0.40",
"refund_excluding_shipping_tax": "4.29",
"returned_at": "2023-01-01T22:27:16.000Z",
"return_reason": "I like another style more",
"parent_return_reason": "Didn't like it",
"return_comment": "N/A",
"barcode": "290832428347",
"outcome": "default",
"consolidation_tracking": "MS6681181",
"consolidation_destination_id": "357",
"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": {
"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"
}
}
],
"presentment": {
"currency": "CAD",
"return_product_total": "156.00",
"return_discount_total": "0.00",
"return_tax_total": "8.58",
"return_total": "164.58",
"return_shipping_total": "4.00",
"return_shipping_tax_total": "0.40",
"credit_shipping_total": "0.00",
"handling_fee": "0.00",
"return_credit_total": "0.00",
"gift_card": "0.00",
"refund": "168.58",
"refund_breakdown": [
{
"gateway": "shopify_payments",
"provider": "shopify",
"amount": "168.58",
"currency": "CAD"
}
],
"line_items": [
{
"line_item_id": "59989689",
"price": "156.00",
"discount": "0.00",
"tax": "8.58"
}
]
},
"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"
}
],
"carrier": "N/A",
"tracking_number": "N/A",
"label_status": "N/A",
"label_url": "http://example.label.url",
"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",
"city": "Columbus",
"state": "OH",
"zip": "43212",
"country": "United States of America",
"country_code": "US",
"latitude": 39.995329,
"longitude": -83.026838
},
"rma_id": "HR12345",
"qr_code_url": "https://partner.happyreturns.com/barcode/qr?code=HR12345"
},
"labels": [
{
"status": "N/A",
"updated_at": "2023-01-01T22:27:18.000Z",
"url": "http://example.label.url",
"carrier": "USPS",
"tracking_number": "9999999999999999999999",
"line_items": [
1001,
1002
]
}
]
}
]