Investigate a customer balance with AI

---
name: investigate-customer-balance
description: Investigate a Hyperline customer balance with read-only checks. Use when an agent needs to reconcile customer balance, open invoices, wallet or credit balances, invoice payments, refunds, and recent transactions.
---

# Investigate Customer Balance

Default to read-only operations.

## Inputs

Collect these values before querying data:

- Customer ID, external ID, or customer name.
- The balance question: outstanding amount, credit balance, wallet balance, payment mismatch, refund, or invoice status.
- Timeframe if relevant.
- Environment: production or sandbox.

If the user gives a name, resolve the customer and confirm when multiple customers match.

## Workflow

1. Get the customer record.
2. List recent invoices for the customer.
3. Check invoice statuses, due dates, totals, outstanding amounts, and related transactions.
4. Check wallet balances and wallet transactions when the question mentions prepaid balance, wallet, top-up, or credit.
5. Check credit balances and credit transactions when the question mentions credits or usage credits.
6. Compare the expected balance against the sum of open invoices, payments, refunds, wallet movements, and credit movements.

## Useful endpoints

- `GET /v2/customers/{id}` for customer context.
- `GET /v1/invoices` filtered by customer for invoices and status.
- `GET /v1/invoices/{id}` for invoice details.
- Wallet endpoints for wallet balance and transactions.
- Customer credit endpoints for credit products and credit transactions.

Use MCP or CLI equivalents when available.

## Output

Return:

- Direct answer first.
- Then a short reconciliation table.
- Then the records checked.
- Then unresolved gaps or next checks.

## Safety

- Do not mark invoices paid, void invoices, issue refunds, or load wallets without explicit confirmation.
- Do not assume an invoice is paid because a payment exists; verify final invoice and transaction status.
- Do not assume usage credits and wallet balance are the same thing.