Loop Anywhere

This guide assumes you have API access and the necessary permissions. Loop Anywhere integrations require coordination with Loop’s team during onboarding. Contact your Loop point of contact, Merchant Success Manager, or [e-mail] to get started.

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

When is Loop Anywhere the right fit?

Use Loop Anywhere when you need to control how commerce data flows into Loop. Whether you’re integrating a single platform, consolidating data from multiple sources, or building a custom data pipeline, Loop Anywhere lets you bring that data into Loop and execute return outcomes back in your systems.

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

How you build this integration is flexible—it could be a custom service, an integration platform, direct API calls from your existing systems, or any approach that can make HTTP requests and receive webhooks.

---

🏗️ 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.

Products must be synced before Orders. Loop assigns internal IDs to products and variants. When syncing orders, line items must reference these Loop IDs—not your platform’s external IDs. You’ll need to maintain a mapping table.

ID Mapping Requirement

When you create a product in Loop, the API returns an id. 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).

1. Sync Products & Variants

   Push your product catalog. Store the returned Loop IDs in your mapping table.

2. Sync Orders

   Push historical orders, referencing Loop Product IDs in line items.

3. Sync Locations (if offering exchanges)

   Create location records for warehouses and fulfillment centers.

4. Sync Inventory (if offering exchanges)

   Push stock levels for each variant at each location.

5. Sync Collections (optional)

   Create collections and attach products for advanced exchange rules.

Ongoing Sync (Real-Time)

Once the initial data is in Loop, you need to keep it current. New orders, product updates, and inventory changes should flow to Loop as they happen.

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
Order cancelled	Update order in Loop with status: "cancelled" and cancelled_at (required for Checkout+ protection reversal)

Recommended approach: Subscribe to webhooks from your commerce platform that fire when data changes. Transform and push that data to Loop in real time. A daily reconciliation job can catch anything webhooks miss.

---

📡 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

Webhook Security: Always validate webhook signatures to ensure requests are genuinely from Loop. Loop includes a signature header with every webhook for verification.

You’ll need an endpoint to receive these webhooks—this could be a serverless function, an integration platform flow, or a dedicated endpoint in your service.

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

Combining approaches: Some integrations use webhooks for real-time responsiveness and scheduled polling for reconciliation. Choose the approach that fits your architecture and reliability requirements.

---

🔧 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

Once processed, Loop fires the 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

Exchanges require additional data in Loop. To support exchanges, you’ll need to sync Locations and Inventories (see Bucket I) so Loop knows what’s available.

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

---

🛡️ Bucket V: Checkout+ API Integration

Checkout+ is Loop’s order protection product — covering returns, shipping issues, or both — directly at checkout via the Checkout+ API.

Checkout+ is not enabled by default. To get started, reach out to [e-mail] to enable it for your account.

Sync order cancellations. When a Checkout+ protected order is cancelled on your platform, update it in Loop with status: "cancelled" and cancelled_at so protection coverage is reversed. Both fields are required — see Cancelling Protected Orders in the Checkout+ guide.

For full integration details — including the API contract, platform-specific guidance for WooCommerce, BigCommerce, and headless stores, and code examples — see the Checkout+ API Integration Guide.

---

⚠️ 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. When setting status to cancelled, also include cancelled_at (RFC 3339 / ATOM, no milliseconds).
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 five buckets—pushing commerce data, getting return data, managing in-flight returns, executing outcomes, and offering order protection with Checkout+—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.