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

# Retrieving Return Data

<Warning>
  This guide assumes you have API access and the necessary permissions. For help
  enabling these features, contact your Merchant Success Manager or
  [support@loopreturns.com](mailto:support@loopreturns.com).
</Warning>

## 📝 Overview

Loop provides several ways for merchants and partners to access return data, whether you need a real-time stream of updates or periodic data pulls for reporting and operations. This guide covers the available APIs and webhooks, and helps you choose the best approach for your use case.

The data returned by these endpoints includes:

* Return metadata (IDs, status, timestamps)
* Line item details (SKUs, quantities, reasons)
* Customer and order information
* Shipping and tracking details (where applicable)
* Disposition and grading info (if enabled)
* Associated events (creation, updates, closure)

This gives you a comprehensive view of each return and its lifecycle.

## ⚙️ Prerequisites

* Access to the Loop admin and API documentation.
* An API key with the **Return** scope (generate one in [Developer tools](https://admin.loopreturns.com/settings/developers) in Loop Admin).

<Tip>
  If you want to utilize webhooks, you'll need to set up a webhook subscription.
  See the [webhook setup guide](/webhook-reference/setting-up) for step-by-step
  instructions.
</Tip>

## 🧭 Choosing the Right Approach

Choosing the right method for retrieving return data depends on your workflow and integration needs. Here’s a guide to help you pick the best option:

| Use Case                                      | Recommended Option                                    |
| --------------------------------------------- | ----------------------------------------------------- |
| Real-time updates                             | [Return Webhook](#webhooks)                           |
| Bulk data export/reporting                    | [Detailed Returns List](#detailed-returns-list)       |
| Drill-down on a single return                 | [Get Return Details](#get-return-details)             |
| Pull packages by tracking status or timeframe | [Advanced Shipping Notice](#advanced-shipping-notice) |

**When to use each option:**

* **Return Webhook:** Best for triggering workflows or syncing systems in real time as returns are created, updated, or closed.
* **Detailed Returns List:** Ideal for periodic reporting, analytics, or keeping a data warehouse in sync with all return activity.
* **Get Return Details:** Use when you need comprehensive information about a specific return, such as for customer support or troubleshooting.
* **Advanced Shipping Notice:** Use when you need to pull a list of packages filtered by tracking status or time window, such as for warehouse or carrier integrations.

<Tip>
  **Best Practice:** Many merchants combine webhooks for real-time needs with
  periodic API pulls for reconciliation or reporting.
</Tip>

***

## 📡 APIs

### Detailed Returns List

Use the [Detailed Returns List API](/api-reference/latest/return-data/detailed-returns-list) to retrieve a list of returns, including line items and metadata. This is ideal for:

* Periodic reporting or analytics.
* Bulk data pulls (e.g., daily exports).
* Building dashboards or syncing with external systems.

<Tip>
  If you can't or don't want to use webhooks for real-time updates, the Detailed
  Returns List API is the best alternative. Schedule regular calls to this
  endpoint to keep your systems in sync with Loop's latest return data.
</Tip>

**Query Parameters:**

| Parameter | Type                                    | Description                                                                                                                | Options/Example                                    |
| --------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `from`    | string                                  | The start date and time for the returns list.                                                                              | `"2022-01-01T00:00:00.000Z"`                       |
| `to`      | string                                  | The end date and time for the returns list.                                                                                | `"2022-03-31T23:59:59.000Z"`                       |
| `filter`  | `enum (string)` (default: `created_at`) | The date used to filter results.                                                                                           | `created_at`, `updated_at`                         |
| `state`   | `enum (string)`                         | 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` |

These parameters let you customize the data you retrieve, such as pulling returns created in a given timeframe or filtering by return status.

<Note>
  See the [Detailed Returns List API
  docs](/api-reference/latest/return-data/detailed-returns-list) for full
  details.
</Note>

### Get Return Details

Use the [Get Return Details API](/api-reference/latest/return-data/get-return-details) to get the details of a specific return based on a return’s ID, an order name, or an order ID depending on the query value of the call.

This is useful when:

* You have an `id` for the return and need all associated data.
* You want to fetch all returns initiated on a given order.
* You want to display or view the details for a single return.

**Query Parameters:**

| Parameter    | Type    | Description                                       |
| ------------ | ------- | ------------------------------------------------- |
| `return_id`  | integer | The unique identifier associated with the return. |
| `order_id`   | integer | The unique identifier associated with the order.  |
| `order_name` | string  | The merchant-facing order name as stored in Loop. |

You can use any of these parameters to retrieve the details for a specific return. Typically, these values are obtained from the Detailed Returns List API or a webhook payload.

<Note>
  See the [Get Return Details API
  docs](/api-reference/latest/return-data/get-return-details) for more info.
</Note>

### Advanced Shipping Notice

The [Advanced Shipping Notice API](/api-reference/latest/return-data/advanced-shipping-notice) allows you to pull all packages by tracking statuses and/or timeframe. This endpoint returns an array of objects, each containing order and return information.

Use this endpoint to:

* Retrieve a list of packages filtered by tracking status or time window
* Access order and return details for each package

**Query Parameters:**

| Parameter         | Type   | Description                                     | Options/Example                 |
| ----------------- | ------ | ----------------------------------------------- | ------------------------------- |
| `from`            | string | The start date and time for filtering packages. | `"2022-01-01T00:00:00.000Z"`    |
| `to`              | string | The end date and time for filtering packages.   | `"2022-03-31T23:59:59.000Z"`    |
| `tracking_status` | string | Filter results by tracking status.              | e.g., `in_transit`, `delivered` |

These parameters let you filter which packages are returned based on time window and tracking state, making it easy to pull only the packages relevant to your workflow.

<Note>
  See the [Advanced Shipping Notice API
  docs](/api-reference/latest/return-data/advanced-shipping-notice) for full
  details on parameters and response structure.
</Note>

## 🔔 Webhooks

For real-time updates, subscribe to the [Return webhook](https://docs.loopreturns.com/webhook-reference/topics/return-webhook). You can configure triggers for this webhook to fire when returns are created, updated, or closed. This allows you to receive notifications whenever a return changes state in Loop.

**Common scenarios:**

* Trigger external workflows or business logic as soon as a return is initiated, updated, or completed.
* Sync return data to external systems in real time.
* Reduce the need for polling APIs.

> Webhook payloads include return metadata, line items, and event details. For the full schema and event types, see the [Return webhook documentation](https://docs.loopreturns.com/webhook-reference/topics/return-webhook).
>
> **Security:** Always [validate webhook signatures](https://docs.loopreturns.com/webhook-reference/validation) to ensure authenticity.
>
> **Reliability:** Loop will retry webhooks on failure—see [webhook errors and retries](https://docs.loopreturns.com/webhook-reference/getting-started#webhook-errors-and-retries) for details.

### 📦 Getting Tracking Information via Webhooks

When a return is first created, the initial `return.created` webhook will likely not contain label or tracking information—there is often a brief delay (a few seconds) before a label is generated. To reliably receive tracking numbers and RMA details, you have two options:

1. **Subscribe to the `label` webhook topics**

   * The [`label.created`](https://docs.loopreturns.com/webhook-reference/topics/label-webhook) webhook fires as soon as a return shipping label is generated.
   * This payload includes the tracking number and can be matched to the corresponding return using the `id` field (which matches the return ID from the [Return webhook](https://docs.loopreturns.com/webhook-reference/topics/return-webhook)).

2. **Wait for `return.updated` after label creation**
   * Once the label is created, a `return.updated` webhook is triggered, now containing the label and tracking number in the payload.

For the most reliable tracking info, either subscribe directly to the `label` webhooks, or wait for the subsequent `return.updated` event with the label data included. Always match the `id` field in the label payload to the return ID you received from the return webhook.

## 🛡️ Best Practices

* Store API keys securely and restrict access.
* Validate webhook signatures to ensure authenticity.
* Log all API interactions and webhook payloads for traceability.
* Monitor for failed API calls or webhook delivery issues.

***

## ✅ Conclusion

With these APIs and webhooks, you can efficiently access and synchronize return data in Loop to support your business workflows and reporting.

Remember to follow best practices for security and reliability, and combine real-time and bulk approaches as needed.

If you have questions, need help with advanced use cases, or want to provide feedback, check out the [Loop API documentation](/api-reference/) or contact our support team at [support@loopreturns.com](mailto:support@loopreturns.com).