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

# Returns — Read

> Search and inspect returns through the Loop MCP Server.

These read-only tools let an assistant search for returns, inspect a single return in detail, and review a return's event timeline. Each tool renders a Generative UI card so the merchant can drill in without leaving the chat.

***

## List Returns

**Tool name:** `list-returns-tool`  ·  **Read-only**  ·  **Permissions:** `list-returns` or `manage-returns`

Search and paginate the authenticated shop's returns with rich filtering. Filters compose with AND semantics across distinct fields and OR semantics within multi-value fields (`status`, `label_status`, `return_method_state`).

### Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `query` | string | – | Free-text search across order name, customer email, and other fields. |
| `status` | string\[] | – | One or more of `open`, `partial`, `review`, `expired`, `processing`, `processed`, `closed`, `cancelled`. |
| `label_status` | string\[] | – | One or more of `new`, `pre_transit`, `in_transit`, `out_for_delivery`, `delivered`, `no_label`, `failure`. |
| `return_method_state` | string\[] | – | One or more of `new`, `pre_transit`, `in_transit`, `out_for_delivery`, `delivered`, `needs_scheduled`, `canceled`. |
| `outcome` | string | – | One of `exchange`, `upsell`, `refund`, `credit`, `exchange+refund`, `exchange+credit`, `credit+refund`. |
| `flagged` | boolean | – | `true` for only flagged returns, `false` for only unflagged. |
| `fraud_risk` | string | – | `has_unconfirmed_high_fraud_risk` or `has_confirmed_fraud_risk`. |
| `is_warranty` | boolean | – | `true` for warranty returns only, `false` to exclude warranty returns. |
| `day_limit` | integer | – | Restrict to returns updated within the last N days. |
| `sort_by` | string | `createdAt` | One of `returnId`, `orderName`, `returnStatus`, `labelStatus`, `createdAt`, `email`, `returnMethod`, `outcome`. |
| `sort_direction` | string | `desc` | `asc` or `desc`. |
| `page` | integer | `1` | Page number. |
| `limit` | integer | `25` | Page size, max `100`. |

### Example prompts

> "Show me the most recent 10 returns flagged for review."

> "List returns delivered in the last 7 days that haven't been processed yet."

***

## Get Return Details

**Tool name:** `get-return-tool`  ·  **Read-only**  ·  **Permissions:** `list-returns` or `manage-returns`

Fetch full detail for a single return, including order info, state, customer, line items, refund/exchange resolution, and notes. Renders an interactive card with action buttons for Process, Cancel, Close, Reject, and Timeline.

### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `return_id` | integer | yes | The Loop return ID. |

### Example prompts

> "Get return #1234 and summarize what's happening."

> "Pull up the details for the return I just flagged."

***

## Get Return Timeline

**Tool name:** `get-return-timeline-tool`  ·  **Read-only**  ·  **Permissions:** `list-returns` or `manage-returns`

Retrieve the chronological event timeline for a return — creations, state changes, label generation, shipping events, processing actions, customer notifications, and manual merchant actions. Large event payloads are truncated automatically.

### Parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `return_id` | integer | required | The Loop return ID. |
| `page` | integer | `1` | Page number. |
| `limit` | integer | `50` | Page size, max `200`. |

### Example prompts

> "What happened with return #1234? Walk me through the timeline."

> "When was the label for this return generated?"


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.