Select all applicable drop off methods for your integration:
For BORIS drop off method, reach out to Happy Returns for guidelines.
Overview
The “headless returns” integration adds Happy Returns drop off options, Return Bar and/or BORIS, Mail, No Pack, and No Pack or Print, 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 available Happy Returns drop off options in your portal – Return Bar and/or BORIS, Mail, No Pack, and/or No Pack or Print
Understand which Return Bar locations are close to them, if eligible
Receive a QR code or shipping label for their return, and
Drop off their items at a convenient location
Return Bar
Consolidated Returns
The following APIs and Webhooks are applicable to the consolidated returns integration:
Eligibility API – Recommended; check for return
eligibility across configured dropoff methods and receive eligible locations
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.
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.
Note: For retailers offering both Return Bar and non-consolidated return options (such as No Pack / No Pack or Print),
items eligible for Return Bar will not be eligible for non-consolidated drop-off methods by default.
To change this setting, please contact your customer support representative.
Happy Returns’ responsibility
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.
The Happy Returns dropoff method(s) should be the first & preselected option(s)
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, prior to starting a return
“By continuing, you acknowledge you have had an opportunity to read Happy Returns Privacy Policy.”
Where the "privacy policy" is a link to (https://www.privacypolicy.happyreturns.com/en-us)
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. Assets will be provided during onboarding.
Nearby locations can be retrieved using the Eligibility API. Display best practices are:
The API gets top locations for the shopper's delivery address. We recommend 3 to give the shopper a choice.
address – used to prepopulate their delivery 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 Example Return Bar option in a return portal
Starting the Return
Once the shopper has selected the drop off option, the return can be created. To create the return,
use the Create headless return API, making sure to select the correct drop-off method
to generate the appropriate request body. 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 drop off 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.
When the current dropoff method is Happy Returns, the return's confirmation page and any email, sms, or text
communication should include:
Prominent image representation of the QR code
Note: Some email providers will block images hosted by third parties. When emailing the shopper, we recommend you
download the QR code image and providing it as an inline attachment.
Alphanumeric representation of the express code in case QR code cannot be successfully scanned
For Return Bar method, Happy Returns brand, correctly displayed (see portal design guidelines for details)
Information about the allowable distance from shopper's delivery address
Example Return Bar QR code presented after starting a return
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.
No Print
Non-Consolidated Returns
Happy Returns supports non-consolidated, mail-based returns—including prepaid label, No Print, and No Pack or Print options—through the headless API. Shoppers can complete a return by either printing a prepaid shipping label or by receiving a QR code and dropping their package at participating locations. Prepaid label and No Print methods are configurable in the retailer dashboard for US-only merchants; No Pack or Print requires configuration with a Happy Returns representative.
For implementation within your portal, first check availability for a given return using
the /eligibility endpoint
(as required) before displaying each dropoff method. Provide shoppers with a method to select the dropoff method. Once
selected create a return using the /create-return endpoint with the
appropriate dropoff method id (“mail” for standard mail, “mail-nolabel” for No Print, or “mail-nobox-nolabel” for
No Pack or Print). After starting the return ensure your portal displays the label or QR code and provides links
to eligible drop-off locations. Refunds trigger point can be configured within the retailer dashboard,
and status updates are available through the /return webhook.
Happy Returns supports two shipment routing options. Depending on business requirements, you may implement merchant owned or Happy Returns owned.
With client owned routing, the client controls the logic to determine the service level and ship to address. In the create_return request, client must specify:
Sender’s address (end user making the return) within the returning.shipping_address object
Destination address (typically the return warehouse) within the mail_destination_address object
Shipping method (carrier account number and service level) as shipping_method_id
Note: Happy Returns will configure one or more shipping methods that represent a combination of account number and service level.
Each of these methods will have an integer assigned to be provided by client in the API request.
With Happy Returns owned routing, Happy Returns will configure one or more destination addresses and shipping methods. When the return is created, Happy Returns will calculate the cheapest of the configured shipping methods, based on client provided sender’s address and preconfigured destination address(es).
Item eligibility check
Shoppers use your return portal to select items.
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.
Note: For retailers offering both Return Bar and non-consolidated return options (such as No Pack / No Pack or Print),
items eligible for Return Bar will not be eligible for non-consolidated drop-off methods by default.
To change this setting, please contact your customer support representative.
Happy Returns’ responsibility
Examples of checks performed by the API include:
Determines if a preferred QR code method (Return Bar) is available. If so, it will take precedence
Otherwise, determines if a shipping label is available for given origin, destination, and carrier settings (UPS only).
Merchant’s responsibility
Ensure that the Eligibility API is called before
displaying the dropoff methods to the shopper. For Mail, No Pack, and No Pack or Print returns, you are responsible to limit returns to those containing items that meet the Mail return item restrictions.
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.
The Happy Returns dropoff method(s) should be the default/primary option(s)
Happy Returns branding must be displayed correctly
A link to Happy Returns privacy policy MUST be displayed, prior to starting a return
“By continuing, you acknowledge you have had an opportunity to read Happy Returns Privacy Policy.”
Where the "privacy policy" is a link to (https://www.privacypolicy.happyreturns.com/en-us)
Nearby locations can be retrieved using the Eligibility API. Display best practices are:
The API gets top locations for the shopper's delivery address. We recommend 3 to give the shopper a choice.
address – used to prepopulate their delivery 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 Example return options in a return portal
Starting the Return
Once the shopper has selected the drop off option, the return can be created. To create the return,
use the Create headless return API, making sure to select the correct drop-off method
to generate the appropriate request body. All fields documented as “required” must be included. Implementation considerations:
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 drop off 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.
When the dropoff method is No Print, the return's confirmation page and any email, sms, or text
communication should include:
Prominent image representation of the QR code
Note: Some email providers will block images hosted by third parties. When emailing the shopper, we recommend you
download the QR code image and providing it as an inline attachment.
address – used to prepopulate their delivery zip code
has_qr_code – used to bring shopper directly to the map
retailer – used to indicate source of the request
Example QR code presented after starting a return
Return approval and notification
Closed box returns are dropped off without any item verification; contents may vary from the shopper’s declared return.
Within a few minutes, a Return webhook notification will be
sent by Happy Returns. Merchants may elect one of three refund timing options and are accompanied by the following considerations:
For Refund on Inspection, the Return webhook will indicate that the return was dropped off. It will contain a timestamp of the
drop off via the items.droppedOffAt parameter. The items.approvedAt parameter will be null and there is no expectation that the
return is refunded at this time. Optionally, merchants may use the Approve return API to update Happy Returns
when approving a return at time of inspection. If this API is not used, Happy Returns will show the return in a dropped off status and
will not get a record of final disposition of the return.
For Refund on Carrier Scan, the Return webhook will indicate that the return was dropped off. Both items.droppedOffAt and items.approvedAt
parameters will contain the timestamp for the drop off event. With a non-null approvedAt parameter, the expectation is that the return is dispositioned immediately.
For Refund on Delivery, the Return webhook will indicate that the return was dropped off. It will contain a timestamp of the drop off via the items.droppedOffAt
parameter. The items.approvedAt parameter will be null and there is no expectation that the return is refunded at this time. The Return webhook will provide another notification at the time of delivery. At delivery, the items.approvedAt parameter will now contain the timestamp for the delivery event. The expectation is that the return is dispositioned immediately.
No Pack or Print
Non-Consolidated Returns
Happy Returns supports non-consolidated, mail-based returns—including prepaid label, No Print, and No Pack or Print options—through the headless API. Shoppers can complete a return by either printing a prepaid shipping label or by receiving a QR code and dropping their package at participating locations. Prepaid label and No Print methods are configurable in the retailer dashboard for US-only merchants; No Pack or Print requires configuration with a Happy Returns representative.
For implementation within your portal, first check availability for a given return using
the /eligibility endpoint
(as required) before displaying each dropoff method. Provide shoppers with a method to select the dropoff method. Once
selected create a return using the /create-return endpoint with the
appropriate dropoff method id (“mail” for standard mail, “mail-nolabel” for No Print, or “mail-nobox-nolabel” for
No Pack or Print). After starting the return ensure your portal displays the label or QR code and provides links
to eligible drop-off locations. Refunds trigger point can be configured within the retailer dashboard,
and status updates are available through the /return webhook.
Happy Returns supports two shipment routing options. Depending on business requirements, you may implement merchant owned or Happy Returns owned.
With client owned routing, the client controls the logic to determine the service level and ship to address. In the create_return request, client must specify:
Sender’s address (end user making the return) within the returning.shipping_address object
Destination address (typically the return warehouse) within the mail_destination_address object
Shipping method (carrier account number and service level) as shipping_method_id
Note: Happy Returns will configure one or more shipping methods that represent a combination of account number and service level.
Each of these methods will have an integer assigned to be provided by client in the API request.
With Happy Returns owned routing, Happy Returns will configure one or more destination addresses and shipping methods. When the return is created, Happy Returns will calculate the cheapest of the configured shipping methods, based on client provided sender’s address and preconfigured destination address(es).
Item eligibility check
Shoppers use your return portal to select items.
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.
Note: For retailers offering both Return Bar and non-consolidated return options (such as No Pack / No Pack or Print),
items eligible for Return Bar will not be eligible for non-consolidated drop-off methods by default.
To change this setting, please contact your customer support representative.
Happy Returns’ responsibility
Examples of checks performed by the API include:
Determines if a preferred QR code method (Return Bar) is available. If so, it will take precedence
Otherwise, determines if a shipping label is available for given origin, destination, and carrier settings (UPS only).
Merchant’s responsibility
Ensure that the Eligibility API is called before
displaying the dropoff methods to the shopper. For Mail, No Pack, and No Pack or Print returns, you are responsible to limit returns to those containing items that meet the Mail return item restrictions.
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.
The Happy Returns dropoff method(s) should be the default/primary option(s)
Happy Returns branding must be displayed correctly
A link to Happy Returns privacy policy MUST be displayed, prior to starting a return
“By continuing, you acknowledge you have had an opportunity to read Happy Returns Privacy Policy.”
Where the "privacy policy" is a link to (https://www.privacypolicy.happyreturns.com/en-us)
Nearby locations can be retrieved using the Eligibility API. Display best practices are:
The API gets top locations for the shopper's delivery address. We recommend 3 to give the shopper a choice.
address – used to prepopulate their delivery 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 Example return options in a return portal
Starting the Return
Once the shopper has selected the drop off option, the return can be created. To create the return,
use the Create headless return API, making sure to select the correct drop-off method
to generate the appropriate request body. 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 drop off 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.
When the dropoff method is No Pack or Print, the return's confirmation page and any email, sms, or text
communication should include:
Prominent image representation of the QR code
Note: Some email providers will block images hosted by third parties. When emailing the shopper, we recommend you
download the QR code image and providing it as an inline attachment.
address – used to prepopulate their delivery zip code
has_qr_code – used to bring shopper directly to the map
retailer – used to indicate source of the request
Example QR code presented after starting a return
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).
Mail
Non-Consolidated Returns
Happy Returns supports non-consolidated, mail-based returns—including prepaid label, No Print, and No Pack or Print options—through the headless API. Shoppers can complete a return by either printing a prepaid shipping label or by receiving a QR code and dropping their package at participating locations. Prepaid label and No Print methods are configurable in the retailer dashboard for US-only merchants; No Pack or Print requires configuration with a Happy Returns representative.
For implementation within your portal, first check availability for a given return using
the /eligibility endpoint
(as required) before displaying each dropoff method. Provide shoppers with a method to select the dropoff method. Once
selected create a return using the /create-return endpoint with the
appropriate dropoff method id (“mail” for standard mail, “mail-nolabel” for No Print, or “mail-nobox-nolabel” for
No Pack or Print). After starting the return ensure your portal displays the label or QR code and provides links
to eligible drop-off locations. Refunds trigger point can be configured within the retailer dashboard,
and status updates are available through the /return webhook.
Happy Returns supports two shipment routing options. Depending on business requirements, you may implement merchant owned or Happy Returns owned.
With client owned routing, the client controls the logic to determine the service level and ship to address. In the create_return request, client must specify:
Sender’s address (end user making the return) within the returning.shipping_address object
Destination address (typically the return warehouse) within the mail_destination_address object
Shipping method (carrier account number and service level) as shipping_method_id
Note: Happy Returns will configure one or more shipping methods that represent a combination of account number and service level.
Each of these methods will have an integer assigned to be provided by client in the API request.
With Happy Returns owned routing, Happy Returns will configure one or more destination addresses and shipping methods. When the return is created, Happy Returns will calculate the cheapest of the configured shipping methods, based on client provided sender’s address and preconfigured destination address(es).
Item eligibility check
Merchant’s responsibility
Ensure that the Eligibility API is called before
displaying the dropoff methods to the shopper. For Mail, No Pack, and No Pack or Print returns, you are responsible to limit returns to those containing items that meet the Mail return item restrictions.
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.
Happy Returns branding must be displayed correctly
A link to Happy Returns privacy policy MUST be displayed, prior to starting a return
“By continuing, you acknowledge you have had an opportunity to read Happy Returns Privacy Policy.”
Where the "privacy policy" is a link to (https://www.privacypolicy.happyreturns.com/en-us)
Use of location partner logos are not allowed, for example using Staples logo next to Staples location.
Display drop off locations based on carrier Example return options in a return portal
Starting the Return
Once the shopper has selected the drop off option, the return can be created. To create the return,
use the Create headless return API, making sure to select the correct drop-off method
to generate the appropriate request body. All fields documented as “required” must be included. Implementation considerations:
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 drop off 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.
When the dropoff method is Mail, the return's confirmation page should include:
Prominent download link for the label
Any email communication should include the label, as an attachment.
Example label download link presented after starting a return
Return approval and notification
Closed box returns are dropped off without any item verification; contents may vary from the shopper’s declared return.
Within a few minutes, a Return webhook notification will be
sent by Happy Returns. Merchants may elect one of three refund timing options and are accompanied by the following considerations:
For Refund on Inspection, the Return webhook will indicate that the return was dropped off. It will contain a timestamp of the
drop off via the items.droppedOffAt parameter. The items.approvedAt parameter will be null and there is no expectation that the
return is refunded at this time. Optionally, merchants may use the Approve return API to update Happy Returns
when approving a return at time of inspection. If this API is not used, Happy Returns will show the return in a dropped off status and
will not get a record of final disposition of the return.
For Refund on Carrier Scan, the Return webhook will indicate that the return was dropped off. Both items.droppedOffAt and items.approvedAt
parameters will contain the timestamp for the drop off event. With a non-null approvedAt parameter, the expectation is that the return is dispositioned immediately.
For Refund on Delivery, the Return webhook will indicate that the return was dropped off. It will contain a timestamp of the drop off via the items.droppedOffAt
parameter. The items.approvedAt parameter will be null and there is no expectation that the return is refunded at this time. The Return webhook will provide another notification at the time of delivery. At delivery, the items.approvedAt parameter will now contain the timestamp for the delivery event. The expectation is that the return is dispositioned immediately.