check_invoice_status
Billing · Read-only · account-scoped
Check one invoice, or sweep every unpaid invoice for the shop — the receivables question.
Usage
Two modes: pass invoiceId to check one invoice, or omit it to get every unpaid invoice, oldest first — the question a shop owner usually means by "what hasn't been paid?".
Read paymentState, not status. Stripe leaves a declined invoice at status open, identical to one nobody has tried to pay. paymentState: "declined" means a card was attempted and failed — say so plainly. "awaiting-payment" means no attempt has been made yet. Each result carries a human-readable explanation; relay it rather than inventing a reading.
No card details or payment credentials are returned, and none can be requested through this tool.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
invoiceId | string | No | One invoice to check — either the Stripe id from an issue_invoice result (starts with "in_") or the printed invoice number. OMIT THIS to sweep every unpaid invoice for the shop instead. Example: "ALRVAKWA-0001" |
limit | positive integer | No | Sweep mode only: how many unpaid invoices to return, oldest first. Defaults to 25. Example: 25 |
Description advertised to clients
The exact description a fully entitled MCP client discovers — the workflow contracts travel with the tool, so a client with no system prompt still uses it correctly. An account missing a licence for content this tool reaches sees the same text behind a [Licensed content — not enabled on this account] or [Partially available] notice:
Check whether an invoice has been paid, or sweep every unpaid invoice for the shop. THIS TOOL IS READ-ONLY: it reads MotorAdvisor's payment provider (Stripe) and changes nothing there. It writes NOTHING to MOTOR — MOTOR DaaS is read-only on this server and this tool does not touch it. The shop is NEVER a parameter: it is resolved from the authenticated account, so this tool can only read the caller's own shop. TWO MODES. Pass invoiceId to check one invoice. OMIT invoiceId to get every unpaid invoice, oldest first — that is the receivables question ("what hasn't been paid?") and the one an owner usually means. READ paymentState, NOT status, when telling the user what happened. Stripe leaves a DECLINED invoice at status "open", identical to one nobody has tried to pay, so "open" alone does not mean the customer simply hasn't got to it. paymentState "declined" means a card was attempted and FAILED — say so plainly and tell the advisor to contact the customer; never report it as merely unpaid. paymentState "awaiting-payment" means no attempt has been made yet. Each result also carries a human-readable explanation — relay it rather than inventing your own reading. NO CARD DETAILS AND NO PAYMENT CREDENTIALS ARE RETURNED by this tool, and none can be requested through it. Preconditions, each refused by name when unmet: the account must belong to a shop; the shop must have a connected Stripe account; a named invoice must exist on it.
Example — One invoice by printed number
Captured from the live server, 2026-08-20 — the standing demo invoice.
Request
{
"invoiceId": "ALRVAKWA-0001"
}
Response
{
"invoiceId": "in_1U3eHUR4WQPNzEYlDhYqbFHn",
"number": "ALRVAKWA-0001",
"status": "open",
"paymentState": "awaiting-payment",
"explanation": "Sent and not yet paid. No payment has been attempted.",
"totalCents": 18000,
"total": "$180.00",
"amountPaidCents": 0,
"amountPaid": "$0.00",
"customerName": "Jane Rivera",
"dueDate": "2026-09-11",
"overdue": false,
"overdueDays": 0,
"lines": [
{
"description": "A/C Compressor — Remove & Replace — 1.2 hr @ $150.00/hr",
"amountCents": 18000,
"amount": "$180.00"
}
]
}