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 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 in Loop Admin).
If you want to utilize webhooks, you’ll need to set up a webhook subscription. See the webhook setup guide for step-by-step instructions.

​
🧭 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 CaseRecommended Option
Real-time updatesReturn Webhook
Bulk data export/reportingDetailed Returns List
Drill-down on a single returnGet Return Details
Pull packages by tracking status or timeframeAdvanced 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.
Best Practice: Many merchants combine webhooks for real-time needs with periodic API pulls for reconciliation or reporting.

​
📡 APIs

​
Detailed Returns List

Use the Detailed Returns List API 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.
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.
Query Parameters:
ParameterTypeDescriptionOptions/Example
fromstringThe start date and time for the returns list."2022-01-01T00:00:00.000Z"
tostringThe end date and time for the returns list."2022-03-31T23:59:59.000Z"
filterenum (string) (default: created_at)The date used to filter results.created_at, updated_at
stateenum (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.
See the Detailed Returns List API docs for full details.

​
Get Return Details

Use the Get Return Details API to get the details of a specific return based on a return’s ID, an order name, or a Shopify 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 Shopify order.
  • You want to display or view the details for a single return.
Query Parameters:
ParameterTypeDescription
return_idintegerThe unique identifier associated with the return.
order_idintegerThe unique identifier associated with the order.
order_namestringThe Shopify order name.
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.
See the Get Return Details API docs for more info.

​
Advanced Shipping Notice

The Advanced Shipping Notice API 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:
ParameterTypeDescriptionOptions/Example
fromstringThe start date and time for filtering packages."2022-01-01T00:00:00.000Z"
tostringThe end date and time for filtering packages."2022-03-31T23:59:59.000Z"
tracking_statusstringFilter 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.
See the Advanced Shipping Notice API docs for full details on parameters and response structure.

​
🔔 Webhooks

For real-time updates, subscribe to the 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. Security: Always validate webhook signatures to ensure authenticity. Reliability: Loop will retry webhooks on failure—see 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 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).
  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 or contact our support team at support@loopreturns.com.