Return

API docs by Redocly

Return

Download OpenAPI specification:Download

Overview

For partners who would like to receive notifications of the events triggered for their returns and when they are being refunded.

Manage Webhook Subscription

Partners can subscribe to this webhook by following the steps here: Webhook set up.

Triggers/Events

The return.asn webhook type is triggered when one of the following happens in the Happy Returns system:

  • A drop-off method is created for the return. This occurs when a return is started or when the customer changes their desired drop-off method.
  • The return status is updated. This occurs when a return is started, dropped off, approved for a refund, or expired.

In order to reduce the volume of requests you will receive, Happy Returns will internally aggregate requests for the same return that occur within 60 seconds of each other. In this scenario, the otherEvents field will be populated with the events that have been aggregated. If both a drop-off method and return status event exist in the same payload, the latest return status will always be the primary event. If there are multiple events, then they are ordered in reverse chronological order with latest event being first.

Return Details Webhook

Request Body schema: application/json

Details about a return.
The header contains the X-Hr-Signature. For example, X-Hr-Signature: bab3130e011ba9522d5919bcf9075649b24f9fdfc928b3d2accc99a53aaf3c34

See here for more information: Webhook Validation

  • The payload consists of a return's items of the same order number. For example, if a return consists of multiple order numbers, Happy Returns will POST to the webhook URL multiple times for the same return, one request per order number. In the report, each line item is one physical item. NOTE: For some fields, such as the SKU, in order for a value to be populated the information must be passed from the retailer’s ecommerce platform to the Happy Returns system.
  • If the customer decides to do a walk-up return where he/she would go to the retailer store and return, then an event is also triggered. See example on the right.
  • If the there is an extra item in the return bag processed at the hub, then the retailer will be notified for it with some basic information. See example on the right.

event
string

The event that triggered the webhook. This can be either return_dropoff_method_created or return_status_updated.

typeID
string

The details on the event that triggered the webhook.

  • If the event is return_dropoff_method_created, then the value is the drop-off method. The possible values are: mail, mail-nolabel, mail-nobox-nolabel, mail-shopper-provided, return-bar, retailer-store.
  • If the event is return_status_updated, then the value is the new return status. The possible values are started, dropped-off, partial-refund, expired and complete.

retailerID
string

The unique identifier for the retailer in the Happy Returns system.

Array of objects
Array of objects

Responses

Request samples

Content type
application/json
Example
{
  • "event": "return_status_updated",
  • "typeID": "started",
  • "retailerID": "modern-retailer",
  • "otherEvents": [
    ],
  • "items": [
    ]
}