Method

invoice.post

Post a document to an A/R or A/P account: its transaction, lot, frozen tax tables and terms.

Posts an unposted document to an A/Receivable account (invoices) or A/Payable account (bills, vouchers) in the document's currency: it makes the transaction, puts the balance in a new lot, and freezes copies of the document's billing term and the tax tables of its lines. The transaction is read-only until the document is unposted.

By default the lines are accumulated into one split per income or expense account (accumulateSplits), as GnuCash's default preference is. dueDate defaults to the billing term's. Lines or tax accounts in another commodity need a prices entry each. Everything is checked first, and a document with no lines, a line without an account or a wrong posting account is refused with invalid and nothing changed; GnuCash can stop halfway.

Examples

Example: with a copy of the synthetic/business-editable example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"invoice.post","params":{"invoice":"71803cac5d8e4dceabfd0d56ec5e7521","account":"Assets:Receivable","postDate":"2024-03-10","dueDate":"2024-04-10"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "transaction": "…",
    "lot": "…",
    "due": "2024-04-10T10:59:00Z"
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"invoice.post","params":{"invoice":"71803cac5d8e4dceabfd0d56ec5e7521","account":"Assets:Receivable","postDate":"2024-03-10"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": 2003,
    "message": "document 000002 is already posted",
    "data": {
      "help": "error/conflict"
    }
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
invoice.post {"invoice":"71803cac5d8e4dceabfd0d56ec5e7521","account":"Assets:Receivable","postDate":"2024-03-10","dueDate":"2024-04-10"}
invoice.post {"invoice":"71803cac5d8e4dceabfd0d56ec5e7521","account":"Assets:Receivable","postDate":"2024-03-10"}
EOF

It fails with exit status 2, printing on standard error:

{
  "error": {
    "code": 2003,
    "message": "document 000002 is already posted",
    "data": {
      "help": "error/conflict"
    }
  }
}

MCP tool call

Tool call:

{"name":"invoice.post","arguments":{"invoice":"71803cac5d8e4dceabfd0d56ec5e7521","account":"Assets:Receivable","postDate":"2024-03-10","dueDate":"2024-04-10"}}

Result:

{
  "structuredContent": {
    "transaction": "…",
    "lot": "…",
    "due": "2024-04-10T10:59:00Z"
  }
}

Tool call:

{"name":"invoice.post","arguments":{"invoice":"71803cac5d8e4dceabfd0d56ec5e7521","account":"Assets:Receivable","postDate":"2024-03-10"}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2003,
      "name": "conflict",
      "message": "document 000002 is already posted",
      "data": {
        "help": "error/conflict"
      }
    }
  }
}

Effect: write, on the Book.

Params

Params of invoice.post.

  • invoice (Guid, required): The document.
  • account (AccountRef, required): The A/Receivable (customer documents) or A/Payable (bills, vouchers) account, in the document currency.
  • postDate (Date, required): The posting date.
  • dueDate (Date or null): The due date. Default: from the document's billing term, else the posting date.
  • memo (string or null): Memo for the A/R or A/P split and accumulated splits.
  • accumulateSplits (boolean or null): One split per account rather than per entry (GnuCash's default: true).
  • autoPay (boolean): Then apply the owner's open pre-payments and opposite documents (GnuCash's default: false).
  • prices (array of PriceParam): Prices for entries posting to accounts in another commodity.

Result

Result of invoice.post.

  • transaction (Guid, required): The posted transaction.
  • lot (Guid, required): The document's lot.
  • due (Timestamp, required): The due instant stored on the transaction.