Note: 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.

​
📝 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 in Loop Admin).

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

​
🧭 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: Complete a return and trigger downstream actions (e.g., refunds, exchanges, store credits).
  • Remove Line Items: Remove one or more items from a return and immediately process/close the return (only for refund returns).
  • Cancel Return: Cancel a return, allowing a customer to make another return with the same items.
  • Close Return: Close a return without fulfilling any outcomes (such as exchanges or gift cards); items cannot be returned again.
  • Flag Return: Flag a return for manual review, preventing automated processing until a human reviews it in the Loop admin.
  • Get Return Notes: Retrieve internal notes for context or audit trails.
  • Create Return Note: Add an internal note to a return for record-keeping.
  • Create Return Deep Link: Generate a link to access a return directly.
  • Create Return Deep Link with QR Code: Generate a link and QR code for quick access to a return.

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

​
🗂️ 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 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.

Note: Most returns can be processed automatically in Loop using automated processing events (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.

When to use:

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

Path Parameter:

ParameterTypeDescription
return_idintegerThe 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.

See the Process Return API docs for full details.

​
Cancel Return

Use the 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:

ParameterTypeDescription
return_idintegerThe unique identifier for the return.
reasonstring(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.

See the Cancel Return API docs for full details.

​
Close Return

Use the 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:

ParameterTypeDescription
return_idintegerThe 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.

​
🛠️ 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 endpoint to remove line items from a return and process the return.

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 returns with refund outcomes allow for line items to be removed.

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:

ParameterInTypeRequiredDescription
return_idpathintegerYesThe unique identifier for the return.
line_item_idquerystringYesThe 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.

See the Remove Line Items API docs for full details.

​
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:

ParameterTypeDescription
return_idintegerThe unique identifier for the return.
reasonstring(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.

See the Flag Return API docs for full details.

​
📝 Return Notes

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

Note: Return notes are visible on the timeline of the return details page in the Loop admin, making them easily accessible for your team.

​
Get Return Notes

Use the 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:

ParameterTypeDescription
return_idintegerThe 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.

See the Get Return Notes API docs for full details.

​
Create Return Note

Use the 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:

ParameterInTypeRequiredDescription
return_idpathintegerYesThe unique identifier for the return.

Request Body: (application/json, required)

FieldTypeRequiredDescription
notestringYesThe 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.

See the Create Return Note API docs for full details.

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

Use the 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:

ParameterTypeDescription
return_idintegerThe 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.

See the Create Return Deep Link API docs for full details.

Use the 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:

ParameterTypeDescription
return_idintegerThe 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.

See the Create Return Deep Link with QR Code API docs for full details.

​
✅ 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.