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.
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.
- The Happy Returns dropoff methods should be the default/primary options
- For Return Bar method, Happy Returns branding must be displayed correctly
- "Happy Returns" is the correct name of the brand
- "Happy Returns locations" should be used to reference locations
- Alternatively “Return Bar locations” can be used
- A link to Happy Returns privacy policy MUST be displayed
- 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.
- For Return Bar and BORIS methods, nearby locations can be retrieved using the Get nearby locations API. Display best practices are:
- 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.
- 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:
address
– used to prepopulate their zip code
has_qr_code
– used to bring shopper directly to the map
retailer
– used to indicate source of the request
- Display the promotions, hours of operations, address, and distance
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