Headless Returns

Overview

The “headless returns” integration adds Happy Returns drop off options, Return Bar and/or BORIS, in your existing shopper-facing return portal. This is typically applicable to merchants that have their own home grown return portal or Happy Returns’ partners who offer a return portal to multiple merchants.

Once implemented according to the best practices outlined in this document, shoppers will be able to:

• See Happy Returns drop off options in your portal – Return Bar and/or BORIS
• Understand which locations are close to them
• Receive a QR code for their return, and
• Drop off their items at Return Bar or BORIS locations and get an electronic receipt issued by Happy Returns

You will be able to:

• Receive notification of drop off so you can refund the shopper within 24 hours of drop off
• Receive advanced notification of aggregated shipments of returned goods to your warehouses or 3PLs.

The following APIs and Webhooks are applicable to this integration:

• Eligibility API – Recommended; check for return eligibility across configured dropoff methods and receive eligible locations
• Create headless return API - Required
• Return webhook - Required
• Outbound shipment webhook – Recommended; also available through dashboard or flat files
• Get outbound shipment details API – Recommended, also available through dashboard or flat files

Your Happy Returns point of contact will provide credentials during onboarding to ensure the correct access is granted. If additional merchants or brands are onboarded in the future, please alert Happy Returns in advance so access can be updated.

Item eligibility check

Shoppers use your return portal to select items.

Happy Returns’ responsibility

The Eligibility API should be called before displaying the dropoff methods to the shopper. The API will verify that the return meets Happy Returns’ eligibility requirements and responds with the available Happy Returns dropoff methods. Included in the response is a list of nearby dropoff locations and their details, which should be displayed to the shopper (see design guidelines). If the dropoff method is not eligible it should not be presented to the shopper.

Examples of checks performed by the API include:

• Returns with high value items
• Returns with many items
• Shoppers without nearby dropoff locations
• Items previously identified by Happy Returns operations as oversized or otherwise ineligible

Merchant’s responsibility

Ensure that the Eligibility API is called before displaying the dropoff methods to the shopper. For Return Bar returns, you are then responsible to limit returns that contain items that do not meet the Return Bar item guidelines.

Please discuss applicable use cases with your Happy Returns point of contact.

Return portal design guidelines

When Happy Returns drop off methods are presented to shoppers, the following design guidelines must be followed.
Please refer to your contract for any additional requirements.

1. The Happy Returns dropoff method(s) should be the default/primary option(s)
2. For Return Bar method, Happy Returns branding must be displayed correctly
1. "Happy Returns" is the correct name of the brand
2. "Happy Returns locations" should be used to reference locations
1. Alternatively, "Return Bar locations" can be used
3. A link to Happy Returns privacy policy MUST be displayed https://www.privacypolicy.happyreturns.com/
4. Use of location partner logos are not allowed, for example using Staples logo next to Staples location. The only acceptable logo is Happy Returns logo.
3. For Return Bar and BORIS methods, nearby locations can be retrieved using the Eligibility API or Get nearby locations API. Display best practices are:
1. The API gets top locations for the shopper's delivery address. You can choose to display 1 or more; we recommend 3 to give the shopper a choice.
2. For Return Bar method, display the link for the locations map using https://locations.happyreturns.com/?address={zipcode}&has_qr_code=true&retailer={yourRetailerID}. Query parameter information:
1. address – used to prepopulate their delivery zip code
2. has_qr_code – used to bring shopper directly to the map
3. retailer – used to indicate source of the request
3. Display the promotions, hours of operations, address, and distance
   

   

Starting the Return

Once the shopper has selected the Return Bar option, the return can be created. To create the Return Bar or BORIS return, use the Create headless return API. All fields documented as “required” must be included. Implementation considerations:

• The barcode or barcodes physically present on the item must be provided via the SKU, UPC parameters. If a different barcode ID is used, the product_id parameter must be provided.
• Returns expire if the shopper does not drop off items within a set period, typically 30 days from creation. Please communicate this expectation to the shopper as Return Bar locations will not be able to accept returns once the return expires. Note that an expiration notification is available via the Return webhook.
• Expiration can be manually triggered if necessary for your return process using Expire headless return API. Please communicate this change to the shopper.

Return confirmation design guidelines

The following design guidelines should be followed for the point in the process after the shopper starts their return.
Please refer to your contract for any additional requirements.

1. When the current dropoff method is Happy Returns, the return's confirmation page and any email, sms, or text communication should include:
   1. Prominent image representation of the QR code
   2. Alphanumeric representation of the express code in case QR code cannot be successfully scanned
   3. For Return Bar method, Happy Returns brand, correctly displayed (see portal design guidelines for details)
   4. Information about the allowable distance from shopper's delivery address

Return approval and notification

At the drop off location, the associate scans the shopper’s QR code and collects items in that return. Each item’s physical barcode is scanned, and an image validation may be performed. The items collected are approved and Happy Returns emails a receipt to the shopper. Within a few minutes, a Return webhook notification will be sent by Happy Returns. Refund notification emails from the merchant’s system are typically sent to the shopper at this time. Implementation considerations:

• For “headless returns”, the return webhook will only be triggered at the time of approval/drop off or expiration; start return and changing drop off method notifications do not apply.
• The Return ASN webhook approval must immediately trigger the refund, exchange, or store credit process in the system of record. You are responsible to issue the refund or other refund methods within 24 hours of the drop off event.
• The shopper may drop off a portion of the started items (a partial return), however the payload will contain all items in the return. The items.approvedAt parameter can be used to distinguish if an item was dropped off (with a timestamp), or was not dropped off (null value).
• The remaining unapproved items on a partial return cannot be accepted at a Return Bar; shoppers will need to start a new return if those items are still within your return policy.
• Returns cannot be accepted at a Return Bar that is further than 50 miles from the shopper’s delivery address.

Receiving aggregated shipments

Return Bar and applicable BORIS returns are routed to one of Happy Returns hubs where they are aggregated by merchant or partner and then shipped. An Outbound shipment webhook notification will be sent by Happy Returns at the time an aggregated shipment departs a hub. After receipt of notification, the Get outbound shipment details API can be used to retrieve details. Implementation Considerations:

• The outbound shipment webhook contains very high-level information about the shipment including the shipment’s ID.
  The ID should be retained to call the outbound shipment details API.
• The outbound shipment details API can be called at any time after the shipment was created and contains details of all items in the shipment. Since these shipments contain large amounts of data, the payloads are paginated with a limited number of items in each response.
• The outbound shipment details API likely contains more information than your application requires. More information and best practices for using this payload are available in the Shipments guide.
• Alternatively, shipment details and their tracking status can be retrieved from the Happy Returns’ dashboard Hub outbound shipments report or through a flat file.