🧭 Overview
Loop Anywhere is a set of API-driven capabilities that allow you to push commerce data into Loop from any source. Whether your data lives in a commerce platform, ERP, OMS, or custom system, Loop Anywhere provides the APIs to bring it all together and power your returns experience.Why It Matters
Loop needs commerce data—orders, products, customers—to power the returns experience. With Loop Anywhere, you control how that data gets into Loop, giving you flexibility over the source, transformation, and timing of your commerce data sync.How It Works
Loop Anywhere integrations handle two directions of data flow between your systems and Loop:| Direction | Description |
|---|---|
| Inbound (to Loop) | Extract commerce data from your platform (the Source of Truth), normalize it, and push it into Loop |
| Outbound (from Loop) | Listen for return events from Loop via webhooks, then execute outcomes (refunds, exchanges, restocks) back in your platform |
🏗️ Integration Architecture
Loop Anywhere integrations are organized into four functional “buckets.” Each bucket represents a distinct phase of the integration, and together they form a complete returns operation.| Bucket | Purpose | Data Flow |
|---|---|---|
| I. Push Commerce Data | Populate Loop with products, orders, and related data | Platform → Loop |
| II. Get Return Data | Receive notifications when returns are created or updated | Loop → Your Systems |
| III. In-Flight Management | Manage active returns (process, flag, annotate) | Your Systems → Loop |
| IV. Outcome Execution | Execute refunds, exchanges, and restocks | Loop → Platform |
Build in order. These buckets are designed to be implemented sequentially. Bucket I is a prerequisite for everything else—Loop can’t create returns without order data. Buckets II-IV can be built in parallel once data is flowing.
📦 Bucket I: Push Commerce Data to Loop
The first step is populating Loop with the commerce data it needs to power the returns experience. Your platform acts as the Source of Truth, and Loop uses this data to enable returns.For complete API documentation on all Commerce Data endpoints, see the Commerce Data guide.
Data Types and Sync Order
Not all data types are required for every integration. The table below shows what’s needed based on the return outcomes you want to support.| Data | Required For | Notes |
|---|---|---|
| Products & Variants | All returns | Must be synced before orders. Store the returned id for mapping. |
| Orders | All returns | Reference Loop Product IDs in line items. Sync at least your return policy window back. |
| Customers | All returns | Can be created automatically when orders are pushed, or synced independently. |
| Locations | Exchanges | Required if offering exchanges. Represents warehouses and fulfillment centers. |
| Inventories | Exchanges | Stock levels per variant/location. Required to prevent overselling on exchanges. |
| Collections | Advanced rules | Optional. Useful for defining exchange eligibility rules by product grouping. |
ID Mapping Requirement
When you create a product in Loop, the API returns anid. Your integration must store this ID mapped to your platform’s external product ID. The same applies to variants. This mapping is used when:
- Creating orders (line items reference Loop Product IDs)
- Syncing inventory (keyed by Loop Variant ID + Location ID)
- Processing exchanges (matching items across systems)
| Your Platform | Loop |
|---|---|
platform_product_id | id (from Loop product) |
platform_variant_id | id (from Loop variant) |
Initial Sync vs. Ongoing Sync
Initial Sync (Historical Backfill) Before launching, you need to backfill historical data so customers can return recent orders. At minimum, sync orders going back to match your return policy window (e.g., 30, 60, or 90 days).Sync Products & Variants
Push your product catalog. Store the returned Loop IDs in your mapping table.
Sync Locations (if offering exchanges)
Create location records for warehouses and fulfillment centers.
| Event in Your Platform | Action |
|---|---|
| New order placed | Push order to Loop |
| Product created/updated | Sync product to Loop |
| Order shipped (fulfillment) | Update order fulfillments in Loop |
| Inventory changed | Update inventory in Loop |
| Order refunded (outside Loop) | Update order refunds in Loop |
📡 Bucket II: Get Return Data
Once returns are flowing through Loop, your systems need to know about them. This bucket is about listening—receiving notifications when customers initiate returns, when return status changes, and when returns are finalized.For complete documentation on retrieving return data, see the Retrieving Return Data guide.
Option 1: Webhooks
Loop can push return events to your systems in real time via webhooks. Subscribe to the events you care about and take action accordingly.| Webhook | When It Fires | Common Actions |
|---|---|---|
| return.created | Customer initiates a return | Create RMA in ERP, update order status, notify warehouse |
| return.updated | Return state changes | Update internal records, sync status to other systems |
| return.closed | Return finalized (processed or cancelled) | Trigger outcome execution (Bucket IV) |
| label.created | Shipping label generated | Capture tracking number, update ASN |
| restock.requested | Restock triggered in Loop | Increment inventory in WMS/ERP |
Option 2: API Polling
You can poll Loop’s APIs on a schedule to check for return activity. This approach gives you full control over when and how often you pull data.| API | Use Case |
|---|---|
| Detailed Returns List | List returns filtered by created_at, updated_at, or state |
| Get Return Details | Fetch full details for a specific return |
| Advanced Shipping Notice | Pull packages by tracking status or timeframe |
🔧 Bucket III: In-Flight Management
Loop provides APIs to manage returns while they’re in progress. This is useful when another system—like your WMS, ERP, or a warehouse inspection workflow—needs to trigger actions on a return before it closes.For complete documentation on return actions, see the Actioning on Returns guide.
Common Use Cases
| Scenario | API Action | Description |
|---|---|---|
| Warehouse confirms receipt | Process Return | Finalize the return and trigger outcomes |
| Item fails inspection | Flag Return | Pause automated processing for manual review |
| Customer requests cancellation | Cancel Return | Cancel the return; items become returnable again |
| Internal note needed | Create Return Note | Add audit trail or context from external systems |
| Item not received | Remove Line Items | Remove items and process remaining return |
Inspection workflows: For high-value items that require physical inspection before approval, your warehouse or ERP can call the Process Return API only after inspection passes. This keeps Loop in sync with your internal approval flow.
Processing Triggers
Returns can be processed (finalized) in several ways:- Automatically: Based on Loop’s configured processing events (e.g., label scanned, package delivered)
- Via API: Your integration calls the Process Return API after external confirmation
- Manually: A team member processes the return in Loop’s admin
return.closed webhook, which kicks off outcome execution (Bucket IV).
💰 Bucket IV: Outcome Execution
When a return is processed and closed, Loop provides all the information needed to execute the outcome—what type of resolution, how much, and for which items. Your systems handle the actual execution. This is where the integration comes full circle: Loop tells you what and when; your platform handles how.Delivering Outcomes
| Outcome | What Loop Provides | What You Do |
|---|---|---|
| Refund | Refund amount, line items, destination (original payment or store credit) | Refund to original payment method via payment gateway, or issue store credit/gift card |
| Exchange | New items selected, shipping address | Create new order in your commerce platform for fulfillment |
| Restock | Items to restock, quantities | Increment inventory in WMS or ERP |
Reconciliation: Closing the Loop
After executing an outcome in your external system, the data in Loop may become stale. Reconciliation ensures Loop’s records stay accurate—this matters if a customer returns additional items from the same order later.This reconciliation happens through the same Commerce Data APIs used in Bucket I. Your ongoing sync should catch these updates automatically if it’s listening for changes in your platform.
| After This Happens | Sync This Back to Loop |
|---|---|
| Refund executed | Update the order’s refunds |
| Exchange order created | Push the new order to Loop (so it can be returned later) |
| Inventory restocked | Update inventory levels |
| Order fully resolved | Update order status to archived |
⚠️ Technical Considerations
When building your integration, keep these implementation details in mind.| Consideration | Requirement |
|---|---|
| Monetary Values | All prices must be in minor units (cents). $10.00 → 1000 |
| Date Formatting | Use RFC 3339 / ATOM format without milliseconds: YYYY-MM-DDTHH:mm:ss+00:00 |
| Order Status Mapping | Map your platform’s statuses to Loop’s allowed values: active, archived, cancelled, unknown |
| Sync Order | Always sync Products before Orders |
✅ Conclusion
Loop Anywhere gives you full control over how commerce data flows into Loop and how return outcomes flow back to your systems. By working through the four buckets—pushing commerce data, getting return data, managing in-flight returns, and executing outcomes—you can build a complete returns integration tailored to your platform and business needs.📚 Related Resources
Commerce Data APIs
Detailed guide for syncing products, orders, customers, and more into Loop.
Retrieving Return Data
How to access return data via APIs and webhooks.
Actioning on Returns
Process, flag, cancel, and annotate returns via API.
Webhook Reference
Full documentation on Loop’s webhook topics and payloads.