getBillingHistory
Retrieve a customer's complete billing history, current balance, payment methods, and invoice details to resolve billing disputes and inquiries.
Instructions
Retrieve customer billing statements, balances, and payment methods - Retrieves complete billing statements, current account balance due, payment methods on file, and historical invoice IDs for a specific customer.
[Usage Guidelines]
When to use: Use this tool to answer customer inquiries regarding outstanding balances, billing disputes, invoice history, or active payment methods.
When NOT to use: Do NOT use this tool for customer account profile details; use 'getCustomerDetails' instead. Do NOT use to search for customer IDs; use 'listCustomers' first. Do NOT use to check customer support issues; use 'listSupportTickets' instead.
Prerequisites: Requires a valid customerId (e.g., 'cust-001') previously discovered using 'listCustomers'.
[Behavior]
Operation: Read-only and idempotent. No financial transactions, charges, or balance mutations are executed.
Authorization: Requires 'readonly_agent', 'support_agent', or 'admin' role.
DLP / Sanitization: All payment card numbers, bank account numbers, and CVVs in responses are automatically masked with [REDACTED] by the zero-allocation gateway sanitizer.
[Parameters]
'customerId' (path, required): Unique customer identifier string (e.g. 'cust-001'). Must correspond to an active or archived customer account.
[Returns]
Returns HTTP 200 with JSON object containing: customerId, currency, balanceDue (decimal), paymentMethods (array of masked card tokens), and invoices (array of invoice objects with id, date, amount, status). Returns HTTP 404 if customerId is not found.
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": {
"customerId": "<customerId>"
},
"name": "getBillingHistory"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| customerId | Yes | Unique customer identifier in format 'cust-XXX' (e.g., 'cust-001'). Prerequisite is a valid customerId discovered from listCustomers. |