Return webhook events

Return-request webhooks track the return lifecycle — approvals, rejections, item receipt, and completion. The trigger HTTP header carries a fixed string indicating the event category.

Wire trigger values

The trigger header carries one of two values:

Trigger header value	Fires when
return_status_update	Return request transitions to a new status
return_received_update	Items are received or returned at the return location

Status triggers

You subscribe to individual statuses in the webhook configuration's notify_status list. When the return request reaches one of these statuses, the webhook fires with trigger header return_status_update.

Status	Fires when
pending	Return request is awaiting review
on_hold	Return request is placed on hold
approved	Return request is approved
rejected	Return request is rejected
cancelled	Return request is cancelled
completed	Return is completed
returned	Items have been returned
received	Items have been received at the return location

Item triggers

Item-level events fire with trigger header return_received_update. These are controlled by configuration fields on the webhook:

Configuration field	Fires when
notifyReturnRequestReceivedItems	Items received at the return location
notifyReturnRequestReturnedItems	Items returned/restocked

Payload

The body is the full ReturnRequest object as JSON. No wrapper, no diff.

{
  "return_request_id": "RET-00078901",
  "merchant": "ACME",
  "status": "approved",
  "line_items": [
    {
      "sku": "SHOES-RUN-42",
      "quantity": 1,
      "reason": "wrong_size"
    }
  ],
  "customer": {
    "contact_name": "Jane Doe",
    "country": "GB",
    "city": "London"
  }
  // ... full return request fields
}

Conditions

No entity-specific conditions are available for return-request webhooks. The webhook fires for all return-request events matching the configured triggers.