invoice-housekeeping

/invoice-housekeeping — Invoice cleanup and refunds

Algorithm

1. Call list_invoices with page, per_page and status (paid | unpaid | expired | cancelled). Start with unpaid to find stale checkouts.
2. Page through until the list is exhausted. Do not report a total you have not paged to.
3. For anything ambiguous, call get_invoice_data with its invoice_id for the full record (amount, method, transaction_id, customer).
4. To cancel: cancel_invoice with invoice_id. This only works on unpaid invoices — check status first, and confirm with the user before cancelling anything.
5. To refund: refund_payment with invoice_id, optional amount (omit for full refund) and optional reason. Refund support depends on the rail — a Fawry cash payment may not be refundable through the API. Report the error as-is rather than retrying blindly.
6. Call get_balance at the end so the user sees the account position after the cleanup.

Response format

## Fawaterak housekeeping

**Balance**: 18,420 EGP

### Unpaid over 48 h — 6 invoices, 3,100 EGP
| Invoice | Amount | Created | Action |
|---------|--------|---------|--------|
| 88101 | 450 EGP | 2026-08-30 | cancelled |

### Refunds issued
| Invoice | Amount | Reason | Status |
|---------|--------|--------|--------|
| 88044 | 200 EGP | partial return | success |

Notes

• Always confirm before cancel_invoice or refund_payment — neither is reversible.
• Partial refund = pass amount. Full refund = omit amount entirely.
• get_balance reflects settled money; a just-issued refund may not be deducted yet.

Examples

/invoice-housekeeping unpaid
/invoice-housekeeping refund 88044 200 "partial return"