Guide

Set up the business features

Prepare a book for invoices and bills: receivable and payable accounts, tax tables, billing terms, document numbering and your company's details.

GnuCash's business features (customers, vendors, employees, invoices, bills and payments) rest on a few settings made once per book. This guide sets them up. Then Invoices and bills and Process payments can use them.

Steps

  1. Accounts. Every posted document goes to a control account: money customers owe you is in an RECEIVABLE account, money you owe vendors in a PAYABLE account, and each must be in the document's currency. Create them with account.create. Also create an income account for what you sell, an expense account for what you buy, and a liability account for each tax you collect.
  2. Tax tables. taxTable.create names a tax and its lines: each line is a tax account, an amount and a type, either percent of the price or a fixed value. A table can have several lines, for a tax plus a levy.
  3. Billing terms. billTerm.create names a payment rule. days: due so many days after the posting date (dueDays). proximo: due on a day of the month, and cutoff says after which day of the month a document waits until the next. discountDays and discount store an early-payment discount.
  4. Numbering. Documents, customers and others take their numbers from counters. counter.list shows them; counter.set sets last (the last number used, so the next is one more) and a format such as INV-%04li.
  5. Company details. book.setOptions sets companyName, companyAddress (lines separated by newlines), companyContactPerson, companyPhoneNumber, companyFaxNumber, companyEmailAddress, companyWebsiteUrl, companyId and taxNumber. They print in the header of the invoice (Print an invoice). book.options reads them back.
  6. Defaults. A customer or vendor can name a tax table and billing term of its own; see customer.create.

Example

The accounts for the business features, in a new book:

Example: with a new, empty book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"account.create","params":{"name":"Accounts Receivable","type":"RECEIVABLE","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "type": "RECEIVABLE",
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"account.create","params":{"name":"Accounts Payable","type":"PAYABLE","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "type": "PAYABLE",
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":3,"method":"account.create","params":{"name":"Sales Tax","type":"LIABILITY","commodity":"USD"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": "…"
}

Request:

{"jsonrpc":"2.0","id":4,"method":"taxTable.create","params":{"name":"Sales tax 8%","entries":[{"account":"Sales Tax","amount":"8","type":"percent"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "name": "Sales tax 8%",
    "entries": [
      {
        "accountName": "Sales Tax",
        "amount": {
          "num": "8",
          "denom": "1"
        },
        "type": "percent",
        "…": "…"
      }
    ],
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":5,"method":"billTerm.create","params":{"name":"Net14","type":"days","dueDays":14}}

Response:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "name": "Net14",
    "type": "days",
    "dueDays": 14,
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":6,"method":"counter.set","params":{"name":"gncInvoice","last":41,"format":"INV-%04li"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "name": "gncInvoice",
    "last": 41,
    "format": "INV-%04li",
    "next": "INV-0042",
    "…": "…"
  }
}

Request:

{"jsonrpc":"2.0","id":7,"method":"book.setOptions","params":{"companyName":"Acme Ltd","companyAddress":"1 Main St\nSpringfield","companyEmailAddress":"billing@acme.example"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "companyName": "Acme Ltd",
    "companyEmailAddress": "billing@acme.example",
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
account.create {"name":"Accounts Receivable","type":"RECEIVABLE","commodity":"USD"}
account.create {"name":"Accounts Payable","type":"PAYABLE","commodity":"USD"}
account.create {"name":"Sales Tax","type":"LIABILITY","commodity":"USD"}
taxTable.create {"name":"Sales tax 8%","entries":[{"account":"Sales Tax","amount":"8","type":"percent"}]}
billTerm.create {"name":"Net14","type":"days","dueDays":14}
counter.set {"name":"gncInvoice","last":41,"format":"INV-%04li"}
book.setOptions {"companyName":"Acme Ltd","companyAddress":"1 Main St\nSpringfield","companyEmailAddress":"billing@acme.example"}
EOF

It prints:

[
  {
    "type": "RECEIVABLE",
    "…": "…"
  },
  {
    "type": "PAYABLE",
    "…": "…"
  },
  "…",
  {
    "name": "Sales tax 8%",
    "entries": [
      {
        "accountName": "Sales Tax",
        "amount": {
          "num": "8",
          "denom": "1"
        },
        "type": "percent",
        "…": "…"
      }
    ],
    "…": "…"
  },
  {
    "name": "Net14",
    "type": "days",
    "dueDays": 14,
    "…": "…"
  },
  {
    "name": "gncInvoice",
    "last": 41,
    "format": "INV-%04li",
    "next": "INV-0042",
    "…": "…"
  },
  {
    "companyName": "Acme Ltd",
    "companyEmailAddress": "billing@acme.example",
    "…": "…"
  }
]

MCP tool call

Tool call:

{"name":"account.create","arguments":{"name":"Accounts Receivable","type":"RECEIVABLE","commodity":"USD"}}

Result:

{
  "structuredContent": {
    "type": "RECEIVABLE",
    "…": "…"
  }
}

Tool call:

{"name":"account.create","arguments":{"name":"Accounts Payable","type":"PAYABLE","commodity":"USD"}}

Result:

{
  "structuredContent": {
    "type": "PAYABLE",
    "…": "…"
  }
}

Tool call:

{"name":"account.create","arguments":{"name":"Sales Tax","type":"LIABILITY","commodity":"USD"}}

Result:

{
  "content": [
    {
      "type": "text",
      "text": "\"…\""
    }
  ]
}

Tool call:

{"name":"taxTable.create","arguments":{"name":"Sales tax 8%","entries":[{"account":"Sales Tax","amount":"8","type":"percent"}]}}

Result:

{
  "structuredContent": {
    "name": "Sales tax 8%",
    "entries": [
      {
        "accountName": "Sales Tax",
        "amount": {
          "num": "8",
          "denom": "1"
        },
        "type": "percent",
        "…": "…"
      }
    ],
    "…": "…"
  }
}

Tool call:

{"name":"billTerm.create","arguments":{"name":"Net14","type":"days","dueDays":14}}

Result:

{
  "structuredContent": {
    "name": "Net14",
    "type": "days",
    "dueDays": 14,
    "…": "…"
  }
}

Tool call:

{"name":"counter.set","arguments":{"name":"gncInvoice","last":41,"format":"INV-%04li"}}

Result:

{
  "structuredContent": {
    "name": "gncInvoice",
    "last": 41,
    "format": "INV-%04li",
    "next": "INV-0042",
    "…": "…"
  }
}

Tool call:

{"name":"book.setOptions","arguments":{"companyName":"Acme Ltd","companyAddress":"1 Main St\nSpringfield","companyEmailAddress":"billing@acme.example"}}

Result:

{
  "structuredContent": {
    "companyName": "Acme Ltd",
    "companyEmailAddress": "billing@acme.example",
    "…": "…"
  }
}