conecto. Get started
Bookkeeping

Add or change a tax

books_save_tax · Changes data · Markdown

Adds or changes a tax rate the books use (VAT, GST, sales tax), matched by name.

$0.001 a call

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

An example

Set up German VAT at 19% so expenses and entries can use it.

Your agent callsbooks_save_tax$0.001 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
{
  "name": "VAT 19%",
  "rate": 19
}
What comes back
{
  "tax": {
    "name": "VAT 19%",
    "rate": "19",
    "sales_account": "2100",
    "purchase_account": "1300",
    "reclaimable": true,
    "archived": false
  }
}

Use it when

Expenses or entries need a tax the books do not have yet.

What it does

A tax rate the books use (VAT, GST, sales tax), matched by name. Tax charged on sales is owed on sales_account (default: the sales tax account); tax paid on purchases is reclaimed on purchase_account (default: the tax to reclaim account; null when it can't be reclaimed, and it stays part of the cost). A rate in use can't change: add a new tax and archive the old one. Invoices make the taxes they need on their own. kind makes a new tax one the business owes itself, like Xero's reverse charge rates: rc_eu (services from another EU country), rc_abroad (from outside it), rc_home (reverse charge at home) or eu_goods (goods from another EU country); on an expense or a bank line it books the VAT owed and reclaimed at once, the amount paid being without VAT. kind import is import VAT paid at customs, no rate: what is booked with it is the VAT itself, reclaimed whole on the import VAT account (1310, made with it), where an expense or a bank line counts with no tax named (box 62 in Germany, box 4 in the UK). Conecto gives no tax advice; the rates are the business's.

What comes back

tax: its name, rate, sales_account (where tax on sales is owed), purchase_account (where tax on purchases is reclaimed), reclaimable, archived, and kind for VAT the business owes itself. Every reply also carries cost_usd and balance_usd.

Inputs

NameTypeWhat it is
nameRequiredstring1 to 60 characters.
ratenumber or stringPercent, e.g. 19. Up to 24 characters.
sales_accountstringAn account code from the chart, e.g. "6600". 1 to 20 characters.
purchase_accountstring or nullUp to 20 characters.
archivedboolean
new_namestringUp to 60 characters.
kindstringFor a new tax: VAT the business owes itself, or import VAT. One of: rc_eu,rc_abroad,rc_home,eu_goods,import.

The call

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

Terminal
curl -X POST https://api.conecto.chat/v1/tools/books_save_tax \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"VAT 19%","rate":19}'

When it refuses

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

CodeWhenWhat to do
no_books409The business keeps no books yet.Set them up with books_setup (base currency, start date).
not_found404No 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.
archived409The account or tax is archived.Use another one, or un-archive it with books_save_accounts.
invalid_input400A new tax has no rate, or an account is the wrong type for it.Give the rate as a percent; sales tax goes to a liability account.
rate_fixed409The tax is in use, so its rate stays.Add a new tax for the new rate and archive the old one.
name_taken409A tax with that name exists.Pick another name.
no_role409No account holds the tax role the tax needs.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