This article details how merchants can process Happy Returns shipments in their warehouses and shipping facilities, including how Happy Returns' Return Vision fraud audits affect Loop returns.

Use the menu on the left to quickly navigate this article.

The Happy Returns life cycle is as follows:

After an item is physically dropped off for return at a Happy Returns return bar…

• Each return is placed in a bag, which is assigned a bag barcode.

• In some cases, multiple items are split into multiple bags despite being a part of a single return.

• Bags are shipped to a Happy Returns facility.

• Bags are consolidated into pallets and prepared for shipment to the merchant's warehouse.

When Happy Return shipments depart their facility for the warehouse destination…

• Happy Returns notifies Loop that an outbound shipment containing the return is en route to the merchant's warehouse.

• Loop triggers the return.updated webhook.

• The return.updated webhook now includes the bag barcode ID in the package_reference field.

• The merchant's warehouse staff scans the QR code on the Happy Returns polybag to identify the item.

• The merchant can now inspect and process the returns.

If Happy Returns doesn't receive all items in the return during the customer's initial dropoff…

• Loop is notified that items are missing and waits for a 24-hour grace period.

• If after this grace period items are still missing, Loop will adjust the refund to be a partial refund.

• If the return with missing items is an exchange, Loop will still process the return as normal, creating an exchange order in Shopify.

To fully support Happy Returns, merchants' facilities must have a way to scan QR codes. Happy Returns uses QR codes to identify their bags, and Loop uses these QR codes to associate items with Loop returns.

Note: Merchants that don't have a way to scan Happy Returns QR codes will have to enter the bag barcode ID into their WMS systems manually.

Depending on the merchant's consolidated shipment volume and what types of shipments their warehouse can receive, Happy Returns shipment will either be delivered in consolidated gaylords or individual boxes. Within the gaylords or boxes will be polybags with the Happy Returns bag barcode identifier on them in QR code format, as shown below.

When will your customer's return outcome be issued?

This depends on your return policy's processing event and whether your account has Post-Inspection Outcome enabled.

Default behavior (most merchants): Return outcomes — refunds, exchanges, store credit — are issued within 24 hours of the shopper dropping off their item at a Happy Returns bar. This applies when your return policy processing event is set to In Transit.

If your return policy uses any other automated processing event, return outcomes for Happy Returns will be delayed until the item is manually processed. You can use a Workflow to override this if you want outcomes to fire at drop-off.

Post-Inspection Outcome (available on request): If your account has Post-Inspection Outcome enabled, return outcomes are held at drop-off and only issued after your warehouse has inspected and approved the returned item via the Loop Public API.

To use this mode, you must:

1. Coordinate with Happy Returns to configure your account for inspection-based processing

2. Have your warehouse set up to call the Loop Public API to release return outcomes post-inspection

3. Contact your Loop account team to enable the feature

Important: If Post-Inspection Outcome is enabled but your warehouse has not set up the Loop Public API integration, Happy Returns returns will not process. Contact your Loop account team before enabling.

Note: If your account already issues outcomes this way, Happy Returns' Return Vision fraud audits (below) don't change anything for you — Loop uses your existing inspection-based flow rather than layering on a second hold.

You can also use Workflows to configure which Happy Returns returns get held vs. processed automatically:

• To hold outcomes for inspection: Condition = Return method is Happy Returns → Action = Process = Manual Processing

• To allow drop-off processing when your policy is otherwise set to Manual: Condition = Return method is Happy Returns → Action = Process = In Transit

Merchants can use Loop's webhooks to determine if a return was made using Happy Returns as well as learn when the return is on its way to their warehouse.

Both of the webhook methods below can be used to receive Happy Returns return updates.

Return.updated

• For merchants that are already using the Return webhook, Loop recommends using Return.updated to fetch Happy Returns return data.

  Note: This webhook will trigger for all return updates for the merchant, not just Happy Returns.

• This webhook will include a bag barcode ID that corresponds to the QR code placed on the Happy Returns polybag containing the item.

• When Loop receives the Happy Returns shipping notice, the package_reference field is set as the bag barcode ID.

• Merchants can determine if a return was shipped using Happy Returns by confirming that both the scannable_id and the package_reference are the Happy Returns bag barcode ID.

Happy Returns Shipment Processed Webhook

• For merchants that aren't subscribed to Return.updated and just want Happy Returns shipment info, Loop recommends using the Happy Returns Shipment Processed Webhook.

• This webhook is fired when a Happy Returns shipment is processed in Loop. Happy Returns shipments will process once consolidated items have left the Happy Returns facility for the warehouse destination.

• After receiving this webhook, merchants can call Get Shipment Items to retrieve all Happy Returns bag barcodes and Loop Return IDs that are part of the shipment.

For merchants who aren't able to or don't want to subscribe to webhooks, Loop recommends using the Get Shipments and Get Shipment Items API endpoints. Using these endpoints, merchants can periodically retrieve shipment and line item data.

This is also a helpful tool for merchants who have experienced downtime and need to reconcile missed shipments.

Tip: Happy Returns provides Loop with the information needed to process returns once the shipment is on its way to a merchant's warehouse destination, so it's wise to poll the API endpoints frequently.

Get Shipments

Note: This endpoint is used for querying shipments and does not contain item data.

To get shipment data using this endpoint, choose a start and end timestamp and poll the API to return all shipments between those timestamps.

Merchants may also subscribe to the aforementioned Happy Returns Shipment Processed Webhook to see which shipments have been processed.

Get Shipment Items

After retrieving shipment data, merchants can use this endpoint to get the individual line items for each shipment pulled from the Get Shipments endpoint.

Each Happy Returns line item will have a corresponding bag barcode.

Loop supports Happy Returns’ Return Vision, a physical fraud-audit program where flagged returns are pulled for a rapid inspection at a Happy Returns hub before your return outcome issues. A person inspects the item and, for select products, compares it against your product photos, catching things like a wrong logo, mismatched fabric, or a mislabeled tag. If your account is enrolled, Loop puts the return into a hold while it’s under audit, then processed it like normal or moves it to Needs Review based on the result.

Note: Return Vision runs through Happy Returns’ hub network and is separate from Loop’s own fraud tools. Enroll through your Happy Returns account team — Happy Returns decides whether Return Vision is active for your account. If you’re already set up with Happy Returns through Loop, the Loop-side integration is automatically in place; there’s no separate step to turn it on from the Loop side.

Note: If your account is using Post-Inspection Outcome (see “Processing Happy Returns shipments” above), Return Vision doesn’t change your flow — Loop uses your existing inspection-based process instead of layering on a second hold.

A return under Return Vision audit is held — it is not the same as a return sitting in Needs Review. Only a failed audit moves a return into Needs Review; a return that's still waiting on its audit result is simply on hold.

Important: If any line item in a return fails its Happy Returns audit, Loop holds the entire return for review — Loop doesn't support issuing a partial outcome for just the passing items today.

Inspection photos and the pass/fail result appear directly on the affected line item in the return, using the same line-item image display Loop already uses elsewhere — no separate lookup is needed.

You can also follow an audit's progress in the return's history feed, below the line items: look for "A hold was placed on this return for: Happy Returns Audit" when the hold starts, and "Happy Returns flagged this return for a hub inspection" — which includes a confirmation code and lists the specific items pulled for inspection — once Happy Returns' hub picks the return up.

• The Happy Returns Bag Barcode corresponds to the package_reference field in Loop's Return.updated webhook.

• The Happy Returns Bag Barcode corresponds to the happy_returns_return_bag_barcodes in the response payload of the Get Shipment Items API endpoint.

This often corresponds to the Tracking number field in the merchant's WMS.

Note: If package_reference is NULL, this means there is no scannable ID and no label tracking number and that the necessary data to scan the item does not exist.

The Happy Returns RMA ID and Bag Barcode are searchable within the Loop returns list and the associated return will show up if those values are linked to a Loop return. Those values are found on the return detail page, as shown below.

Once Happy Returns has created a shipment and it has been shipped from the HR consolidation hub, the merchant will be notified via email and the contents of the shipment can be viewed in the Inventory Detail table in the Loop admin. This will contain all items in the shipment with their associated Loop return ID. The “Extra Items” table contains any items not associated to a return.

What data is provided to the warehouse for each Happy Returns shipment? A full list of Happy Returns shipments and items within those shipments can be found in Loop's webhooks and APIs as detailed above. If you're listening to webhooks for real-time Happy Returns updates, Loop's Return.updated and Happy Returns Shipment Processed webhooks will contain shipment and item information. If you’re polling Loop’s APIs, you can use the Get Shipments and Get Shipment Items API endpoints to get shipment and item information.

What are some reasons the bag barcode doesn’t load the return in my WMS at the warehouse? If your WMS is integrated with Loop and supports the Happy Returns integration, most Happy Returns bags should scan but there are a few reasons some may not:

• The bag could have been tagged as an extra/triage item by Happy Returns, which means that the polybag is not associated with a return. This can happen if an item is not correctly checked in at a Returns bar or the proper Happy Returns label is not attached to the polybag. For details on triage items, see Happy Returns' documentation. Triage items within a shipment can be identified in Loop’s Happy Return analytics page.

• In some cases, Happy Returns issues multiple bag barcodes for the return. In this case, the Happy Returns RMA ID is the fallback, which will be unscannable. This is a feature enabled in Happy Returns and will not apply to most merchants.

What is Return Vision? Return Vision is Happy Returns' physical fraud-audit program. Flagged returns are pulled for inspection at a Happy Returns hub before your outcome issues. See Happy Returns' Return Vision overview for more on the program itself.

Why is a return being held with an "In Review by the Happy Returns audit process" message — is that the same as Needs Review? No — a return under audit is on hold, which is a different state from Needs Review. The reasons listed in the banner are why Happy Returns pulled the return for a hub inspection; they don't mean anything is wrong yet. No action is needed on your end while it's held. The return only moves into Needs Review if the audit actually fails.

A return failed its Happy Returns audit and is now in Needs Review — what do I do? Review the reasons and inspection photos attached to the flagged line item(s), then either reject the return or click Mark Reviewed at the top of the return to clear it, based on your own judgment.

Can I get a partial refund if only one item in a multi-item return fails the audit? Not today — Loop holds the entire return for review if any line item fails, since Loop doesn't support splitting outcomes across line items.

Does Return Vision apply if I already have Post-Inspection Outcome set up with Happy Returns? No — if your account already issues outcomes based on Happy Returns' standard hub inspection, that existing flow is what runs. Return Vision doesn't add a second hold on top of it.

Please reach out to support@loopreturns.com with any additional questions.