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

# Actioning on Returns

<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’s Return Actions APIs allow you to programmatically manage and update returns—such as processing, cancelling, flagging, closing, or adding notes—directly from your own systems. Use these endpoints to streamline operations, automate workflows, and keep your return data up to date.

Each action can be used individually to support specific business needs, whether you’re automating exception handling, updating return status, or integrating with your internal tools.

## ⚙️ 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).

<Note>
  Ensure your API key has the necessary permissions for the actions you intend
  to perform.
</Note>

## 🧭 Choosing the Right Action

Selecting the correct endpoint depends on your operational workflow. Use the list below to determine which API action best fits your use case:

* **[Process Return](#process-return):** Complete a return and trigger downstream actions (e.g., refunds, exchanges, store credits).
* **[Remove Line Items](#remove-line-items):** Remove one or more items from a return and immediately process/close the return (only for refund or store credit line items).
* **[Cancel Return](#cancel-return):** Cancel a return, allowing a customer to make another return with the same items.
* **[Close Return](#close-return):** Close a return without fulfilling any outcomes (such as exchanges or gift cards); items cannot be returned again.
* **[Flag Return](#flag-return):** Flag a return for manual review, preventing automated processing until a human reviews it in the Loop admin.
* **[Get Return Notes](#get-return-notes):** Retrieve internal notes for context or audit trails.
* **[Create Return Note](#create-return-note):** Add an internal note to a return for record-keeping.
* **[Create Return Deep Link](#create-return-deep-link):** Generate a link to access a return directly.
* **[Create Return Deep Link with QR Code](#create-return-deep-link-with-qr-code):** Generate a link and QR code for quick access to a return.

<Tip>
  **Best Practice:** Use these actions in combination with return data APIs and
  webhooks for a complete return management workflow.
</Tip>

***

## 🗂️ Return Lifecycle Actions

Actions in this section will finalize, close, or archive a return. Once used, the return is considered closed in Loop and cannot be further actioned except for read-only purposes.

### Process Return

Use the [Process Return](/api-reference/latest/return-actions/process-return) endpoint to complete a return and trigger downstream actions such as refunds, exchanges, or store credits. This is typically the final step after a return has been received and reviewed.

<Tip>
  Most returns can be processed automatically in Loop using [automated
  processing
  events](https://help.loopreturns.com/en/articles/1917249#return_outcomes)
  (like shipping label scans). Use the Process Return endpoint for advanced
  workflows—such as when a 3PL or WMS confirms receipt or inspection—to trigger
  outcomes based on external system events.
</Tip>

**When to use:**

* When you want to finalize a return and ensure all related actions (refund, exchange, etc.) are executed.

**Path Parameter:**

| Parameter   | Type    | Description                           |
| ----------- | ------- | ------------------------------------- |
| `return_id` | integer | The unique identifier for the return. |

**How it works:**

* The request requires only the `return_id` path parameter.
* The response is a boolean string (`"true"`) on success, or an error object if not processable.

<Note>
  See the [Process Return API
  docs](/api-reference/latest/return-actions/process-return) for full details.
</Note>

### Cancel Return

Use the [Cancel Return](/api-reference/latest/return-actions/cancel-return) endpoint to cancel a return in Loop. Canceling a return will allow a customer to make another return with the same items.

**When to use:**

* When you want to allow a customer to make another return with the same items by canceling the current return.

**Query Parameters:**

| Parameter   | Type    | Description                           |
| ----------- | ------- | ------------------------------------- |
| `return_id` | integer | The unique identifier for the return. |
| `reason`    | string  | (Optional) Reason for cancellation.   |

**How it works:**

* The request requires the `return_id` path parameter (and optional `reason`).
* The response provides the updated return status and confirmation of cancellation.

<Note>
  See the [Cancel Return API
  docs](/api-reference/latest/return-actions/cancel-return) for full details.
</Note>

### Close Return

Use the [Close Return](/api-reference/latest/return-actions/close-return) endpoint to close a return. Closing a return will not fulfill any outcomes such as exchanges or gift cards, and the items are not able to be used in a new return.

**When to use:**

* When you want to prevent any further actions on a return and ensure the items cannot be returned again.

**Query Parameters:**

| Parameter   | Type    | Description                           |
| ----------- | ------- | ------------------------------------- |
| `return_id` | integer | The unique identifier for the return. |

**How it works:**

* The request requires only the `return_id` path parameter.
* The response confirms closure and provides the final return status.

<Note>
  See the [Close Return API
  docs](/api-reference/latest/return-actions/close-return) for full details.
</Note>

***

## 🛠️ Return Modification Actions

Use these endpoints to update or flag returns that are still open and in progress.

### Remove Line Items

Use the [Remove Line Items](/api-reference/latest/return-actions/remove-line-items) endpoint to remove line items from a return and process the return.

<Warning>
  **Important:** This call will both remove the specified line items and immediately process/close the return. You can pass multiple `line_item_id` values (comma-separated) to remove several items at once, but you must be prepared for the return to be closed after this call.

  Currently, only line items tied to a refund or store credit outcome allow for line items to be removed programmatically.
</Warning>

**When to use:**

* When you need to update a return before it is finalized and are ready for the return to be closed after removing items.

**Parameters:**

| Parameter      | In    | Type    | Required | Description                                                             |
| -------------- | ----- | ------- | -------- | ----------------------------------------------------------------------- |
| `return_id`    | path  | integer | Yes      | The unique identifier for the return.                                   |
| `line_item_id` | query | string  | Yes      | The ID(s) of the line item(s) to remove (comma-separated for multiple). |

**How it works:**

* The request requires the `return_id` path parameter and one or more `line_item_id` query parameters.
* The response confirms which items were removed and provides the updated return object.

<Note>
  See the [Remove Line Items API
  docs](/api-reference/latest/return-actions/remove-line-items) for full
  details.
</Note>

### Flag Return

Flag a return in Loop for review. This will prevent automated processing and will require a human to go into the merchant admin in Loop and review this return.

**Query Parameters:**

| Parameter   | Type    | Description                           |
| ----------- | ------- | ------------------------------------- |
| `return_id` | integer | The unique identifier for the return. |
| `reason`    | string  | (Optional) Reason for cancellation.   |

**How it works:**

* The request requires the `return_id` path parameter (and optional `reason`).
* The response provides the updated return status and confirmation of cancellation.

<Note>
  See the [Flag Return API
  docs](/api-reference/latest/return-actions/flag-return) for full details.
</Note>

***

## 📝 Return Notes

These endpoints allow you to add and retrieve internal notes for returns, supporting record-keeping, audit trails, and team communication.

<Tip>
  Return notes are visible on the timeline of the return details page in the
  Loop admin, making them easily accessible for your team.
</Tip>

### Get Return Notes

Use the [Get Return Notes](/api-reference/latest/return-actions/get-return-notes) endpoint to retrieve notes associated with a return. Notes are useful for tracking internal comments, history, or audit trails.

**When to use:**

* When you need to fetch all notes for a specific return.

**Query Parameters:**

| Parameter   | Type    | Description                           |
| ----------- | ------- | ------------------------------------- |
| `return_id` | integer | The unique identifier for the return. |

**How it works:**

* The request requires only the `return_id` path parameter.
* The response returns an array of note objects with timestamps and authors.

<Note>
  See the [Get Return Notes API
  docs](/api-reference/latest/return-actions/get-return-notes) for full details.
</Note>

### Create Return Note

Use the [Create Return Note](/api-reference/latest/return-actions/create-return-note) endpoint to add a new note to a return. Notes help with internal communication and record-keeping.

**When to use:**

* When you want to add an internal comment or update to a return.

**Path Parameter:**

| Parameter   | In   | Type    | Required | Description                           |
| ----------- | ---- | ------- | -------- | ------------------------------------- |
| `return_id` | path | integer | Yes      | The unique identifier for the return. |

**Request Body:** (application/json, required)

| Field  | Type   | Required | Description              |
| ------ | ------ | -------- | ------------------------ |
| `note` | string | Yes      | The content of the note. |

**How it works:**

* The `return_id` path parameter is required.
* The request body must include a JSON object with a `note` field.
* The response confirms note creation and returns the updated notes list.

<Note>
  See the [Create Return Note API
  docs](/api-reference/latest/return-actions/create-return-note) for full
  details.
</Note>

***

## 🔗 Return Deep Link Actions

Use these endpoints to generate direct links or QR codes for accessing returns, making it easier to provide access to customers or internal teams.

### Create Return Deep Link

Use the [Create Return Deep Link](/api-reference/latest/return-actions/create-return-deep-link) endpoint to generate a direct link to a return for customer or internal access.

**When to use:**

* When you want to provide a quick-access link to a return for a customer or team member.

**Query Parameters:**

| Parameter   | Type    | Description                           |
| ----------- | ------- | ------------------------------------- |
| `return_id` | integer | The unique identifier for the return. |

**How it works:**

* The request requires the `return_id` path parameter.
* The response provides a direct URL to the return in Loop.

<Note>
  See the [Create Return Deep Link API
  docs](/api-reference/latest/return-actions/create-return-deep-link) for full
  details.
</Note>

### Create Return Deep Link with QR Code

Use the [Create Return Deep Link with QR Code](/api-reference/latest/return-actions/create-return-deep-link-with-qr-code) endpoint to generate a direct link and a QR code for a return.

**When to use:**

* When you want to provide a scannable QR code for quick access to a return (e.g., in warehouse or in-store settings).

**Query Parameters:**

| Parameter   | Type    | Description                           |
| ----------- | ------- | ------------------------------------- |
| `return_id` | integer | The unique identifier for the return. |

**How it works:**

* The request requires the `return_id` path parameter.
* The response provides both a direct URL and a QR code image for the return.

<Note>
  See the [Create Return Deep Link with QR Code API
  docs](/api-reference/latest/return-actions/create-return-deep-link-with-qr-code)
  for full details.
</Note>

***

## ✅ Conclusion

By leveraging these return action endpoints, you can fully customize and automate your returns workflow to fit your business needs. Use the right endpoint for each scenario—whether automating with Loop events or integrating with external systems like 3PLs or WMS. For best results, combine these actions with return data APIs and webhooks to create a seamless, robust return management experience for your team and customers.

***