Skip to main content
This guide assumes your Loop plan includes the Happy Returns integration. For help enabling these features, contact your Loop point of contact or [email protected].

​
📝 Overview

The Happy Returns integration allows merchants to process returns that have been dropped off at Happy Returns Bars. Unlike standard mail returns, these items are consolidated at Happy Returns facilities before being shipped in bulk to your warehouse. This guide explains how to programmatically retrieve shipment data—specifically the Bag Barcode—to efficiently receive and process these returns in your warehouse.

​
How it works

  1. Drop-off: Customer drops item at a Return Bar (no packaging needed).
  2. Validation: Return Bar validates brand, color, and product type.
  3. Bagging: Item is placed in a clear polybag with a pre-printed QR code (Bag Barcode).
  4. Linking: Associate scans the customer’s RMA code to link it to the Bag Barcode.
  5. Processing: The return outcome typically processes ~12 hours later to allow for signal consolidation.
  6. Consolidation: Bags are aggregated at Happy Returns hubs and shipped to your warehouse (typically ~2x/week).

​
🆔 ID Reference

Understanding the IDs is crucial. You have two main options for scanning: Bag Barcodes (standard) or Loop Return IDs (requires configuration).
ID NameDescriptionContext
Bag BarcodeThe pre-printed QR code on the polybag (e.g., HR200250DB9E).Standard scanning method. Links to the return via package_reference.
Loop Return IDThe internal Loop ID (e.g., 12345).Option: Can be printed on the bag label if enabled.
RMA IDCustomer-facing QR code (e.g., HRJYTQ5J).Used at drop-off, rarely in warehouse.
Shipment IDUnique ID for the consolidated shipment.Represents the box/pallet containing multiple bags.
Pro Tip: Print Loop ID on BagsContact your Loop point of contact or support to enable the “Happy Returns Loop Return ID Printed On Bags” setting. This prints the actual Loop Return ID on the bag’s label, allowing your warehouse to scan and find the return directly without mapping a Bag Barcode.When to use: If your WMS or 3PL cannot easily map external barcodes and prefers direct order/return lookups.

​
🚀 Use Cases

There are two primary ways to integrate Happy Returns data into your warehouse workflow:

​
1. Scan-to-Process (Real-Time)

In this workflow, your system listens for webhooks to “pre-alert” your WMS about incoming returns. When the shipment leaves the Happy Returns facility, you receive the data needed to recognize the Bag Barcode when it arrives. Workflow:
  1. Listen for the return.updated webhook.
  2. Extract the package_reference (this is the Bag Barcode) and id (Loop Return ID).
  3. Ingest the return information into your WMS before the box arrives.
  4. Scan the physical Bag Barcode on the polybag upon arrival to immediately identify and process the return.
{
  "topic": "return",
  "trigger": "return.updated",
  "id": 1001,
  "state": "open",
  "package_reference": "HR200250DB9E", // This is the Bag Barcode
  "scannable_id": "HR200250DB9E",      // Repurposed as Bag Barcode for HR returns
  "external_return_label_id": "SB-272610", // Box Barcode (shipping label)
  ...
}
The package_reference field in the return.updated webhook will contain the Happy Returns Bag Barcode once the shipment is in transit.

​
2. Bulk Receiving (Manifest Reconciliation)

Alternatively, you can pull a manifest of all items in a shipment before processing. This is useful for receiving entire pallets at once. Workflow:
  1. Listen for the happy.returns.shipment webhook (trigger: shipment.processed).
  2. Call the Get Shipment Items API using the happy_returns_shipment_id from the webhook.
  3. Ingest all returns in that shipment into your WMS preparation area.
{
  "data": [
    {
      "shipment_id": 12345,
      "happy_returns_shipment_id": "45678",
      "happy_returns_return_bag_barcodes": ["HR200250DB9E"],
      "loop_return_id": 1001,
      "sku": "SKU-123",
      ...
    }
  ]
}

​
🛠️ Technical Implementation

​
Webhook Setup

To receive real-time updates, configure the following webhooks in the Loop Admin or via API:
  • Topic: return | Trigger: return.updated
    • Why: Gives you the link between Loop Return ID and Bag Barcode (package_reference).
  • Topic: happy.returns.shipment | Trigger: shipment.processed
    • Why: Notifies you when a consolidated shipment is on its way to your warehouse.

​
API Polling (Alternative)

If you cannot use webhooks, you can poll the API to find new shipments:
  1. Call Get Shipments to find recent shipments.
  2. For each new shipment, Call Get Shipment Items to get the bag barcodes and return details.

​
📦 Post-Inspection Processing

By default, refunds are often issued at the time of drop-off. However, you can configure Loop to wait for warehouse inspection before refunding. Requirements:
  • Contact your Loop point of contact or support to enable “Manual Processing” mode.
  • Critical: The “Happy Returns Partial Return” shop setting must be disabled.
  • Workflow:
    1. Item arrives at warehouse.
    2. Warehouse inspects item.
    3. WMS calls Process Return API to accept/reject and trigger the refund.

​
❓ FAQ & Troubleshooting

What if a bag doesn’t scan? If a Bag Barcode doesn’t pull up a return, it might be a “Triage Item” (an item that wasn’t correctly linked at the Return Bar). Use the Happy Returns Shipments Report to look up the item manually. Why are there multiple Bag Barcodes? Rarely, a single return might be split into multiple bags. loops API responses provide happy_returns_return_bag_barcodes as an array. Scanning any of the barcodes in this array should validly identify the return. Can I utilize my existing Return Logic? Yes. If you use “Post-Inspection Processing,” you can apply your standard inspection workflows (e.g., grading, restocking fees) just as you would for a mail-in return.

​
🎉 Conclusion

The Happy Returns integration allows you to offer a premium, box-free return experience for your customers while maintaining efficient warehouse operations. By correctly mapping Bag Barcodes to Loop Return IDs—either via real-time webhooks or bulk API polling—you can ensure that every return is processed accurately and quickly. If you have questions about specific warehouse configurations or need to enable Manual Processing, please reach out to your Loop point of contact or support.