Sign in

v3

latestOpenAPI 3.1.02026-08-0619186200.1 KB
Webhooks

Return status change

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.

postWebhookreturnStatusChange

Payload

idinteger required

Unique numeric identifier of the return.

warehousestring required

Code of the warehouse handling this return.

order_keystring nullable required

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

store_idinteger nullable required

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

rmastring required

Return Merchandise Authorization (RMA) number identifying this return.

tracking_numberstring nullable required

Primary carrier tracking number of the return shipment; null if not yet known. Set to the most recently added of tracking_numbers.

tracking_numbersstring[] required

All carrier tracking numbers associated with the return shipment; empty when none are known.

status'status_created' | 'in_progress' | 'en_route' | 'returned' | 'arrived' | 'not_arrived' | 'grading_completed' required
return_reason'reason_exchange' | 'reason_changed_mind' | 'reason_undeliverable' | 'reason_unknown' | 'reason_incorrect_product' required
notestring nullable required

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

created_atstring date-time required

ISO 8601 timestamp when the return record was created.

updated_atstring date-time required

ISO 8601 timestamp when the return record was last updated.

received_atstring date-time nullable required

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

source'shipmonk' | 'loop' | 'returnly' | 'deposco' | 'happy_returns_loop' | 'happy_returns' required

Response

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