Properties

Custom properties let you attach structured metadata to Books, Accounts, Groups, and Transactions as key/value pairs. This is useful for storing data such as tax rates, contact information, invoice numbers, or external references like URLs and IDs from other systems.

For the conceptual overview, see Core Concepts — Custom Properties.

By centralizing this information within your Book, you can work in context without switching between apps. For example, storing contact data on an overdue receivable account makes it possible to reach out to a client directly from Bkper — manually or through an automated process with Google Apps Script.

Rules for custom properties

• Property keys must be lowercase.
• Spaces in keys are automatically converted to underscores (_).
• To remove a property, delete its value.
• All property changes (create, edit, delete) are logged in the book’s Events feed.

Book properties

Book-level properties store information that applies to the entire Book — a tax ID, company address, base currency code, or any configuration data your automations need. They are especially valuable in automated workflows where bots read Book properties to determine how they should behave.

To manage Book properties, open your Book’s Settings (⚙️), go to Configurations > Book Properties, and add or modify key/value pairs.

Common examples:

Key	Value	Purpose
tax_id	12.345.678/0001-90	Company tax identification
exc_code	BRL	Base currency for exchange bots
address	123 Main St, São Paulo	Company contact info

Account properties

Account properties are ideal for storing contact information, external identifiers, or metadata specific to individual accounts. Emails, URLs, and phone numbers are rendered as clickable links in the chart of accounts — clicking a phone number, for example, opens your configured calling app.

To manage account properties, open the account editor, expand the properties section, and add or modify key/value pairs.

Common examples:

Key	Value	Purpose
email	client@example.com	Clickable contact link
phone	+55 11 99999-0000	Opens calling app
exc_code	USD	Currency for exchange bots
external_id	CUST-4829	Reference to an external system

Group properties

Group properties work the same way as account properties but apply to an entire group. They are commonly used to configure bot behavior — for example, setting a tax rate on an expense group so a Tax Bot can calculate taxes automatically for every transaction in accounts under that group.

To manage group properties, hover over the group name in the sidebar, click More > Edit, then expand the properties section.

Common examples:

Key	Value	Purpose
tax_rate	0.21	Tax Bot calculates taxes at 21%
exc_amount	buy	Exchange Bot uses buy rate
inventory_type	fifo	Inventory Bot uses FIFO method

Transaction properties

Transaction properties attach metadata to individual transactions — useful for storing invoice numbers, reference codes, purchase order IDs, or any other per-transaction data that doesn’t belong in the description.

To add properties, open a transaction for editing and expand the properties section to enter key/value pairs.

Common examples:

Key	Value	Purpose
invoice	INV-2026-0042	Invoice reference
po_number	PO-1234	Purchase order tracking
receipt_url	https://...	Link to digital receipt

Properties in Google Sheets

When you use the Bkper Add-on for Google Sheets, properties integrate seamlessly through the column header system. Any column header that is not a recognized system column automatically becomes a property key — the header is the key and each cell value is the property value.

This works for all entity types that support properties:

• Save Transactions — non-system columns become transaction properties
• Save Accounts — non-system columns become account properties
• Save Groups — non-system columns become group properties

When you fetch data back to Sheets, properties appear as additional columns alongside the system columns, making them available for reporting and analysis.

Note

Book properties cannot be recorded via Google Sheets — manage them directly in the web app through Settings > Book Properties.

Properties in automations

Properties are the primary configuration mechanism for Bots in Bkper. Each bot defines its own set of expected property keys — consult the documentation for the specific bot you are using to learn which properties to set.

Common patterns:

• Book properties tell a bot how to behave globally — for example, the Exchange Bot reads exc_code from the Book to know the base currency.
• Account properties tell a bot what applies to specific accounts — for example, exc_code: USD on an account tells the Exchange Bot which currency that account tracks.
• Group properties configure behavior for entire groups — for example, the Tax Bot reads tax_rate from a group to calculate taxes on all transactions in that group’s accounts.
• Transaction properties carry per-entry metadata that bots can read or write — for example, storing the calculated tax amount after processing.

Properties in the audit trail

Every property change — create, edit, or delete — generates an Event in the Book’s Activities panel. This means you have a complete history of who changed which property, when, and what the previous value was.

This is important for compliance and debugging: if an automation misbehaves because a property value was changed, you can trace exactly when and by whom the change was made.