--- name: "invoices_record_prepayment" area: "invoices" title: "Record a prepayment" price: "$0.01" method: "POST" url: "https://api.conecto.chat/v1/tools/invoices_record_prepayment" mcp_server: "https://api.conecto.chat/mcp/invoices" auth: "Authorization: Bearer " docs_url: "https://conecto.chat/tools/invoices/invoices_record_prepayment" --- # Record a prepayment (`invoices_record_prepayment`) 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. Record money a customer paid before there is an invoice, like a deposit, as Xero's prepayments: it waits as their credit (CR-0001 on) until invoices_use_credit puts it on their invoice or pays it back. With tax_rate it carries its VAT, owed when the money came in (as the EU has it for advance payments); using it on the invoice takes that VAT back off, so the sale's VAT counts once. With books kept it is posted at once: the bank against Customer prepayments (2400, made when missing) and the tax owed. Price: $0.01 a call. A call that fails costs nothing. ## Use it when A customer paid ahead: a deposit on an order, an advance on a project. - For money toward an invoice already sent, use [invoices_record_payment](https://conecto.chat/tools/invoices/invoices_record_payment.md). ## Say this to your agent > Hotel Elbblick paid a 3,570 euro deposit on the dishwasher today, VAT included. ## Inputs | Name | Type | Required | Description | Allowed values | Default | |---|---|---|---|---|---| | `customer` | object | yes | Who paid: a CRM contact or company, or a name and email. | | | | `customer.contact_id` | integer | no | A CRM contact; fills the name and email. At least 1. | | | | `customer.company_id` | integer | no | A CRM company; fills the name. At least 1. | | | | `customer.name` | string | no | Who is billed, as printed. Up to 200 characters. | | | | `customer.email` | string | no | Where the document is emailed. Up to 254 characters. | | | | `customer.address` | string | no | Postal address, one line per row. Up to 1,000 characters. | | | | `customer.tax_id` | string | no | The customer's VAT or tax number, for business customers. A reverse-charge or intra-EU invoice needs their EU VAT ID, e.g. "FR12345678901". Up to 60 characters. | | | | `customer.country` | string | no | ISO 3166-1 code of the customer's country, e.g. "FR". Checks intra_eu and export invoices; e-invoices need it. Up to 2 characters. | | | | `amount` | number or string | yes | What they paid, tax included, e.g. "3570.00". Up to 24 characters. | | | | `currency` | string | no | ISO 4217, e.g. "USD", "EUR" or "JPY". Matches ^[A-Za-z]{3}$. | | | | `date` | string | no | When it came in. Default today. Matches ^\\d{4}-\\d{2}-\\d{2}$. | | | | `method` | string | no | | `"bank_transfer"`, `"card"`, `"cash"`, `"check"`, `"online"`, `"other"` | `"bank_transfer"` | | `reference` | string | no | Up to 120 characters. | | | | `note` | string | no | Up to 500 characters. | | | | `tax_rate` | number | no | The VAT in it, in percent, e.g. 19. Default none. 0 to 100. | | | ## Example Written for Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff. MCP: call `invoices_record_prepayment` on the MCP server `https://api.conecto.chat/mcp/invoices` with these arguments: ```json { "customer": { "name": "Hotel Elbblick GmbH", "email": "einkauf@elbblick.example" }, "amount": "3570.00", "tax_rate": 19, "method": "bank_transfer", "reference": "Deposit, dishwasher DW-500" } ``` REST: ```bash curl https://api.conecto.chat/v1/tools/invoices_record_prepayment \ -H "Authorization: Bearer $CONECTO_KEY" \ -H "Content-Type: application/json" \ -d '{"customer": {"name": "Hotel Elbblick GmbH", "email": "einkauf@elbblick.example"}, "amount": "3570.00", "tax_rate": 19, "method": "bank_transfer", "reference": "Deposit, dishwasher DW-500"}' ``` ## Response ```json { "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93", "tool": "invoices_record_prepayment", "status": "succeeded", "replayed": false, "cost_usd": "$0.01", "balance_usd": "$19.75", "result": { "credit": { "number": "CR-0001", "kind": "prepayment", "status": "open", "date": "2026-10-14", "currency": "EUR", "amount": "3570.00", "left": "3570.00", "tax_rate": "19", "tax": "570.00", "method": "bank_transfer", "reference": "Deposit, dishwasher DW-500", "note": null, "entry": 1, "customer": { "name": "Hotel Elbblick GmbH", "email": "einkauf@elbblick.example" }, "history": [ { "at": "2026-10-14T08:00:00+00:00", "what": "received", "amount": "3570.00" } ] } } } ``` `result`: credit: its number, the amount, its VAT, what is left, the customer and the entry that booked it. ## Errors | Code | Status | When | Fix | |---|---|---|---| | `not_found` | 404 | The customer's contact_id or company_id is not in the business's CRM. | Find the record with crm_search, or give a name and email instead. | | `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. | | `invalid_input` | 400 | The amount is 0 or not a number in the currency, the date is in the future, or the customer has no name. | Fix what the message names. | | `limit_reached` | 409 | The account has 5,000 open credits. | Use or pay back some first. | | `in_progress` | 409 | Another credit took the number at the same moment. | Call again. | 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_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_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.