Retrieving Return Data
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 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).
Note: 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 Case | Recommended Option |
|---|---|
| Real-time updates | Return Webhook |
| Bulk data export/reporting | Detailed Returns List |
| Drill-down on a single return | Get Return Details |
| Pull packages by tracking status or timeframe | Advanced 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.
Tip: 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:
| Parameter | Type | Description | Options/Example |
|---|---|---|---|
from | string | The start date and time for the returns list. | "2022-01-01T00:00:00.000Z" |
to | string | The end date and time for the returns list. | "2022-03-31T23:59:59.000Z" |
filter | enum (string) (default: created_at) | The date used to filter results. | created_at, updated_at |
state | enum (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
idfor 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:
| Parameter | Type | Description |
|---|---|---|
return_id | integer | The unique identifier associated with the return. |
order_id | integer | The unique identifier associated with the order. |
order_name | string | The 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:
| Parameter | Type | Description | Options/Example |
|---|---|---|---|
from | string | The start date and time for filtering packages. | "2022-01-01T00:00:00.000Z" |
to | string | The end date and time for filtering packages. | "2022-03-31T23:59:59.000Z" |
tracking_status | string | Filter 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.
🛡️ 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.