Headless Returns

Overview

The “headless returns” integration adds Happy Returns drop off options, both Return Bar 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 best practices outlined in this document, shoppers will be able to:

  • See Happy Returns drop off options in your portal, both 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.
Headless return integration

The following APIs and Webhooks are applicable to this integration:

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

Shoppers use your return portal to select items in accordance with the return policy. The items selected by the shopper must be checked for eligibility before presenting the Happy Returns drop off option to the shopper. Only if all items in the return are eligible should the option be displayed. For Return Bar returns, ineligible items/returns include but are not limited to:

  • Large and heavy items that would not fit into a Happy Returns polybag such as winter coats, boots, and furniture
  • Liquids, items containing batteries, and other hazardous or dangerous items
  • Returns with more than 9 items
  • Returns with items valued more than $500

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 methods should be the default/primary options
  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
    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 Get nearby locations API. Display best practices are:
    1. The API gets top locations for the shopper’s 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 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
      Example Return Bar option in a return portal

Starting a 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 provided. 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
  • Returns expire if the shopper does not drop off items within a set period, typically 30 days from creation, or if the return is manually expired via the expire headless return endpoint. 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.

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.

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