Record a prepayment

invoices_record_prepayment · Changes data · Markdown

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

From your agent’s balance. A call that fails costs nothing.

Hotel Elbblick paid a 3,570 euro deposit on the dishwasher today, VAT included.

Your agent callsinvoices_record_prepayment$0.01 a call

The example business is Hansen & Voss, a restaurant-equipment wholesaler in Hamburg with 60 staff. The reply is the one the tool really gives.

With these arguments

{
  "customer": {
    "name": "Hotel Elbblick GmbH",
    "email": "einkauf@elbblick.example"
  },
  "amount": "3570.00",
  "tax_rate": 19,
  "method": "bank_transfer",
  "reference": "Deposit, dishwasher DW-500"
}

What comes back

{
  "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"
      }
    ]
  }
}

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.

What it does

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.

What comes back

credit: its number, the amount, its VAT, what is left, the customer and the entry that booked it. Every reply also carries cost_usd and balance_usd.

Inputs

Name	Type	What it is
`customer`Required	object	Who paid: a CRM contact or company, or a name and email.
`customer.contact_id`	integer	A CRM contact; fills the name and email. At least 1.
`customer.company_id`	integer	A CRM company; fills the name. At least 1.
`customer.name`	string	Who is billed, as printed. Up to 200 characters.
`customer.email`	string	Where the document is emailed. Up to 254 characters.
`customer.address`	string	Postal address, one line per row. Up to 1,000 characters.
`customer.tax_id`	string	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	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`Required	number or string	What they paid, tax included, e.g. "3570.00". Up to 24 characters.
`currency`	string	ISO 4217, e.g. "USD", "EUR" or "JPY". Matches ^[A-Za-z]{3}$.
`date`	string	When it came in. Default today. Matches ^\d{4}-\d{2}-\d{2}$.
`method`	string	One of: bank_transfer,card,cash,check,online,other. Default: bank_transfer.
`reference`	string	Up to 120 characters.
`note`	string	Up to 500 characters.
`tax_rate`	number	The VAT in it, in percent, e.g. 19. Default none. 0 to 100.

The call

Over MCP, call invoices_record_prepayment on https://api.conecto.chat/mcp/invoices. Over REST:

Terminal

curl -X POST 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"}'

When it refuses

A refused call costs nothing and says what to do next.

Code	When	What to do
`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.

More Invoices tools

All 24 tools

Give this to your agent.

Set up Conecto from https://conecto.chat/SKILL.md

Record a prepayment

An example

Use it when

What it does

What comes back

Inputs

The call

When it refuses

More Invoices tools

Give this to your agent.