Happy Returns Integration

Julie  Houlton
Julie Houlton
  • Updated

In this article:

Happy Returns-1.png

Happy Returns-2.png


The Happy Returns integration is available to customers with an online store partnered with Whiplash and supports two return methods:

  • Returns through Return Bars in retail stores. In this scenario, items are grouped and sent in bulk to Ryder Whiplash in pallets.
  • Consumer-mailed returns, where items are sent directly to the Whiplash warehouse.

Once the return is shipped back, Happy Returns provides the return information required to create Return Merchandise Authorizations (RMAs) for more efficient processing in the warehouse. Then, after Whiplash receives the returned item and has processed the return, a line-item level confirmation is sent to Happy Returns.

Happy Returns supports refunds and exchanges.



Customers can leverage the Happy Returns app for their online store for a comprehensive e-commerce returns management solution that is tied to Whiplash. Benefits include:

  • Consumers can initiate returns from the store.
  • An easy returns process that allows consumers to either:
    • Print the label and mail the item to the Whiplash warehouse.
    • Drop off the item in-person via Happy Returns’ nationwide network of Return Bars.
  • Cost savings with aggregated shipping of bulk return items from Return Bars.
  • Real-time return creation sync that communicates with Whiplash and adjusts inventory levels every time a return is created.
  • Increased warehouse efficiency by receiving returns information provided by Happy Returns.


How it works

Happy Returns allows customers to set two different return workflows, allowing the consumer flexibility on how they prefer to return the product and how the refund can be processed:

  • Return Bar flow: The consumer takes the items to a Return Bar location, where the Return Bar Associate verifies the items, approves the refund, and packs them for shipment.
  • Mail flow: The consumer receives a shipping label to return the items by mail. In this flow, the refund can be executed almost as soon as it’s mailed (i.e., “upon first carrier scan”) or after the items are verified at the distribution center/warehouse (i.e., “by warehouse inspection”).

Return Bar Flow

  1. The consumer initiates a return on the online store.
  2. The consumer is redirected to a Happy Returns Return Bar location to complete the return.
  3. The consumer drops off items at a Return Bar.
  4. Happy Returns aggregates items dropped off at Return Bars and sends them to Ryder Whiplash in pallets and sends return data to Ryder Whiplash via webhook.
  5. Return ship notices are created within the Whiplash application at the consumer return level.
  6. Ryder Whiplash warehouse receives pallets from Happy Returns and scans the cartons and the items within to confirm receipt of return Ship Notices.
  7. Ryder Whiplash sends item-level confirmation of the return to Happy Returns via webhook.
  8. Happy Returns compares the return items report with the RMA and closes the return.

The following diagram illustrates this flow:



Mail Return Flow

  1. The consumer initiates a return on the online store.
  2. The consumer is redirected to the Happy Returns site to complete the return.
  3. The consumer gets a Shipping Label, prints it, and uses it to mail items to the Ryder Whiplash warehouse.
  4. Happy Returns sends return data to Ryder Whiplash (via webhook). If the customer has enabled "return at first carrier scan" on Happy Returns, the refund is automatically approved.
  5. Ryder Whiplash creates online return Ship Notices.
  6. Ryder Whiplash warehouse identifies the package by scanning its ship box bar code number and receives entry of ship notices.
  7. Ryder Whiplash sends an online line-item-level confirmation to Happy Returns. Happy Returns compares the return items report with the RMA. If the refund type is a warehouse inspection refund and items meet the required refund standards, Happy Returns approves the refund.
  8. Happy Returns closes the return.

The following diagram illustrates this flow:


Return information shared with Whiplash

Happy Returns collects and sends the following return details to Whiplash for each return:

  • Original order number
  • Product name
  • Date of the return
  • Location of the return (if returned in-store)
  • Refund type (refund, store credit)


Setup instructions

These two steps explain how to set up an integration between a customer's online store, Whiplash, and Happy Returns. Complete the steps in the order listed below.


Number1.png  Customer completes the following:

1.   Contacts the Ryder Whiplash Customer Success Manager (CSM) and provides:

    • Happy Returns planned launch date.
    • The type of returns flow to be enabled.
Customer will need to provide the CSM with their two Happy Returns Retailer IDs once they receive them. One ID is used in the sandbox environment to enable testing and the second is used in the production environment.

2.   Sets up a Happy Returns account if the customer doesn’t already have one and determines the returns flow that will work best. Customer receives a Happy Returns Retailer ID from Happy Returns.

3.   Contacts the Happy Returns representative to enable the Ryder Whiplash integration by granting permission to the 'ryder-ecommerce' token.

Note: This is the same process for sandbox and production instances.

- or -

The customer can email Happy Returns at retailersupprt@happyreturns.com, to notify them that the customer is with Ryder Whiplash and needs access to the Whiplash “My Retailer ID.”

4.   Notifies the Ryder Whiplash CSM once Happy Returns has configured the necessary permissions.


Number2.png  Ryder Whiplash team completes the following:

1. Adds the customer’s Whiplash account as an instance (tenant) for the Happy Returns integration. Whiplash team uses the customer’s Happy Returns Retailer IDs provided earlier.

Warning.png Important technical notes

  • When testing the integration, note that Whiplash is not processing the Happy Returns event payload shown below. This event only indicates the return has been dropped off at the return bar:

{"event": "return_status_updated", "typeID": "complete",}

  • The integration expects the “outbound_shipment_departure” event that is triggered when all return bar shipments are palletized and shipped to the Whiplash warehouse.
  • The integration expects the following event for mail returns:

{"event": "return_status_updated","typeID": "mail",}

  • The integration will create a ship notice for the returns and not a consumer return when using the Return Bar flow.

2. Confirms that the customer is ready to start leveraging Happy Returns to accept returns at the Whiplash warehouses.


For more information on becoming a Happy Returns customer, please reach out to partnerships@ryder.com.

If you have questions about this integration that aren’t outlined in this documentation, please reach out to us at support@whiplash.com.


Frequently Asked Questions

Is it possible to use both return methods?

Yes, when offering both return methods, the consumer decides their preference for return bar or by mail.

Is it possible to use both refund types?

Yes, Happy Returns allows customers to set the conditions that trigger each refund type, but this is only applicable to mail returns.

For example, “refund upon first carrier scan” may be set as the default refund type, but when the returned item has a price tag above a certain value (e.g., $150), the “refund upon warehouse inspection” type would be used instead. This option requires a team member in the distribution center/warehouse to verify the state and condition of the item before approving the refund.

Which is the most common refund method?

Most retailers opt for the “refund upon first carrier scan” option. This means the refund is executed as soon as the Return Bar Associate approves it or the item is mailed back (for mail returns).

What happens if a return requires warehouse inspection and the item fails to meet the standards to approve and close the return?

This doesn’t happen very often and is mostly handled in a case-by-case scenario. Usually, if the returned item is not in the condition it should be to approve the refund, a Customer Service representative of the retailer will contact the consumer.

What happens if the customer selects to exchange the item? 

The process to return an item is the same for exchanges as for refunds (either mail or return bar).

The only difference is that once the return is approved, a new order with the new item is created in the customer's eComm system and processed on Ryder Whiplash instead of triggering a refund.

The approval processes for exchanges are the same as with refunds: 

    • Upon first carrier scan: The return is approved as soon as the item is accepted by the Return Bar associate or mailed back. 
    • Warehouse inspection: A team member in the warehouse will verify the state and condition of the returned item before approving the exchange. 

I am a returns customer on another platform (Loop, AfterShip, etc.) and using Happy Returns through them, can I use this integration?

You can. Nevertheless, it’s extremely important to notify your CSM before the implementation to avoid setbacks.

I am changing warehouses within the Ryder Ecommerce Fulfillment network, what do I need to do to ensure Happy Returns are being sent to the correct warehouse location?

For mail returns: Go to your Happy Returns dashboard and simply edit the Locations that returns are sent to. The webhook will contain the new addressID for mail.


For return bar returns: You will need to reach out to retailersupport@happyreturns.com in order to confirm the new address you would like to ship Return Bar returns to. 

The destinationaddressID will change int he Return webhook and Outbound shipment API once the address is switched in the system. Happy Returns will need to provide the addressID to Ryder Ecommerce to understand what shipments are for what addresses.

Your customer success manager will help you facilitate this along with the warehouse transition.


Related Questions:

How does Happy Returns work?

What are the benefits of Happy Returns?

What are the different workflows for Happy Returns? 

How do I get started with Happy Returns?