Skip to content

Return status updated
Webhook

Request

Sent when a return moves to another status. The payload is the return as GET /returns/{id} returns it. The event goes to the sales channel of the returned order.

Security
BearerAuth
Headers
x-hive-signaturestringrequired

Hex-encoded HMAC-SHA256 digest of the request body, keyed with your API token (the oldest valid one, if the sales channel has several).

x-hive-event-idstringrequired

Identifies the webhook call. Retries of the same call carry the same value.

Bodyapplication/jsonrequired
carrierstring or nullrequired

The carrier that brought the return back.

completed_handling_atstring or null, (date-time)required

When handling of the return was completed.

created_atstring, (date-time)required

When the return was created.

idinteger, (int64)required

Hive's unique identifier for the return.

orderobject(ReturnOrder)required

The order the return belongs to.

photosArray of objects(ReturnPhoto)required

Photos of the returned parcel.

received_atstring or null, (date-time)required

When the return was received at the warehouse.

return_itemsArray of objects(ReturnItem)required

The items the customer announced through the Customer Portal. Empty if the return did not come through the Customer Portal.

return_line_itemsArray of objects(ReturnLineItem)required

The items that were handled at the warehouse. Empty until the return is handled.

return_reasonstring or nullrequired

Why the parcel came back. Can be null or an empty string when no reason is recorded.

Enum:"customer_return""not_picked_up""invalid_address""rejected_by_customer""customs_documents_missing""return_label_in_box""other"""null
return_reason_typestring or nullrequired

The kind of return:

  • active: a customer return, the customer shipped the parcel back.
  • passive: a carrier return, the customer never received the parcel and the carrier sent it back, for example because of an invalid address, a parcel not picked up, damage or missing customs documents.
  • null or an empty string: the return was created before it was processed and did not come through the Customer Portal. Customer Portal returns are always active.
Enum:"active""passive"""null
started_processing_atstring or null, (date-time)required

When processing of the return started at the warehouse.

statusstringrequired

The return status:

  • requested: requested through the Customer Portal and waiting for approval.
  • on_the_way: on the way to the warehouse.
  • arrived: arrived at the warehouse.
  • processing: being processed.
  • action_required: waiting for guidance from the merchant.
  • handling_completed: processing is completed.
  • cancelled: cancelled.
Enum:"requested""on_the_way""arrived""processing""action_required""handling_completed""cancelled"
tracking_codestring or nullrequired

The tracking number the carrier assigned to the return.

tracking_urlstring or nullrequired

The carrier's tracking page for the return.

Payload
{
  "id": 70047,
  "return_reason_type": "active",
  "return_reason": "customer_return",
  "status": "handling_completed",
  "tracking_code": "TC123456789",
  "tracking_url": "https://example.org/package?trackingNumber=TC123456789",
  "carrier": "ExampleCarrier",
  "created_at": "2023-05-18T09:38:18.999+02:00",
  "received_at": "2023-05-19T10:38:18.999+02:00",
  "started_processing_at": "2023-05-20T11:38:18.999+02:00",
  "completed_handling_at": "2023-05-21T12:38:18.999+02:00",
  "order": {
    "id": 1230221,
    "merchant_order_id": "60423b95-23b5-4e5b-aa1c-6a71bd90b106",
    "name": "#DE12345"
  },
  "photos": [
    { … }
  ],
  "return_items": [
    { … }
  ],
  "return_line_items": [
    { … }
  ]
}

Responses

Any 2xx status acknowledges the webhook.