Report

Printable Invoice

The Printable Invoice report.

Prints one business document, an invoice, bill, credit note or expense voucher, as GnuCash's Printable Invoice (Reports › Business › Printable Invoice) does: its title and number, the document's dates, billing ID and terms, the customer's or vendor's address, your company's details, one row per entry (date, description, action, quantity, unit price, discount, taxable, total) and the net price, tax, total price, payments and amount due. Use it to print or send a document; report.export gives the same report as one HTML page.

The document is the General › Invoice Number option: its GUID, as invoice.list and invoice.get give it. Without one, or with a GUID that names no document, the report shows GnuCash's warning "No valid invoice selected" and nothing else. Figures are exact: quantities, prices and discounts are never rounded for display, and amounts are in the document's currency.

Key options

  • General › Custom Title: replaces "Invoice", "Bill" or "Expense Voucher" in the heading.
  • Display Columns: which entry columns show. All but Tax Amount are on.
  • Display: Due Date, References, Billing Terms, Billing ID, Payments, Invoice Notes, Job Details, the Extra Notes printed at the foot, the "Payable to" and "Company contact" lines, and the Minimum # of entries (blank rows are added up to it).
  • Layout › Row 1 to 3 Left and Right: what each of the six header cells holds: the client, the company, the invoice details, today's date, the picture or nothing.
  • Layout › Picture Location: a picture for the header, as a path or file:/// URL. It goes into the page as a file:/// URL, as GnuCash writes it; red-ale never reads the file, so the picture shows only where the page is opened on a machine that has it.
  • Layout › CSS: the CSS of the page. Blocks and cells carry GnuCash's class names (entries-table, invoice-title, client-name, …), so the layout can be changed by class.

Your company's name, address, ID, contact, phone, fax, email, URL and tax number come from the Book's Business options: set them with book.setOptions.

Printing an invoice as GnuCash does

GnuCash's Print Invoice runs the Book's Default Invoice Report for the document. To do the same:

  1. Read defaultInvoiceReport with book.options.
  2. If it names an invoice report red-ale has, run that report. An invoice report is a template whose General › Invoice Number option has type invoice (report.options shows it), or a saved configuration of one; report.list lists them.
  3. Otherwise (no default, or one naming a report red-ale doesn't have, such as GnuCash's Easy or Fancy Invoice) run the Printable Invoice, as GnuCash falls back to it.
  4. Pass the document as {"General": {"Invoice Number": "<guid>"}} to report.run or report.export.

Examples

The first invoice of a fixture book: one entry of 2 at $3.00, so $6.00 due.

Example: with a copy of the reports/transaction example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"report.run","params":{"report":"Printable Invoice","options":{"General":{"Invoice Number":"30000000000000000000000000000000"}}}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "report": {
      "guid": "5123a759ceb9483abf2182d01c140e8d",
      "name": "Printable Invoice",
      "configuration": null
    },
    "title": "",
    "sections": [
      {
        "blocks": [
          {
            "kind": "text",
            "text": "Invoice #0001",
            "role": "heading",
            "class": "invoice-title"
          },
          "…",
          "…",
          "…",
          {
            "kind": "table",
            "class": "entries-table",
            "rows": [
              {
                "cells": [
                  {
                    "date": "2024-03-15T12:00:00Z",
                    "…": "…"
                  },
                  {
                    "text": "entry-1-desc"
                  },
                  {
                    "text": "entry-1-action"
                  },
                  {
                    "number": {
                      "num": "2",
                      "denom": "1"
                    },
                    "…": "…"
                  },
                  {
                    "price": {
                      "num": "3",
                      "denom": "1"
                    },
                    "currency": "CURRENCY::USD",
                    "…": "…"
                  },
                  "…"
                ],
                "…": "…"
              },
              "…",
              "…",
              "…",
              {
                "role": "grandTotal",
                "cells": [
                  {
                    "text": "Amount Due"
                  },
                  {
                    "monetary": {
                      "amount": {
                        "num": "6",
                        "denom": "1"
                      },
                      "commodity": "CURRENCY::USD"
                    },
                    "…": "…"
                  }
                ]
              }
            ],
            "…": "…"
          },
          "…"
        ],
        "…": "…"
      }
    ],
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash report.run '{"report":"Printable Invoice","options":{"General":{"Invoice Number":"30000000000000000000000000000000"}}}'

It prints:

{
  "report": {
    "guid": "5123a759ceb9483abf2182d01c140e8d",
    "name": "Printable Invoice",
    "configuration": null
  },
  "title": "",
  "sections": [
    {
      "blocks": [
        {
          "kind": "text",
          "text": "Invoice #0001",
          "role": "heading",
          "class": "invoice-title"
        },
        "…",
        "…",
        "…",
        {
          "kind": "table",
          "class": "entries-table",
          "rows": [
            {
              "cells": [
                {
                  "date": "2024-03-15T12:00:00Z",
                  "…": "…"
                },
                {
                  "text": "entry-1-desc"
                },
                {
                  "text": "entry-1-action"
                },
                {
                  "number": {
                    "num": "2",
                    "denom": "1"
                  },
                  "…": "…"
                },
                {
                  "price": {
                    "num": "3",
                    "denom": "1"
                  },
                  "currency": "CURRENCY::USD",
                  "…": "…"
                },
                "…"
              ],
              "…": "…"
            },
            "…",
            "…",
            "…",
            {
              "role": "grandTotal",
              "cells": [
                {
                  "text": "Amount Due"
                },
                {
                  "monetary": {
                    "amount": {
                      "num": "6",
                      "denom": "1"
                    },
                    "commodity": "CURRENCY::USD"
                  },
                  "…": "…"
                }
              ]
            }
          ],
          "…": "…"
        },
        "…"
      ],
      "…": "…"
    }
  ],
  "…": "…"
}

MCP tool call

Tool call:

{"name":"report.run","arguments":{"report":"Printable Invoice","options":{"General":{"Invoice Number":"30000000000000000000000000000000"}}}}

Result:

{
  "structuredContent": {
    "report": {
      "guid": "5123a759ceb9483abf2182d01c140e8d",
      "name": "Printable Invoice",
      "configuration": null
    },
    "title": "",
    "sections": [
      {
        "blocks": [
          {
            "kind": "text",
            "text": "Invoice #0001",
            "role": "heading",
            "class": "invoice-title"
          },
          "…",
          "…",
          "…",
          {
            "kind": "table",
            "class": "entries-table",
            "rows": [
              {
                "cells": [
                  {
                    "date": "2024-03-15T12:00:00Z",
                    "…": "…"
                  },
                  {
                    "text": "entry-1-desc"
                  },
                  {
                    "text": "entry-1-action"
                  },
                  {
                    "number": {
                      "num": "2",
                      "denom": "1"
                    },
                    "…": "…"
                  },
                  {
                    "price": {
                      "num": "3",
                      "denom": "1"
                    },
                    "currency": "CURRENCY::USD",
                    "…": "…"
                  },
                  "…"
                ],
                "…": "…"
              },
              "…",
              "…",
              "…",
              {
                "role": "grandTotal",
                "cells": [
                  {
                    "text": "Amount Due"
                  },
                  {
                    "monetary": {
                      "amount": {
                        "num": "6",
                        "denom": "1"
                      },
                      "commodity": "CURRENCY::USD"
                    },
                    "…": "…"
                  }
                ]
              }
            ],
            "…": "…"
          },
          "…"
        ],
        "…": "…"
      }
    ],
    "…": "…"
  }
}

No document chosen gives GnuCash's warning:

Example: with a copy of the reports/transaction example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"report.run","params":{"report":"Printable Invoice"}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "title": "",
    "sections": [
      {
        "blocks": [
          {
            "kind": "warning",
            "title": "Invoice:",
            "text": "No valid invoice selected. Click on the Options button and select the invoice to use."
          }
        ],
        "…": "…"
      }
    ],
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash report.run '{"report":"Printable Invoice"}'

It prints:

{
  "title": "",
  "sections": [
    {
      "blocks": [
        {
          "kind": "warning",
          "title": "Invoice:",
          "text": "No valid invoice selected. Click on the Options button and select the invoice to use."
        }
      ],
      "…": "…"
    }
  ],
  "…": "…"
}

MCP tool call

Tool call:

{"name":"report.run","arguments":{"report":"Printable Invoice"}}

Result:

{
  "structuredContent": {
    "title": "",
    "sections": [
      {
        "blocks": [
          {
            "kind": "warning",
            "title": "Invoice:",
            "text": "No valid invoice selected. Click on the Options button and select the invoice to use."
          }
        ],
        "…": "…"
      }
    ],
    "…": "…"
  }
}

Template GUID: 5123a759ceb9483abf2182d01c140e8d · Script: standard/invoice.rhai

Options

Display

  • Due Date (boolean, default true): Display due date?
  • Subtotal (boolean, default true): Display the subtotals?
  • Use Detailed Tax Summary (boolean, default false): Display all tax categories separately (one per line) instead of one single tax line?
  • References (boolean, default true): Display the invoice references?
  • Billing Terms (boolean, default true): Display the invoice billing terms?
  • Billing ID (boolean, default true): Display the billing id?
  • Invoice owner ID (boolean, default false): Display the customer/vendor id?
  • Invoice Notes (boolean, default false): Display the invoice notes?
  • Payments (boolean, default true): Display the payments applied to this invoice?
  • Job Details (boolean, default false): Display the job name for this invoice?
  • Extra Notes (text, default "Thank you for your patronage!"): Extra notes to put on the invoice.
  • Payable to (boolean, default false): Display the Payable to: information.
  • Payable to string (text, default "Please make all checks payable to"): The phrase for specifying to whom payments should be made.
  • Company contact (boolean, default false): Display the Company contact information.
  • Company contact string (text, default "Please direct all enquiries to"): The phrase used to introduce the company contact.
  • Minimum # of entries (numberRange, default 1): The minimum number of invoice entries to display.

Display Columns

  • Date (boolean, default true): Display the date?
  • Description (boolean, default true): Display the description?
  • Action (boolean, default true): Display the action?
  • Quantity (boolean, default true): Display the quantity of items?
  • Price (boolean, default true): Display the price per item?
  • Discount (boolean, default true): Display the entry's discount?
  • Taxable (boolean, default true): Display the entry's taxable status?
  • Tax Amount (boolean, default false): Display each entry's total total tax?
  • Total (boolean, default true): Display the entry's value?

General

  • Report name (string, default "Printable Invoice"): Enter a descriptive name for this report.
  • Stylesheet (multichoice, default "Default"): Select a stylesheet for the report.
  • Add options summary (multichoice, default "never"): Add summary of options.
  • Invoice Number (invoice, default null)
  • Custom Title (string, default ""): A custom string to replace Invoice, Bill or Expense Voucher.

Layout

  • Row 1 Left (multichoice, default "none"): 1st row, left
  • Row 1 Right (multichoice, default "invoice"): 1st row, right
  • Row 2 Left (multichoice, default "client"): 2nd row, left
  • Row 2 Right (multichoice, default "company"): 2nd row, right
  • Row 3 Left (multichoice, default "none"): 3rd row, left
  • Row 3 Right (multichoice, default "today"): 3rd row, right
  • Picture Location (image, default ""): Location for Picture
  • CSS (text, default "/* advanced users only */\n.div-align-right { float: right; }\n.div-align-right .maybe-align-right { text-align: right }\n.entries-table * { border-width: 1px; border-style:solid; border-collapse: collapse}\n.entries-table > table { width: 100% }\n.company-table > table * { padding: 0px; }\n.client-table > table * { padding: 0px; }\n.invoice-details-table > table * { padding: 0px; text-indent: 0.2em; }\n@media print { .main-table > table { width: 100%; }}\n"): CSS code. This field specifies the CSS code for styling the invoice. Please see the exported report for the CSS class names.