TUTORIAL.md

Invoice Builder Tutorial

💡 Note: The interface is fully responsive and works well on resizable windows, making it suitable for users on Linux tiling window managers, small screens, or any desktop setup.

Database creation screen

The first screen of the application lets you choose how you want to work with your database. You can either create/open a local database file or connect to a database server.

Local database

Recently opened databases are displayed in a quick access list for faster reopening.

When the application runs in Docker or the web version, databases are created inside a predefined folder. All databases in that folder are automatically listed in Quick Access. To remove a database from the Quick Access list, simply delete it from that folder. During creation, you will be prompted to enter the database name.

Server database

Recently used server connections also appear in a Quick Access list for faster reconnecting. For security reasons, passwords are never saved, so you will always need to re-enter the password when reconnecting. On the connection screen, you can:

• Enter server connection details
• Test the connection
• Save the connection (without password) for quick access

Settings screen

The Settings screen allows you to configure application behavior, manage data, and customize document output.

General & Data Management

From this screen you can:

• Enable or disable optional layouts (Presets, Style profiles, Quotes and Reports)
• Enable or disable optional features (UBL 2.1, XRechnung)
• Export all application data to JSON
• Import previously exported data
• Access project resources:
  • GitHub repository
  • Issue tracker
  • Tutorial
  • Project homepage
  • Privacy Policy
  • Terms of Use
• Check for application updates via GitHub Releases (Available only for native software version)

Localization & Formatting

You can customize:

• Application language
• Number (amount) formatting
• Date formatting

Invoice & File Naming

The following options are available:

• Customize invoice and quote numbers using:
  • Prefix
  • Suffix
• Customize exported PDF file names

By default, files are named: "{Invoice|Quote}_{InvoiceNumber}.pdf"

You can optionally include:

• Year
• Month
• Business name

Businesses screen

The Businesses screen allows you to create, read, update, and delete (CRUD) business data.

You can also:

• Filter businesses by various criteria
• Import and export businesses via XLSX

  💡 Note: XLSX import/export does not include business logo data.

Adding a Business

Click the Add button at the bottom to open a modal where you can:

• Enter business information
• Upload a logo (crop and adjust as needed)

  ⚠️ Maximum file size: 2 MB

Editing/Deleting a Business

Once businesses are added, select one from the list to edit it on the right side. Each business item also shows:

• Number of invoices created
• Number of quotes created (hidden if the layout is disabled in settings)

You can also:

• Search businesses by name
• Delete a business by clicking the red trash icon

Filters

Businesses have filters to control what is displayed. By default:

• Active: shows all businesses except archived

The archived flag can be toggled during creation or editing. This flag only affects filtering and does not delete the business.

Sorting

Businesses can be sorted by:

• Name
• Last updated date

Import & Export

You can:

• Export businesses to XLSX
• Import businesses from XLSX
• Download a XLSX template for business import

Banks screen

The Banks screen allows you to create, read, update, and delete (CRUD) bank data.

You can also:

• Filter banks by various criteria
• Import and export banks via XLSX

  💡 Note: XLSX import/export does not include bank qr code data.

Adding a Bank

Click the Add button at the bottom to open a modal where you can:

• Enter bank information
• Upload a QR code (crop and adjust as needed)

  ⚠️ Maximum file size: 2 MB

Editing/Deleting a Bank

Once banks are added, select one from the list to edit it on the right side. Each bank item also shows:

• Number of invoices created
• Number of quotes created (hidden if the layout is disabled in settings)

You can also:

• Search banks by name
• Delete a bank by clicking the red trash icon

Filters

Banks have filters to control what is displayed. By default:

• Active: shows all banks except archived

The archived flag can be toggled during creation or editing. This flag only affects filtering and does not delete the bank.

Sorting

Banks can be sorted by:

• Name
• Last updated date

Import & Export

You can:

• Export banks to XLSX
• Import banks from XLSX
• Download a XLSX template for bank import

Presets screen

The Presets screen allows you to create, read, update, and delete (CRUD) preset data.

You can also:

• Filter presets by various criteria
• Import and export presets via XLSX

Adding a Preset

Click the Add button at the bottom to open a modal where you can:

• Enter preset information

Editing/Deleting a Preset

Once presets are added, select one from the list to edit it on the right side.

You can also:

• Search presets by name
• Delete a preset by clicking the red trash icon

Filters

Presets have filters to control what is displayed. By default:

• Active: shows all presets except archived

The archived flag can be toggled during creation or editing. This flag only affects filtering and does not delete the preset.

Sorting

Presets can be sorted by:

• Name
• Last updated date

Import & Export

You can:

• Export presets to XLSX
• Import presets from XLSX
• Download a XLSX template for preset import

Clients screen

The Clients screen allows you to create, read, update, and delete (CRUD) client data. You can also filter, import, and export clients via XLSX.

Adding a Client

Click the Add button at the bottom to open a modal where you can:

• Enter client information

Editing/Deleting a Client

Once clients are added, select one from the list to edit it on the right side. Each client item also shows:

• Number of invoices created
• Number of quotes created (hidden if the layout is disabled in settings)

You can also:

• Search clients by name
• Delete a client by clicking the red trash icon

Filters

Clients have filters to control what is displayed. By default:

• Active: shows all clients except archived

The archived flag can be toggled during creation or editing. This flag only affects filtering and does not delete the client.

Sorting

Clients can be sorted by:

• Name
• Last updated date

Import & Export

You can:

• Export clients to XLSX
• Import clients from XLSX
• Download a XLSX template for client import

Categories screen

The Categories screen allows you to create, read, update, and delete (CRUD) category data. You can also filter, import, and export categories via XLSX.

Adding a Category

Click the Add button at the bottom to open a modal where you can:

• Enter category information

  💡 Note: Category names must be unique. You cannot create two categories with the same name.

Editing/Deleting a Category

Once categories are added, select one from the list to edit it on the right side. Each category item also shows:

• Number of invoices created
• Number of quotes created (hidden if the layout is disabled in settings)

You can also:

• Search categories by name
• Delete a category by clicking the red trash icon

Filters

Categories have filters to control what is displayed. By default:

• Active: shows all categories except archived

The archived flag can be toggled during creation or editing. This flag only affects filtering and does not delete the category.

Sorting

Categories can be sorted by:

• Name
• Last updated date

Import & Export

You can:

• Export categories to XLSX
• Import categories from XLSX
• Download a XLSX template for category import

Units screen

The Units screen allows you to create, read, update, and delete (CRUD) unit data. You can also filter, import, and export units via XLSX.

Adding a Unit

Click the Add button at the bottom to open a modal where you can:

• Enter unit information

  💡 Note: Unit names must be unique. You cannot create two units with the same name.

Editing/Deleting a Unit

Once units are added, select one from the list to edit it on the right side. Each unit item also shows:

• Number of invoices created
• Number of quotes created (hidden if the layout is disabled in settings)

You can also:

• Search units by name
• Delete a unit by clicking the red trash icon

Filters

Units have filters to control what is displayed. By default:

• Active: shows all units except archived

The archived flag can be toggled during creation or editing. This flag only affects filtering and does not delete the unit.

Sorting

Units can be sorted by:

• Name
• Last updated date

Import & Export

You can:

• Export units to XLSX
• Import units from XLSX
• Download a XLSX template for unit import

Currencies screen

The Currencies screen allows you to create, read, update, and delete (CRUD) currency data. You can also filter, import, and export currencies via XLSX.

Adding a Currency

Click the Add button at the bottom to open a modal where you can:

• Enter currency information

  💡 Note: Currency symbols must be unique. You cannot create two currencies with the same symbol.
  💡 Subunit: Defines how many subunits make up one unit of the currency.
  For example:

  • USD and EUR: 100 subunits = 1 USD/EUR
  • Japanese Yen (JPY): 1 subunit = 1 JPY

Editing/Deleting a Currency

Once currencies are added, select one from the list to edit it on the right side. Each currency item also shows:

• Number of invoices created
• Number of quotes created (hidden if the layout is disabled in settings)

You can also:

• Search currencies by text
• Delete a currency by clicking the red trash icon

Filters

Currencies have filters to control what is displayed. By default:

• Active: shows all currencies except archived

The archived flag can be toggled during creation or editing. This flag only affects filtering and does not delete the currency.

Sorting

Currencies can be sorted by:

• Text
• Last updated date

Import & Export

You can:

• Export currencies to XLSX
• Import currencies from XLSX
• Download a XLSX template for currency import

Items screen

The Items screen allows you to create, read, update, and delete (CRUD) item data. You can also filter, import, and export items via XLSX.

Adding a Item

Click the Add button at the bottom to open a modal where you can:

• Enter item information

  💡 Note: The item amount is always recorded in the selected currency. The currency is attached once when the item is added to a quote or invoice. Changing the quote/invoice currency will not automatically convert existing item amounts.

Editing/Deleting a Item

Once items are added, select one from the list to edit it on the right side. Each item also shows:

• Number of invoices created
• Number of quotes created (hidden if the layout is disabled in settings)

You can also:

• Search items by name
• Delete a item by clicking the red trash icon

Filters

Items have filters to control what is displayed. By default:

• Active: shows all items except archived

The archived flag can be toggled during creation or editing. This flag only affects filtering and does not delete the item.

Sorting

Items can be sorted by:

• Name
• Last updated date

Import & Export

You can:

• Export items to XLSX
• Import items from XLSX
• Download a XLSX template for item import

💡 Note: When importing items from XLSX, if a unit or category name is provided and does not already exist in the system, it will be automatically created.

Style profiles screen

The Style profiles screen allows you to create, read, update, and delete (CRUD) style profiles data, which can be later used in Invoice | Quote. You can also filter, import, and export style profiles via XLSX.

Adding a Style profile

Click the Add button at the bottom to open a modal where you can:

• Enter style profile information

  💡 Name: must be unique. You cannot create two style profiles with the same name. 💡 Sort Order: under "Table" tab its possible to customize sort order of generic item table headers.

Editing/Deleting a Style profile

Once style profiles are added, select one from the list to edit it on the right side. Each style profile item also shows:

• Number of invoices created
• Number of quotes created (hidden if the layout is disabled in settings)

You can also:

• Search style profiles by name
• Delete a style profile by clicking the red trash icon

Filters

Style profiles have filters to control what is displayed. By default:

• Active: shows all style profiles except archived

The archived flag can be toggled during creation or editing. This flag only affects filtering and does not delete the style profile.

Sorting

Style profiles can be sorted by:

• Name
• Last updated date

Import & Export

You can:

• Export style profiles to XLSX
• Import style profiles from XLSX
• Download a XLSX template for currency import

Quotes screen

The Quotes screen allows you to create, read, update, and delete (CRUD) quote records.

💡 Note: Amounts and dates are formatted based on the configuration in the Settings screen and the currency format defined in the Currency screen.

You can also:

• Filter quotes by various criteria
• Export quotes to XLSX

  💡 Note: XLSX export does not include attachments or business logo snapshots.

• Preview quotes live in PDF format
• Customize PDF appearance and layout
• Export quotes as PDF documents
• Create Invoice from Quote (generate an invoice directly from a quote, quote becomes closed, but can be manually opened again)
• Duplicate Quote to quickly create a similar quote

Adding a Quote

Click the Add button at the bottom to open the right-hand pane, where you can enter quote details. If Presets screen are enabled then you will have to choose either create new or from preset.

• Required information:
  • Currency
  • Language (Quote language for PDF labels which is independant from global application settings)
  • Business
  • Client (“Bill To”)
  • Quote information
  • At least one item

Select a currency from the dropdown. The dropdown supports search, filter, and sort (see Currencies screen for details).

💡 Note: The selected currency is saved as a snapshot. The snapshot is updated only when editing the quote and changing the currency.

Select a business from the dropdown. The dropdown supports search, filter, and sort (see Businesses screen for details).

💡 Note: The selected business is saved as a snapshot. The snapshot is updated only when editing the quote and changing the business.

Select a client from the dropdown. The dropdown supports search, filter, and sort (see Clients screen for details).

💡 Note: The selected client is saved as a snapshot. The snapshot is updated only when editing the quote and changing the client.

Select a style profile from the dropdown. The dropdown supports search, filter, and sort (see Style profiles screen for details).

💡 Note: The selected style profile is saved as a snapshot. The snapshot is updated only when editing the quote and changing the style profile.

💡 This section can be hidden if the feature is turned off in the settings. Customization can still be adjusted in preview mode.

💡 Selecting a style profile only applies preset values. You can continue customizing everything afterward.

Select a language from the dropdown. The dropdown supports search.

💡 Note: The selected language applies only to the generated PDF and is independent of the application's global language setting.

Enter the quote details, including:

• Quote number prefix
• Quote number suffix
• Quote number
• Issued date
• Due date

💡 Note:

• The prefix and suffix are saved as a snapshot if they were configured on the Settings screen.
• You can also change or add them here, even if they were not configured in Settings.
• If configured, the prefix and suffix are always incorporated into the quote number automatically.

Select a item from the dropdown and set quantity and unit price. The dropdown supports search, filter, and sort (see Items screen for details).

💡 Note: The selected item is saved as a snapshot. The snapshot is updated only when editing the quote and changing the item.

💡 When adding or editing an item in a quotation, a modal will appear requiring you to set the quantity and unit price. You can also define custom field data for the item, including a header, value, and alignment. Each unique custom header is added as a column in the PDF’s item table, and the corresponding value is placed in that column for the item. Alignment is configured per unique header. A header can be selected from the existing list or typed in as a new one (pressing Enter is required to register a new header). Both fields header and value must either be fully selected / entered or empty; otherwise, the Save button will remain disabled.

💡 Note: The items order can be changed by drag and drop.

Once all required information has been filled in, the quote can be saved.

Information on other pages is also updated to reflect the current quote count.

Additionally, you can set a discount (fixed amount or percentage-based).

You can also configure taxes for the quote:

• Total-based taxes: inclusive, exclusive, or deducted
• Per-item taxes: inclusive or exclusive

Results:

Additionally, you can set a shipping fees (fixed amount).

Additionally, you can set a notes (customer notes, thank you note, terms & conditions note).

Additionally, you can set a signature which can be set via hand/cursor or uploaded as image.

⚠️ Maximum file size: 2 MB

Additionally, you can attach images, which will be embedded into the PDF.

⚠️ Maximum file size: 2 MB

Editing / Deleting a Quote

Once quotes are added, select one from the list to edit it on the right-hand pane. Each quote also displays:

• Quote data (Issued At)
• Quote status (Open, Closed)
• Client name
• Total amount
• Due date / Overdue information

You can also:

• Search quotes by quote number
• Delete a quote by clicking the vertical dots menu → Delete

Filters

Quotes have filters to control what is displayed. By default:

• Active: shows all items except archived

The archived flag can be toggled during creation or editing. This flag only affects filtering and does not delete the quote.

Quotes have only Open and Closed statuses, so the status filter includes only these options.
Client and business filters are based on snapshot data stored with the quote. The date filter applies to the Issued At date.

Sorting

Quotes can be sorted by:

• Status
• Issued at date
• Quote number
• Last updated date

Export

Quotes can be exported only to XLSX format.

• Export all quote-related data to XLSX

  💡 Note: Attachments and business logo snapshots are not included in the export.

PDF Preview

• Quotes can be previewed live and exported as PDF.
• PDF customization is based on predefined configuration options.
• The Paid watermark is applied only when the status is set to Paid.
• The watermark is applied across all pages of the document.
• Page numbers are shown only when the document has more than one page.
• Attachments are embedded into the PDF when present.
• Sections with zero values (Discount, Tax, Shipping fees) are hidden in the PDF.
• Save as Profile button will create style profile item with these customization presets for futher usage on other quotes.

Invoices screen

The Invoices screen allows you to create, read, update, and delete (CRUD) invoice records.

💡 Note: Amounts and dates are formatted based on the configuration in the Settings screen and the currency format defined in the Currency screen.

You can also:

• Filter invoices by various criteria
• Export invoices to XLSX

  💡 Note: XLSX export does not include attachments or business logo snapshots.

• Preview invoices live in PDF format
• Customize PDF appearance and layout
• Export invoices as PDF documents
• Duplicate Invoice to quickly create a similar invoice

Adding a Invoice

Click the Add button at the bottom to open the right-hand pane, where you can enter invoice details. If Presets screen are enabled then you will have to choose either create new or from preset.

• Required information:
  • Currency
  • Language (Quote language for PDF labels which is independant from global application settings)
  • Business
  • Client (“Bill To”)
  • Invoice information
  • At least one item

Select a currency from the dropdown. The dropdown supports search, filter, and sort (see Currencies screen for details).

💡 Note: The selected currency is saved as a snapshot. The snapshot is updated only when editing the invoice and changing the currency.

Select a business from the dropdown. The dropdown supports search, filter, and sort (see Businesses screen for details).

💡 Note: The selected business is saved as a snapshot. The snapshot is updated only when editing the invoice and changing the business.

Select a client from the dropdown. The dropdown supports search, filter, and sort (see Clients screen for details).

💡 Note: The selected client is saved as a snapshot. The snapshot is updated only when editing the invoice and changing the client.

Select a style profile from the dropdown. The dropdown supports search, filter, and sort (see Style profiles screen for details).

💡 Note: The selected style profile is saved as a snapshot. The snapshot is updated only when editing the quote and changing the style profile.

💡 This section can be hidden if the feature is turned off in the settings. Customization can still be adjusted in preview mode.

💡 Selecting a style profile only applies preset values. You can continue customizing everything afterward.

Select a language from the dropdown. The dropdown supports search.

💡 Note: The selected language applies only to the generated PDF and is independent of the application's global language setting.

Enter the invoice details, including:

• Invoice number prefix
• Invoice number suffix
• Invoice number
• Issued date
• Due date

💡 Note:

• The prefix and suffix are saved as a snapshot if they were configured on the Settings screen.
• You can also change or add them here, even if they were not configured in Settings.
• If configured, the prefix and suffix are always incorporated into the invoice number automatically.

Select a item from the dropdown and set quantity and unit price. The dropdown supports search, filter, and sort (see Items screen for details).

💡 Note: The selected item is saved as a snapshot. The snapshot is updated only when editing the invoice and changing the item.

💡 When adding or editing an item in a invoice, a modal will appear requiring you to set the quantity and unit price. You can also define custom field data for the item, including a header, value, and alignment. Each unique custom header is added as a column in the PDF’s item table, and the corresponding value is placed in that column for the item. Alignment is configured per unique header. A header can be selected from the existing list or typed in as a new one (pressing Enter is required to register a new header). Both fields header and value must either be fully selected / entered or empty; otherwise, the Save button will remain disabled.

💡 Note: The items order can be changed by drag and drop.

Once all required information has been filled in, the invoice can be saved.

Information on other pages is also updated to reflect the current invoice count.

Additionally, you can set a discount (fixed amount or percentage-based).

You can also configure taxes for the invoice:

• Total-based taxes: inclusive, exclusive, or deducted
• Per-item taxes: inclusive or exclusive

Results:

Additionally, you can set a shipping fees (fixed amount).

Additionally, partial payments are supported, allowing you to track paid amounts and outstanding balances per invoice.

Additionally, you can set a notes (customer notes, thank you note, terms & conditions note).

Additionally, you can set a signature which can be set via hand/cursor or uploaded as image.

⚠️ Maximum file size: 2 MB

Additionally, you can attach images, which will be embedded into the PDF.

⚠️ Maximum file size: 2 MB

Editing / Deleting a Invoice

Once invoice are added, select one from the list to edit it on the right-hand pane. Each invoice also displays:

• Invoice data (Issued At)
• Invoice status (Unpaid, Paid, Partially, Closed)
• Client name
• Total amount
• Due date / Overdue information / Partial paid information

You can also:

• Search invoices by invoice number
• Delete a invoice by clicking the vertical dots menu → Delete

Filters

Invoices have filters to control what is displayed. By default:

• Active: shows all items except archived

The archived flag can be toggled during creation or editing. This flag only affects filtering and does not delete the invoice.

Invoices have Unpaid, Partially, Paid and Closed statuses, so the status filter includes only these options.
Client and business filters are based on snapshot data stored with the invoice. The date filter applies to the Issued At date.

Sorting

Invoices can be sorted by:

• Status
• Issued at date
• Invoice number
• Last updated date

Export

Invoices can be exported only to XLSX format.

• Export all invoice-related data to XLSX

  💡 Note: Attachments and business logo snapshots are not included in the export.

PDF Preview

• Invoices can be previewed live and exported as PDF.
• PDF customization is based on predefined configuration options.
• The Paid watermark is applied only when the status is set to Paid.
• The watermark is applied across all pages of the document.
• Page numbers are shown only when the document has more than one page.
• Attachments are embedded into the PDF when present.
• Sections with zero values (Discount, Tax, Shipping fees) are hidden in the PDF.
• Save as Profile button will create style profile item with these customization presets for futher usage on other quotes.

Reports screen

The Reports screen provides an overview of aggregated financial data grouped by currency for a selected period.

Filters

You can filter reports using:

• Predefined periods (e.g. this month, last year)
• Custom date ranges

e-invoices

The application supports:

• UBL Peppol XML: you can download the XML embedded with the PDF, or as a standalone XML file. This feature is enabled by default and can be toggled in the Settings page.
• XRechnung (UBL 2.1) XML: you can download the standalone XML file. This feature is enabled by default and can be toggled in the Settings page.

To generate valid UBL/Peppol XML or XRechnung (UBL 2.1) XML, additional fields are available on Businesses and Clients. These fields must be properly filled to produce compliant invoices.

ℹ️ UBL XML / XRechnung XML may fail validation if data is misconfigured. The application only checks that required fields are present. It does not guarantee that all values conform to UBL/Peppol or XRechnung (UBL 2.1) standards.

For example:

• Tax names must match supported values (e.g., VAT). Arbitrary text will cause validation errors.
• Currency codes must be standard ISO codes (e.g., EUR, USD). Random text will fail validation.

Export behavior:

• A regular PDF can be exported at any time.
• The XML file and the PDF with embedded XML reflect only saved data.
• You cannot export XML while creating a new invoice until it has been saved.
• When editing an invoice, make sure to save changes before exporting.

Use a UBL Peppol XML validator (e.g., https://peppolvalidator.com/) to ensure compliance before sending. Use a XRechnung (UBL 2.1) XML validator (e.g., https://validator.invoice-portal.de/) to ensure compliance before sending.