Book an expense

books_record_expense · Changes data · Markdown

Books a cost the business paid, with its tax split off and the receipt attached.

$0.01 a call

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

Book the 238 euros we paid Hamburg Energie for the warehouse's electricity on October 5, VAT included. The receipt is in our files.

Your agent callsbooks_record_expense$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

{
  "date": "2026-10-05",
  "amount": "238.00",
  "account": "6800",
  "tax": "VAT 19%",
  "vendor": "Hamburg Energie",
  "reference": "RE 2026-10-5521",
  "receipt_file_id": "4c1f7e92-3a6b-4d8e-b5c0-9e2d1f3a7b68"
}

What comes back

{
  "entry": {
    "entry": 3,
    "date": "2026-10-05",
    "memo": "Expense: Hamburg Energie",
    "reference": "RE 2026-10-5521",
    "party": "Hamburg Energie",
    "source": "expense",
    "total": "238.00",
    "currency": "EUR",
    "rate": null,
    "lines": [
      {
        "account": "6800",
        "account_name": "Utilities and phone",
        "debit": "200.00",
        "credit": null,
        "description": "Hamburg Energie",
        "tax": "VAT 19%"
      },
      {
        "account": "1300",
        "account_name": "Tax to reclaim",
        "debit": "38.00",
        "credit": null,
        "description": "VAT 19%",
        "tax": "VAT 19%"
      }
    ],
    "reverses": null,
    "reversed_by": null,
    "receipt_file_id": "4c1f7e92-3a6b-4d8e-b5c0-9e2d1f3a7b68",
    "recorded_at": "2026-10-15T14:29:47+00:00",
    "recorded_by": "key 4101 (Pip)"
  }
}

Use it when

The business paid for something: a subscription, electricity, supplies, a repair.

For a supplier bill to pay later, use purchasing_create_bill.
For anything else that moves money between accounts, use books_record_entry.

What it does

Book a cost the business paid: account is what it was for (an expense, or an asset like equipment), paid_from where the money came from (default the bank account; a card, cash or the owner's account). paid_by instead (an email) makes it an expense claim, like Xero's: someone paid with their own money and is paid back with books_repay_claims. With a tax, the tax to reclaim is split off (amount includes it unless amount_includes_tax is false). Attach the receipt from the file store. A negative amount is a refund.

What comes back

The entry booked: its number, date, memo, party, receipt, and lines with the tax split off; with paid_by, claim: the expense claim to pay back. Every reply also carries cost_usd and balance_usd.

Inputs

Name	Type	What it is
`date`Required	string	YYYY-MM-DD. Matches ^\d{4}-\d{2}-\d{2}$.
`amount`Required	number or string	e.g. "119.00". Up to 24 characters.
`account`Required	string	An account code from the chart, e.g. "6600". 1 to 20 characters.
`paid_from`	string	An account code from the chart, e.g. "6600". 1 to 20 characters.
`tax`	string	A tax by name (books_get lists them), e.g. "VAT 19%". Up to 60 characters.
`amount_includes_tax`	boolean	Default: true.
`vendor`	string	Up to 200 characters.
`memo`	string	Up to 500 characters.
`reference`	string	e.g. the receipt number. Up to 120 characters.
`receipt_file_id`	string	A file_id from the file store. Exactly 36 characters.
`currency`	string	When it is not the base currency, e.g. "USD". The rate is then rate, a standing rate, or the European Central Bank's for the date. Matches ^[A-Za-z]{3}$.
`rate`	number or string	One unit of currency in the base currency, e.g. "0.9241". Default: a standing rate, else the European Central Bank's reference rate for the date. Up to 24 characters.
`tracking`	object	Tracking options by category, e.g. {"Department": "Service"} (books_list_tracking).
`paid_by`	string	The email of whoever paid it privately and is paid back: an expense claim. Not with paid_from. Up to 254 characters.
`paid_by_name`	string	Up to 200 characters.

The call

Over MCP, call books_record_expense on https://api.conecto.chat/mcp/books. Over REST:

Terminal

curl -X POST https://api.conecto.chat/v1/tools/books_record_expense \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"2026-10-05","amount":"238.00","account":"6800","tax":"VAT 19%","vendor":"Hamburg Energie","reference":"RE 2026-10-5521","receipt_file_id":"4c1f7e92-3a6b-4d8e-b5c0-9e2d1f3a7b68"}'

When it refuses

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

Code	When	What to do
`no_books`409	The business keeps no books yet.	Set them up with books_setup (base currency, start date).
`not_found`404	No account, tax, entry or file of the books has that code, name or id.	Check the codes with books_list_accounts and the taxes with books_get.
`archived`409	The account or tax is archived.	Use another one, or un-archive it with books_save_accounts.
`unbalanced`400	The debits and credits do not add up to the same amount.	Make the lines balance.
`before_start`409	The date is before the books start.	Use a later date.
`period_locked`409	The books are locked for that date.	Use a later date, or unlock with books_lock.
`no_rate`409	There is no exchange rate for the currency on that day.	Pass rate, or set a standing rate with books_setup rates.
`rates_loading`503	The day's exchange rates are still loading.	Try again in a few minutes, or pass rate.
`invalid_input`400	The amount is 0 or not a number, the date is not valid, paid_by is not an email, or both paid_by and paid_from are given.	Send an amount like "238.00" and a date like 2026-10-05.
`no_role`409	No account holds a role the expense needs (the bank, or tax to reclaim).	Give an account the role with books_save_accounts.

More Bookkeeping tools

All 33 tools

Give this to your agent.

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

Book an expense

An example

Use it when

What it does

What comes back

Inputs

The call

When it refuses

More Bookkeeping tools

Give this to your agent.