Return status change

wbhk

returnStatusChange

Supported Return Webhooks

All return-related webhooks are closely tied to the status of the return. Each webhook is triggered by a specific status transition, marking important stages in the return process.

Return created (status: status_created)
Return in progress (status: in_progress)
Return en route (status: en_route)
Return returned (status: returned)

Payload Structure (JSON Schema)

The payload of each return-related webhook matches the structure of a single return object as returned by the GET /v1/integrations/returns-list endpoint. While the GET /v1/integrations/returns-list endpoint responds with an array of return objects (returns-list field), each webhook delivers the full data of one return in the same format. This allows for easy reuse of the return model across both API responses and webhook events.

Payload

integer

required

Unique numeric identifier of the return.

warehouse

string

required

Code of the warehouse handling this return.

order_key

string | null

required

External order key of the original order this return relates to; null when no linked order exists.

store_id

integer | null

required

Identifier of the store the return belongs to; null if the return is not linked to a store.

rma

string

required

Return Merchandise Authorization (RMA) number identifying this return.

tracking_number

string | null

required

Carrier tracking number of the return shipment; null if not yet known.

status

string

enum

required

Current processing status of the return: status_created, in_progress, en_route, returned, arrived, not_arrived, or grading_completed.

Allowed:

return_reason

string

enum

required

Reason the return was initiated: exchange, changed_mind, undeliverable, unknown, or incorrect_product.

Allowed:

note

string | null

required

Optional free-text note attached to the return; null when no note was provided.

created_at

date-time

required

ISO 8601 timestamp when the return record was created.

updated_at

date-time

required

ISO 8601 timestamp when the return record was last updated.

received_at

date-time | null

required

ISO 8601 timestamp when the return was physically received at the warehouse; null until received.

items

array of objects

required

Line items included in the return, each with expected and received quantities.

items*

custom_data

array of objects

required

List of custom name/value pairs attached to the return by the source integration.

custom_data*

source

string

enum

required

System that originated this return record: shipmonk, loop, returnly, deposco, happy_returns_loop, or happy_returns.

Allowed:

Responses

200

Return a 2xx status to indicate that the data was received successfully

default

For a 4xx status, ShipMonk will retry the webhook delivery up to 100 times, with a 5-minute delay between attempts.