Ask for a refund for your user
request_refundAsk for a refund for your user, exactly as previewed with preview_refund: pass the same request_id, preview_id and amount, and your user's reason (the preview's reason_category is used). It can't be undone. On the refund_now path the money is refunded right away and the order is canceled (also for a partial refund); refund.refunded_amount and refund.refund_id (the refund's reference) say what was refunded. On the seller_decides path the request goes to the seller (refund.seller_respond_by); the order doesn't complete on its own meanwhile, and check_request with the request_id shows its progress (refund). When the seller asks for the item back, the status is return_requested, refund.stage is awaiting_return and refund.return says where to send it and by when; after your user ships it, pass the tracking number with submit_return_shipment. Needs your user's Egonex account connected to you with permission to act for them (egonex.write), and that account must be the order's buyer: without such a connection (none, or a read-only one), nothing is done and the result is an error ending in (connection_required); when the connected account isn't the order's buyer, nothing is done (not_found). Without a connection, this is done on Egonex, in your user's chat with the seller. At most 5 calls a minute per connected account (slow_down). Nothing is requested when the preview expired (preview_expired) or isn't for this request, order and account (preview_not_found), when amount isn't the preview's (preview_mismatch), or when the seller marked the order delivered since the preview (preview_outdated: preview again and show your user the new amounts). Calling it again with the same preview_id returns the same refund request. If the result is refund_error, Egonex couldn't confirm the outcome and the refund may already have gone through: call it again with the same request_id, preview_id and amount, also after the preview's 15 minutes or after the seller marked the order delivered. A refund that went through is then recorded and returned (nothing is refunded twice); if none went through, the request is made as previewed, or refused with preview_outdated when the order changed. Egonex also records such a refund on its own, and a different refund already at the payment processor stops the request (refund_on_hold). Photos can't be attached here. Errors end with their code in parentheses. Only call this after your user saw the preview's amounts and deductions and asked for the refund.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"request_id": "<request_id>",
"preview_id": "<preview_id>",
"amount": "<amount>",
"reason": "<reason>"
},
"name": "request_refund"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | The amount you passed to preview_refund, in USD. | |
| reason | Yes | Why your user wants the refund, in their words, up to 1000 characters. The seller sees it, and so do Egonex members if they review it. | |
| preview_id | Yes | preview_id from preview_refund for this request (it lasts 15 minutes). | |
| request_id | Yes | The id returned by request_order (check_request shows the order it led to). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| next | Yes | What happens next. | |
| order | No | The order this request led to: made with pay_order, or placed by your user in the chat after confirming. Times are given only where they matter for the status. | |
| refund | Yes | A refund request for the order. | |
| status | No | Where the order stands now, as check_request reports it: pending (waiting for your user to confirm or decline; nothing has happened yet), declined (your user chose not to go ahead), expired (nobody acted within 7 days; the link no longer works), listing_unavailable (the listing isn't for sale anymore (taken down or sold out), so the request can't go ahead), message_sent (messages only: the message was sent to the seller as your user), awaiting_order (orders only: your user confirmed and the chat is open, but they haven't placed the order yet), payment_in_progress (orders only: a payment is being processed), payment_failed (orders only: a pay_order payment didn't go through; nothing was charged and the order can still be paid), waiting_for_seller (orders only: the order was sent to the seller, who hasn't accepted yet; nothing has been charged), ready_to_pay (orders only: the order is waiting to be paid (pay_order again, or your user pays on Egonex)), paid (orders only: paid; waiting for the seller to deliver), delivered (orders only: the seller marked it delivered; waiting for your user to confirm receipt), refund_requested (orders only: your user asked for a refund; Egonex is handling it), return_requested (orders only: the item has to go back for the refund: your user ships it by order.return_ship_by and adds the tracking number on Egonex), return_in_transit (orders only: the item is on its way back; the refund follows once it arrives and the seller confirms), return_delivered (orders only: the returned item arrived; waiting for the seller to confirm receipt, then the refund follows), completed (orders only: the order is complete), refund_pending (orders only: canceled after payment; the refund hasn't gone through yet), refunded (orders only: canceled after payment; your user was refunded), closed_unpaid (orders only: the order closed before anything was charged (close_reason says why)). | |
| request_id | Yes | The request. |