--- name: "invoices_list" area: "invoices" title: "List quotes and invoices" price: "free" method: "POST" url: "https://api.conecto.chat/v1/tools/invoices_list" mcp_server: "https://api.conecto.chat/mcp/invoices" auth: "Authorization: Bearer " docs_url: "https://conecto.chat/tools/invoices/invoices_list" --- # List quotes and invoices (`invoices_list`) Quotes and invoices, newest first, by kind, status (also overdue, unpaid and expired), customer and issue date. Quotes, invoices and credit notes, newest first, filtered by kind, status (also overdue, unpaid and expired), customer and issue date. Totals and balances come with each one. Price: Free up to 1,000,000 reads a month for the whole account, then $0.50 per 10,000 reads. A call that fails costs nothing. ## Use it when Someone asks what is unpaid, overdue or still open. - For the totals owed, without the list, use [invoices_summary](https://conecto.chat/tools/invoices/invoices_summary.md). ## Say this to your agent > Which invoices haven't been paid yet? ## Inputs | Name | Type | Required | Description | Allowed values | Default | |---|---|---|---|---|---| | `kind` | string | no | | `"quote"`, `"invoice"`, `"credit_note"` | | | `status` | string | no | overdue: past due with a balance. unpaid: sent invoices with a balance. expired: sent quotes past valid_until. | `"draft"`, `"sent"`, `"accepted"`, `"declined"`, `"paid"`, `"partially_paid"`, `"void"`, `"overdue"`, `"unpaid"`, `"expired"` | | | `contact_id` | integer | no | At least 1. | | | | `company_id` | integer | no | At least 1. | | | | `customer` | string | no | Part of the customer's name or email, or of the number. Up to 200 characters. | | | | `date_from` | string | no | Issued on or after (YYYY-MM-DD). Drafts have no issue date yet. Matches ^\\d{4}-\\d{2}-\\d{2}$. | | | | `date_to` | string | no | Issued on or before. Matches ^\\d{4}-\\d{2}-\\d{2}$. | | | | `limit` | integer | no | 1 to 100. | | `25` | | `offset` | integer | no | At least 0. | | `0` | ## Example Written for Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff. MCP: call `invoices_list` on the MCP server `https://api.conecto.chat/mcp/invoices` with these arguments: ```json { "kind": "invoice", "status": "unpaid" } ``` REST: ```bash curl https://api.conecto.chat/v1/tools/invoices_list \ -H "Authorization: Bearer $CONECTO_KEY" \ -H "Content-Type: application/json" \ -d '{"kind": "invoice", "status": "unpaid"}' ``` ## Response ```json { "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93", "tool": "invoices_list", "status": "succeeded", "replayed": false, "cost_usd": "$0.00", "balance_usd": "$19.75", "result": { "invoices": [ { "invoice_id": "dc06a8a9-037e-4bc1-b064-c75202c55b0f", "kind": "invoice", "number": "INV-0042", "status": "sent", "currency": "EUR", "issue_date": "2026-10-14", "due_date": "2026-10-28", "overdue": false, "days_overdue": 0, "customer": { "contact_id": null, "company_id": null, "name": "Hotel Elbblick GmbH", "email": "lukas.meyer@hotel-elbblick.example", "address": "Elbchaussee 120\n22763 Hamburg", "tax_id": "", "country": null }, "total": "13887.30", "total_formatted": "€13,887.30", "amount_paid": "0.00", "balance": "13887.30", "balance_formatted": "€13,887.30", "public_url": "https://cncto.co/i/2yjFWMMMxFslGRDgAAhem_gxc2VYoP84", "created_at": "2026-10-14T08:00:00+00:00", "sent_at": "2026-10-14T08:00:00+00:00", "credited": "0.00" } ], "count": 1, "total": 1, "today": "2026-10-14" } } ``` `result`: The documents, newest first, each with its number, kind, status, customer, dates, total and balance; how many are on the page, the total, and today's date. ## Errors | Code | Status | When | Fix | |---|---|---|---| | `invalid_input` | 400 | A date is not a real date as YYYY-MM-DD. | Send dates like 2026-10-01. | The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md ## Related - [invoices_set_profile](https://conecto.chat/tools/invoices/invoices_set_profile.md): Sets the business details on quotes and invoices: name, country, address, tax ID, logo, terms, tax, numbering, how to pay and legal notes. $0.001 a call. - [invoices_get_profile](https://conecto.chat/tools/invoices/invoices_get_profile.md): The business details on quotes and invoices, the next numbers, and what is missing before documents can be sent. Free up to 1,000,000 reads a month. - [invoices_connect_stripe](https://conecto.chat/tools/invoices/invoices_connect_stripe.md): Connects the business's own Stripe account with a restricted key, so invoices can be paid online; the money goes straight to the business. $0.001 a call. - [invoices_create](https://conecto.chat/tools/invoices/invoices_create.md): Creates a draft quote or invoice: the customer, the lines, the currency and the dates. $0.01 a call. - [invoices_update](https://conecto.chat/tools/invoices/invoices_update.md): Changes a draft quote or invoice; customer and lines replace the old ones. $0.01 a call. - [invoices_send](https://conecto.chat/tools/invoices/invoices_send.md): Sends a draft: it gets the next number, its PDF is made, and the customer is emailed a link to view, pay or accept it. $0.10 a call. - [invoices_get](https://conecto.chat/tools/invoices/invoices_get.md): One quote or invoice in full, by invoice_id or number: lines, totals, taxes, payments, history, its page and a fresh PDF link. Free up to 1,000,000 reads a month. - [invoices_convert_quote](https://conecto.chat/tools/invoices/invoices_convert_quote.md): Turns an accepted quote into a draft invoice with the same customer and lines. $0.01 a call. - [invoices_record_payment](https://conecto.chat/tools/invoices/invoices_record_payment.md): Records money received against a sent invoice, or a refund; the invoice becomes partially paid or paid. $0.01 a call. - [invoices_record_prepayment](https://conecto.chat/tools/invoices/invoices_record_prepayment.md): Records a customer's deposit before there is an invoice, like Xero's prepayments; it waits as their credit, with its VAT owed at once. $0.01 a call. - [invoices_use_credit](https://conecto.chat/tools/invoices/invoices_use_credit.md): Puts a customer's credit on their invoice, like Xero's allocate credit, or pays it back to them. $0.01 a call. - [invoices_list_credits](https://conecto.chat/tools/invoices/invoices_list_credits.md): Lists customers' credits, deposits and overpayments, with what is left on each. Free up to 1,000,000 reads a month. - [invoices_remind](https://conecto.chat/tools/invoices/invoices_remind.md): Emails the customer a reminder about a sent invoice with a balance, at most once a day. $0.02 a call. - [invoices_remind_overdue](https://conecto.chat/tools/invoices/invoices_remind_overdue.md): Emails a reminder about every invoice at least some days overdue, the longest overdue first. $0.02 per reminder sent. - [invoices_set_expected_date](https://conecto.chat/tools/invoices/invoices_set_expected_date.md): Notes the day a customer says they will pay an invoice, so the cash flow forecast counts the money then, even when the invoice is overdue. Free. - [invoices_create_credit_note](https://conecto.chat/tools/invoices/invoices_create_credit_note.md): Corrects a sent invoice with a numbered credit note: all of it, some of its lines or an amount, emailed like an invoice. $0.10 a call. - [invoices_void](https://conecto.chat/tools/invoices/invoices_void.md): Voids a document: a sent one keeps its number but can no longer be paid or accepted; a draft is discarded. $0.01 a call. - [invoices_save_repeating](https://conecto.chat/tools/invoices/invoices_save_repeating.md): Makes an invoice again every so many weeks, months or years, drafted or sent on its day, with [Month] and [Year] filled in, like Xero's repeating invoices. $0.001 a call. - [invoices_list_repeating](https://conecto.chat/tools/invoices/invoices_list_repeating.md): Lists the repeating invoices: who each is for, how often, the next dates, and what each made. Free up to 1,000,000 reads a month. - [invoices_delete_repeating](https://conecto.chat/tools/invoices/invoices_delete_repeating.md): Stops a repeating invoice for good; the invoices it made stay. Free. - [invoices_statement](https://conecto.chat/tools/invoices/invoices_statement.md): Makes a customer statement, outstanding or activity, as a PDF, and emails it when asked, like Xero's statements. $0.05 a call. - [invoices_summary](https://conecto.chat/tools/invoices/invoices_summary.md): What customers owe, per currency: outstanding, overdue and paid this month, and the quotes still open. Free up to 1,000,000 reads a month. - [invoices_report](https://conecto.chat/tools/invoices/invoices_report.md): Aged receivables on any day, or sales per customer for a period with the credit notes taken off. Free up to 1,000,000 reads a month.