Preview a refund before asking for it
preview_refundSee what a refund request for an order would do before your user decides. Pass the request_id and the amount your user wants back in USD (up to order.amount, which includes shipping; sales tax is refunded in proportion). It only reads: nothing is requested or changed. Returns the path (refund_now: the seller hasn't marked the order delivered, so it is refunded right away and the order is canceled; seller_decides: the seller has 48 hours to agree or disagree, no answer counts as agreeing, and if they disagree, Egonex members vote or Egonex decides), and for each possible outcome what your user gets back and every deduction: your user's share of the payment processing fee (processing_fee_paid_by says who pays it: it depends on the reason, see rules), the review fee when members vote to refund (2% of the order, at least $0.50), shipping that isn't refunded when the seller disagrees, and the sales tax refunded. After the seller marked the order delivered, also pass reason_category as your user says: not_received or damaged_or_not_as_described for any order, changed_mind only for a physical item (services and digital products don't have it; listing_kind says which). It decides who pays the payment processing fee and whether the item goes back, caps a changed_mind refund at the item price (max_refund: the original shipping isn't refunded), and request_refund uses it. For a shipped physical item, return says what the seller can choose (ask for the item back or refund without it), what happens if they don't answer, who pays the return shipping and the deadlines: ship within 7 days, the money comes back when the seller confirms receipt or 3 days after delivery, and nothing is refunded when nothing is shipped in time. Also the deadline for the seller, Egonex's refund rules, Egonex buyer protection, and a preview_id that request_refund can use for 15 minutes. Your user sees these amounts and deductions before deciding. 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). (It needs egonex.write, like request_refund, because only request_refund can use its preview_id.) A refund can be requested once per order, while it is paid and not completed: otherwise the error says why (refund_not_allowed, refund_already_requested; payment_processing right after the payment, for a minute). At most 30 previews an hour per connected account (slow_down). Errors end with their code in parentheses.
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>",
"amount": "<amount>"
},
"name": "preview_refund"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| amount | Yes | How much your user wants back, in USD with at most 2 decimals: up to order.amount (items and shipping). Sales tax comes back in proportion on top. | |
| request_id | Yes | The id returned by request_order (check_request shows the order it led to). | |
| reason_category | No | Why your user wants the refund, as they say: required after the seller marked the order delivered (check_request status delivered), ignored before. changed_mind is only for a physical item. It decides who pays the payment processing fee and whether the item goes back; request_refund uses the same one. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| next | Yes | What happens next. | |
| path | Yes | refund_now (refunded right away, the order is canceled) or seller_decides (the seller answers first). | |
| rules | Yes | Egonex's refund rules. | |
| amount | Yes | The amount asked for, USD (items and shipping, before sales tax). | |
| return | No | After delivery, for a shipped physical item: whether and how it goes back. | |
| currency | Yes | usd. | |
| order_id | Yes | The order. | |
| outcomes | Yes | Each possible outcome: what your user gets back and every deduction. | |
| shipping | No | Shipping in the order amount, USD; absent when the order has none. | |
| sales_tax | Yes | Sales tax paid on the order, USD (refunded in proportion). | |
| expires_at | Yes | request_refund can use preview_id until then (RFC 3339). | |
| max_refund | No | With this reason the refund is at most this, USD: the item price, without the original shipping (physical changed_mind). | |
| preview_id | Yes | Pass it to request_refund with the same request_id and amount before expires_at. | |
| request_id | Yes | The request. | |
| listing_kind | Yes | What was bought: physical, service or digital (after delivery, changed_mind is only for physical). | |
| order_amount | Yes | The most that can be asked for, USD: the order amount (items and shipping). | |
| processing_fee | Yes | The payment processing fee of this payment, USD; who pays it, and how much, is in each outcome. | |
| reason_category | No | After the seller marked the order delivered: the reason used, which decides who pays the payment processing fee. | |
| buyer_protection | Yes | Egonex buyer protection. | |
| seller_respond_by | No | seller_decides: if asked now, the seller answers by then (RFC 3339). | |
| seller_missed_delivery_deadline | No | The seller is past the delivery deadline and hasn't marked the order delivered: asking now refunds the whole order (whatever amount), and the seller pays the payment processing fee. |