Issue refund
issue_refundIssue a full or partial refund on a paid order with amount and reason validation, duplicate-payment protection via idempotency keys, and audit logging.
Instructions
Refund money on a paid order. Guardrails: amount must be > 0 and within the remaining refundable amount; unpaid, cancelled and fully-refunded orders are refused; a reason and an idempotency_key are required, and repeating a key replays the original refund instead of paying twice. When refunds reach the order total the order becomes 'refunded'. Every refund is written to the audit log.
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": {
"order_id": "<order_id>",
"amount_cents": "<amount_cents>",
"reason": "<reason>",
"idempotency_key": "<idempotency_key>"
},
"name": "issue_refund"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| reason | Yes | Why the refund is issued; stored in the audit log. | |
| order_id | Yes | Numeric order ID, e.g. 1042. | |
| amount_cents | Yes | Refund amount in integer cents (1050 = $10.50). Must be > 0 and <= the order's remaining refundable amount (get_order -> financials.refundable_cents). | |
| idempotency_key | Yes | Unique key for THIS refund, e.g. 'refund-1042-late-delivery'. Retrying with the same key returns the original refund instead of paying twice. Use a new key only for a genuinely new refund. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| order | Yes | ||
| refund | Yes | ||
| replayed | Yes | True when this key was already used for the same refund: nothing new was refunded. |