Issue refund
issue_refundDestructiveIdempotent
Issue 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.
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. |