Shipments

Overview

Whether you are a merchant independently receiving returns at your warehouse, or a 3rd party receiving returns on behalf of a merchant, you’ll likely require information from Happy Returns to process returns. This guide is broken into sections for mail and return bar returns, depending on your use cases, only some may be applicable.

Warehouse 3PL Integrations

The following APIs and Webhooks are commonly used by warehouses and 3PLs:

As a merchant who is directly partnered with Happy Returns, you can enable API access directly within the Happy Returns dashboard here.

As a 3rd party, you may process returns for one or many Happy Returns merchants. 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 so access can be updated.

Receiving mail returns

Mail returns started in the Happy Returns portal can be identified by your warehouse in various ways. Typically, the tracking number, express code (RMA), or the order number is used to uniquely identify the return.

Option 1 (recommended): Subscribe to the Return webhook to get all information about the return prior to delivery

  • A notification will be sent by Happy Returns at the time any return is started or dropoff method is updated. Mail returns will have a dropoffMethod of “mail”.
  • Mail returns will include tracking number, carrier, link to the shipping label, and a unique destination address ID
  • The tracking number and related item info can be ingested into your system to allow for identification of mail returns once received at your warehouse. Note that some carriers include prefixes or suffixes in the scannable shipping label’s barcode which might require processing to ensure a direct match can be made.
  • The destination address ID is automatically assigned by Happy Returns when a shipping zone and destination address is configured. This ID can be used to determine which warehouse the return is routed to.
  • Happy Returns does not provide notification of mail shipment progress. Depending on carrier, we recommend using a direct carrier integration to receive real time updates for tracking numbers provided.

Option 2: Lookup the return via the Happy Returns dashboard

  • See documentation for what information can be queried in the dashboard.
  • The query is limited to the current logged in merchant/brand.

Option 3: Lookup the return using the Get return details API

  • See API details for what information can be used to query returns.

Option 4: Enable packing slips

  • Includes fields for express code, order number, item identifier (typically SKU), and other supporting return information, see documentation.
  • This is required for merchants who use mail-no-label, where the shopper purchases their own label. Since the tracking number is not known by Happy Returns, the packing slip is the only method to identify the return.

Approving mail returns

Some merchants are configured in Happy Returns system to approve mail returns upon inspection. When this applies to a return, the warehouse typically inspects the item, and after confirming the item meets the requirements, and approval is issued. Approval should be issued in the Happy Returns system to ensure accurate reporting and shopper communications are made. Approval can be issued in one of two ways:

Option 1 (recommended): Make an API request to the Approve return API

  • This method can be integrated into existing warehouse management systems for ease of access.
  • See documentation for what information is needed to make this request. Typically, the Return webhook or Get return details API is used to retrieve these parameters.

Option 2: Approve the return from the Happy Returns dashboard

  • User roles should be set up for warehouse staff to use the dashboard. See how to do this here.

Receiving aggregated shipments

Return Bar and applicable In-Store returns are routed to one of Happy Returns hubs where they are aggregated by merchant or partner and then shipped. These shipments can contain many items. 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 discussed below

Alternatively, shipment details and their tracking status can be retrieved from the Happy Returns' dashboard Hub outbound shipments report or through a flat file.

Shipments from Happy Returns can contain thousands of items and processing these returns efficiently can be critical to achieving a cost-effective return solution. Warehouse receiving processes can vary significantly, but these strategies have proven effective for other Happy Return’s merchants and partners. Please work with your Happy Returns' contact if you have any questions.

Identifying items Each return polybag has a QR code label, referred to as the ‘return bag barcode’. This identifier is the best way to look up the contents of the return using a 2D barcode scanner. We suggest ingesting the outbound shipment details ( Outbound Shipment API) to make the association of Return Bag Barcode to return or item information. Talk to your Happy Returns' contact if 2D barcode scanning is not possible in your system. Implementation considerations:

  • Return Bag barcodes (items.returnBagBarcodes) are associated to one or more items in the outbound shipment, depending on the number of items in the return.
  • Return Bag barcodes (items.returnBagBarcodes) have a one-to-one relationship with their return. When a return requires multiple polybags at a Return Bar location, Happy Returns relabels subsequent bags so all bags in the return have a single identifier. When processing items, associates should process items available in that physical bag, leaving any outstanding items for when additional bags are processed.
  • The outbound shipment API is used to map returnBagBarcode to various attributes. Commonly referenced attributes are:
    • SKU (items.sku)
    • UPC (items.upc)
    • Order number (items.orderNumber) - Note that the shopper has already been refunded at the time of drop off, but this can be used to flag shoppers who abuse return policy.
    • Email (items.email)
    • Return reason (items.returnReason) – This can be used to inform of cases where the item is flagged as wrong item received or damaged, so they can be dispositioned appropriately.
  • While uncommon, a return with multiple bags can be broken into multiple shipments. If this occurs, only the items present in the bags that shipped are included in the outbound shipment API.

Resolving discrepancies As with any returns, discrepancies can occur but there are some strategies to handle common cases and reduce their likelihood.

  • Wrong item received by the shopper – In the event the shopper receives the wrong item, the item will not match the item they select in the return portal. We recommend using the return reason to help identify these items. Typically the item will need to be manually corrected to be received.
  • Shopper used the wrong polybag – In multi-item returns, items that have their barcode identification applied to the polybag can have items swapped between bags by the shopper. Depending on product identification, we recommend validating the polybag matches the item inside, especially on returns/orders that contain multiple items. This is especially relevant when the shopper has bracketed multiple sizes of the same item. Barcodes attached to the product via a hang tag can help reduce this discrepancy
  • Extra item received by the hub – While less common, items may not be properly bagged at a Return Bar location. Happy Returns attempts to match this to the appropriate return prior to shipment, however if an item still can’t be matched, it will be bagged and included in the outbound shipment API as an extra item with minimal information. We recommend receiving these items through an exception process. Hangtags or other clear labeling on products aids in Happy Return’s identification and remediation of these cases.
  • Extra item in polybag – also less common, but sometimes an extra item is dropped off by a shopper unexpectedly. The item won’t be known to Happy Returns and therefore will need to be received manually. These cases may also require customer support coordination with the shopper as they likely did not receive a refund.

Dispositioning items Once items are identified, we recommend performing a quality inspection that meets the standards to resell products. These vary merchant to merchant and can result in various disposition outcomes. For example: restock, dispose, donate, wash/press, etc. Also in the outbound shipment API, attributes like returnReason, returnReasonID, and returnReasonNote ( if applicable), can help in identifying issues and dispositioning items efficiently.

Handling inventory

Refund approval and timing can vary depending on the type of dropoff method and return policy. In some cases, a refund may be issued prior to receipt or disposition by the warehouse. We recommend tracking this inventory separately so that the volume can be tracked but is not immediately available for resale. One common approach is to create an inventory location like “Happy Returns In Transit”.

Labor planning

Processing returns typically takes a team of trained personnel and planning for fluctuations in return volume is critical for a smooth operation. Some strategies to forecast volume are:

  • For mail volume
    • Use the return webhook to see the volume of returns that are started and volume of returns that expire, then account for average shipping times for your carriers and shipping methods.
    • Use the Happy Returns dashboard analytics and reports to see the number of mail returns started in given periods and subscribe to emailed reports.
  • For Return Bar volume
    • Use the outbound shipment webhook to see shipments and number of items
    • Use the Happy Returns dashboard shipments section to see shipments that are in transit and view current tracking statuses
    • Use the Happy Returns analytics to see holistically the items in various stages of the process to get additional indicators of upcoming volume