--- name: "invoices_send" area: "invoices" title: "Send a quote or invoice" price: "$0.10" method: "POST" url: "https://api.conecto.chat/v1/tools/invoices_send" mcp_server: "https://api.conecto.chat/mcp/invoices" auth: "Authorization: Bearer " docs_url: "https://conecto.chat/tools/invoices/invoices_send" --- # Send a quote or invoice (`invoices_send`) 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. Send a draft: it takes the next number (gapless), its PDF is made and kept in the file store, and the customer is emailed a link to its page (to view, pay or accept it) and to the PDF. On a document already sent it emails it again (to `to`, if given). email: false sends it without emailing anyone, to hand the link over yourself. Emailing people outside the business needs a paid account. When the account keeps books (books_setup), a sent invoice is posted to them. Before an invoice or credit note takes its number it is checked against the law of the business's country (in the EU, the UK and Switzerland: the business's address and VAT ID, the customer's VAT ID and address where needed, why a line has no tax, the VAT in the national currency); what is missing is refused for free, warnings come back. With e_invoice set it also goes out as an EN 16931 e-invoice (Factur-X inside the PDF, or an XRechnung XML beside it), validated against the official schema first. Price: $0.10 a call. A call that fails costs nothing. ## Use it when A draft is ready for the customer, or a sent one should be emailed again. ## Say this to your agent > Send the Elbblick invoice to Lukas Meyer with a short thank-you. ## Inputs | Name | Type | Required | Description | Allowed values | Default | |---|---|---|---|---|---| | `invoice_id` | string | yes | The invoice_id invoices_create returned (quotes and credit notes have one too). Exactly 36 characters. | | | | `email` | boolean | no | false: number it and make the PDF and the page, but email no one. | | `true` | | `to` | string | no | Send to this address instead of the customer's email. Up to 254 characters. | | | | `message` | string | no | A short note in the email, e.g. "Thanks for your order!" (up to 2,000 characters) | | | | `link_hours` | integer | no | How long the PDF download link works, in hours (up to 168). 1 to 168. | | `24` | ## Example Written for Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff. MCP: call `invoices_send` on the MCP server `https://api.conecto.chat/mcp/invoices` with these arguments: ```json { "invoice_id": "2d9c4e7b-1a3f-4c5d-8e6f-0b1a2c3d4e5f", "message": "Thank you for your order. The chairs arrive in week 49." } ``` REST: ```bash curl https://api.conecto.chat/v1/tools/invoices_send \ -H "Authorization: Bearer $CONECTO_KEY" \ -H "Content-Type: application/json" \ -d '{"invoice_id": "2d9c4e7b-1a3f-4c5d-8e6f-0b1a2c3d4e5f", "message": "Thank you for your order. The chairs arrive in week 49."}' ``` ## Response ```json { "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93", "tool": "invoices_send", "status": "succeeded", "replayed": false, "cost_usd": "$0.10", "balance_usd": "$19.75", "result": { "invoice": { "invoice_id": "2d9c4e7b-1a3f-4c5d-8e6f-0b1a2c3d4e5f", "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/_u3Gmo2r0-jnEA3tOB97r7VmHS0qK7TS", "created_at": "2026-10-14T08:00:00+00:00", "sent_at": "2026-10-14T08:00:00+00:00", "credited": "0.00", "items": [ { "description": "Bistro chair, beech\nStackable, for terraces", "quantity": "40", "unit_price": "320", "tax_rate": "19", "discount_percent": "10", "amount": "12800.00", "discount": "1280.00", "tax": "2188.80", "total": "13708.80" }, { "description": "Delivery and setup", "quantity": "1", "unit_price": "150", "tax_rate": "19", "discount_percent": "0", "amount": "150.00", "discount": "0.00", "tax": "28.50", "total": "178.50" } ], "totals": { "subtotal": "12950.00", "subtotal_formatted": "€12,950.00", "discount": "1280.00", "discount_formatted": "€1,280.00", "tax": "2217.30", "tax_formatted": "€2,217.30", "total": "13887.30", "total_formatted": "€13,887.30", "credited": "0.00", "credited_formatted": "€0.00", "amount_paid": "0.00", "amount_paid_formatted": "€0.00", "balance": "13887.30", "balance_formatted": "€13,887.30", "taxes": [ { "rate": "19", "base": "11670.00", "amount": "2217.30", "amount_formatted": "€2,217.30" } ] }, "supply": { "label": "Date of supply", "text": "October 14, 2026", "from": "2026-10-14", "until": "2026-10-14" }, "tax_exemption": null, "tax_note": null, "vat_exchange_rate": null, "national_vat": null, "e_invoice": null, "notes": "", "payment_link": null, "business": { "name": "Hansen & Voss GmbH", "address": "Billbrookdeich 112\n22113 Hamburg\nGermany", "tax_id": "DE123456789", "email": "billing@hansenvoss.example", "phone": "+49 40 66969 100", "logo_file_id": "", "footer": "Please pay by bank transfer to Hansen & Voss GmbH\nIBAN DE89 3704 0044 0532 0130 00, BIC COBADEFFXXX", "tax_label": "VAT", "paper": "a4", "country": "DE", "legal_notes": "Hansen & Voss GmbH, Amtsgericht Hamburg HRB 123456\nManaging directors: Clara Hansen, Henrik Voss", "document_language": "" }, "pdf": { "file_id": "adfc06f7-22c0-45d5-bb24-bdfe19af441e", "name": "Invoice INV-0042.pdf", "content_type": "application/pdf", "size": "582 bytes", "size_bytes": 582, "sha256": "7a628ee1199dd863f0236a61a39b6729a977b4ea18a669e9930a57280cb2326e", "created_at": "2026-10-14T08:00:00+00:00", "download_url": "https://cncto.co/d/adfc06f7-22c0-45d5-bb24-bdfe19af441e?t=eyJmIjoiYWRmYzA2ZjctMjJjMC00NWQ1LWJiMjQtYmRmZTE5YWY0NDFlIiwiZXhwIjoxNzkyMTYwODk3fQ:1xHMRN:8J2-MHhqPVO21ZmnbiGiq9g8BSSRnWwvZxr10NUQ3Bs", "link_expires_in_hours": 24 }, "payments": [], "quote_id": null, "credit_notes": [], "viewed_at": null, "accepted_at": null, "declined_at": null, "paid_at": null, "voided_at": null, "void_reason": null, "last_emailed_at": "2026-10-14T08:00:00+00:00", "reminders_sent": 0, "history": [ { "at": "2026-10-14T08:00:00+00:00", "event": "created", "detail": "", "by": "key 4101 (Pip)" }, { "at": "2026-10-14T08:00:00+00:00", "event": "sent", "detail": "INV-0042", "by": "key 4101 (Pip)" } ] }, "emailed_to": "lukas.meyer@hotel-elbblick.example", "warnings": [] } } ``` `result`: invoice: the document in full, now numbered and sent, with its page and PDF links, its date of supply, any VAT in the national currency and, for an e-invoice, its format and XML file; emailed_to: who it went to (null with email: false); warnings: what the law asks for that is worth adding next time. ## Errors | Code | Status | When | Fix | |---|---|---|---| | `not_found` | 404 | No quote or invoice of the business has that invoice_id. | Find it with invoices_list and use its invoice_id. | | `profile_incomplete` | 409 | The business has no legal name or country on its documents yet. | Set them with invoices_set_profile (legal_name and country, and ideally the address, email and tax_id). | | `invoice_incomplete` | 409 | The invoice lacks what the law of the business's country needs on it: the business's address or VAT ID, the customer's VAT ID or address for a reverse charge, why a line has no tax. | Add what the message names (invoices_update, invoices_set_profile) and send again; nothing was numbered. | | `national_system_required` | 409 | The business is in a country whose domestic invoices must go through a national system (Italy, Poland, Belgium, Croatia, Romania, Hungary, Greece, Portugal; Spain from 2027, France from September 2027). | Send it through that system; invoices to customers abroad still work. | | `vat_id_invalid` | 409 | VIES says the customer's VAT ID is not valid, so the reverse-charge or intra-Community invoice can't go out. | Check the number with the customer and fix customer.tax_id with invoices_update. | | `no_rate` | 409 | The invoice is in another currency than the national one and its VAT must be shown in both, but there is no rate for the day. | Pass vat_exchange_rate with invoices_update (UK businesses always give it). | | `no_items` | 409 | The draft has no lines. | Add lines with invoices_update. | | `invalid_dates` | 409 | The due date or valid_until is before the issue date, or the issue date is in the future or before the last invoice numbered in the series (numbers follow the dates). | Fix it with invoices_update; clearing issue_date dates it the day it is sent. | | `void` | 409 | The document is void. | Create a new one. | | `already_paid` | 409 | The invoice is paid in full. | There is nothing to send. | | `already_accepted` | 409 | The customer accepted the quote already. | Turn it into an invoice with invoices_convert_quote. | | `already_declined` | 409 | The customer declined the quote. | Create a new quote. | | `already_sent` | 409 | The document was sent already. | Call again with email: true to email it again. | | `number_taken` | 409 | The next number is used already. | Set a higher next number with invoices_set_profile. | | `storage_full` | 409 | The file store has no room for the PDF. | Delete files with files_delete, or add room with files_add_storage. | | `no_email` | 409 | The document has no customer email to send to. | Pass to, or set customer.email on the draft with invoices_update. | | `payment_required_for_outbound` | 402 | The balance is still free credit, which cannot email people outside the business. | Top up once (POST /v1/topups), or send with email: false and hand the link over yourself. | | `suppressed` | 422 | The address bounced, complained or unsubscribed before. | Send to another address with to. | | `too_many_emails` | 429 | This document was emailed as often as it may in 24 hours. | Try again tomorrow. | | `daily_email_limit` | 429 | The business emailed as many quotes and invoices in 24 hours as it may. | Try again tomorrow, or ask Conecto for more. | | `email_failed` | 502 | The email could not be sent; nothing was charged. | Call again in a moment. | | `before_start` | 409 | The date is before the books start. | Use a later date, or set an earlier start with books_setup. | | `period_locked` | 409 | The books are locked for that date. | Use a later date, or unlock the period with books_lock. | | `no_role` | 409 | The books have no account for a role the posting needs. | Give an account that role with books_save_accounts. | | `unavailable` | 503 | The PDF could not be made right now; nothing was charged. | Call again in a moment. | 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_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_list](https://conecto.chat/tools/invoices/invoices_list.md): Quotes and invoices, newest first, by kind, status (also overdue, unpaid and expired), customer and issue date. 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.