> ## 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 — Actions

> Take actions on returns through the Loop MCP Server.

These tools mutate return state. They're marked as **destructive** in the MCP protocol so well-behaved clients (Claude Desktop, Cursor, VS Code Copilot) prompt the merchant for confirmation before executing them.

<Warning>
  Reject, cancel, close, and process actions are **irreversible**. The MCP server's instructions tell the assistant to confirm before executing — but the responsibility for that confirmation ultimately sits with the client.
</Warning>

After most actions, the tool returns a Generative UI card showing the new return state alongside a short text summary, so the merchant can see immediately what happened.

***

## Add Return Note

**Tool name:** `add-return-note-tool`  ·  **Destructive**  ·  **Permissions:** `manage-returns`

Add an internal staff note to a return. Notes are visible to other staff members in the Loop Admin and do not impact return state.

### Parameters

| Parameter   | Type    | Required | Description                            |
| ----------- | ------- | -------- | -------------------------------------- |
| `return_id` | integer | yes      | The Loop return ID.                    |
| `note`      | string  | yes      | Note content, up to 17,000 characters. |

### Example prompt

> "Add a note to return #1234 that the customer called and wants to switch to a refund."

***

## Flag Return

**Tool name:** `flag-return-tool`  ·  **Destructive**  ·  **Permissions:** `manage-returns`

Flag a return for manual review with optional QC reasons and a comment. The return must be in a flaggable state and not already flagged. At least one reason **or** a non-empty comment is required.

### Parameters

| Parameter   | Type       | Required | Description                                                                                  |
| ----------- | ---------- | -------- | -------------------------------------------------------------------------------------------- |
| `return_id` | integer    | yes      | The Loop return ID.                                                                          |
| `reasons`   | integer\[] | –        | QC reason IDs. Common reasons: `1` = Incorrect item, `2` = Damaged item, `3` = Missing item. |
| `comment`   | string     | –        | Free-text explanation. Required if `reasons` is empty.                                       |

### Example prompt

> "Flag return #1234 for damaged item — note that the box arrived crushed."

***

## Unflag Return

**Tool name:** `unflag-return-tool`  ·  **Destructive**  ·  **Permissions:** `manage-returns`

Mark a flagged return as reviewed (unflag it). The return must currently be flagged.

### Parameters

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

### Example prompt

> "Unflag return #1234 — I've reviewed it and it's fine."

***

## Reject Return

**Tool name:** `reject-return-tool`  ·  **Destructive**  ·  **Permissions:** `manage-returns`

Reject a return. This rejects all line items and closes the return. The return must be in `open`, `partial`, `expired`, or `review` state.

<Warning>
  This action cannot be undone.
</Warning>

### Parameters

| Parameter   | Type    | Required | Description                                                        |
| ----------- | ------- | -------- | ------------------------------------------------------------------ |
| `return_id` | integer | yes      | The Loop return ID.                                                |
| `reason`    | string  | –        | Optional rejection reason. Recorded as a staff note on the return. |

### Example prompt

> "Reject return #1234 — the items aren't eligible per our policy."

***

## Cancel Return

**Tool name:** `cancel-return-tool`  ·  **Destructive**  ·  **Permissions:** `manage-returns`

Cancel a return and any associated exchanges, refunds, or gift cards. The return must be in `open`, `partial`, or `expired` state.

<Warning>
  This action cannot be undone.
</Warning>

### Parameters

| Parameter   | Type    | Required | Description                    |
| ----------- | ------- | -------- | ------------------------------ |
| `return_id` | integer | yes      | The Loop return ID.            |
| `comment`   | string  | –        | Optional cancellation comment. |

### Example prompt

> "Cancel return #1234 — the customer changed their mind."

***

## Close Return

**Tool name:** `close-return-tool`  ·  **Destructive**  ·  **Permissions:** `manage-returns`

Close a return by marking it as processed without taking any action in Shopify. **No** refunds, exchanges, or gift cards are issued.

<Warning>
  This action cannot be undone. The customer will not be able to interact with the return after it is closed.
</Warning>

### Parameters

| Parameter   | Type    | Required | Description                                                 |
| ----------- | ------- | -------- | ----------------------------------------------------------- |
| `return_id` | integer | yes      | The Loop return ID.                                         |
| `comment`   | string  | –        | Optional comment explaining why the return is being closed. |

### Example prompt

> "Close return #1234 without issuing anything — we already handled this manually."

***

## Process Return

**Tool name:** `process-return-tool`  ·  **Destructive**  ·  **Permissions:** `manage-returns` or `manage-point-of-sale`

Process a return. This kicks off background jobs that issue exchanges, refunds, and gift cards. Processing happens **asynchronously** — the tool returns immediately, but downstream resolution may take a few moments.

<Info>
  The return must be in a processable state (typically after a label scan or after the merchant has reviewed line items).
</Info>

### Parameters

| Parameter          | Type      | Required | Description                                                                                            |
| ------------------ | --------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `return_id`        | integer   | yes      | The Loop return ID.                                                                                    |
| `exchange_actions` | object\[] | –        | Override exchange behavior per line item. Each entry: `{ id: integer, disposition?: string }`.         |
| `restock_actions`  | object\[] | –        | Override restock behavior per line item. Each entry: `{ id: integer, restock_location_id?: integer }`. |

Omit `exchange_actions` and `restock_actions` to use the default behavior for every line item.

### Example prompt

> "Process return #1234 with the defaults."