01When does it fire?
- When a completed return is recorded on an order (not just a return request — that is return.requested).
- Once per return — with the stable identity mwh:return-created:<tenant_id>:<return_id>.
02Full payload example
{
"return_id": "b4e1f7a2-9c30-4d58-8e6b-3f2a1d0c9b87",
"order_id": "3f0c8e6a-1d24-4b7f-9a3e-2c5b8d90f1aa",
"refund_amount": 225,
"refund_method": "VODAFONE_CASH",
"reason": "WRONG_SIZE",
"items": [
{
"product_id": "7a2b9c4e-8f31-4d5a-b6c2-1e9f8a7b6c5d",
"variant_id": "2c4e6f8a-0b1d-4e2f-8a3b-5c6d7e8f9a0b",
"name": "Cotton T-shirt - Blue / L",
"price": 225,
"quantity": 1
}
],
"items_truncated": false,
"created_at": "2026-10-21T09:12:40.115602+00:00",
"customer_name": "Ahmed Mahmoud",
"customer_phone": "+201001234567",
"branch_id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
"id": "mwh:return-created:9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b:b4e1f7a2-9c30-4d58-8e6b-3f2a1d0c9b87",
"type": "return.created",
"api_version": "v2",
"tenant_id": "9e8d7c6b-5a4f-4e3d-2c1b-0a9f8e7d6c5b"
}03Payload fields
| Field | Can be null? | Meaning |
|---|---|---|
| return_id | No | The return id (UUID). |
| order_id | No | The original order id. |
| refund_amount | No | The refunded amount in the store currency. |
| refund_method | No | The refund method. |
| reason | No | The return reason — e.g. DEFECTIVE, WRONG_SIZE or CHANGED_MIND. Capped at 500 characters in the payload. |
| items | No | Returned items in the same shape as order items. |
| items_truncated | No | true when items exceeded 100 and were capped. |
| created_at | No | When the return was recorded, ISO 8601. |
| customer_name | Yes | The customer name from the original order, when present. |
| customer_phone | Yes | The customer phone from the original order, when present. |
| branch_id | Yes | The order branch id — when the store has more than one branch. |
04Event identity
Pattern: mwh:return-created:<tenant_id>:<return_id> — constant across retries and replays.
COMPLETE YOUR INTEGRATION