Headers on Google Sheets
The Bkper Add-on for Google Sheets uses the first row of your data range as a header to understand the meaning of each column. This applies when you save Transactions, Accounts, and Groups.
How the Add-on Recognizes Headers
The Add-on considers your first row a valid header when either of these conditions is met:
Frozen first row — When you freeze the first row in Google Sheets (View > Freeze > 1 row), the Add-on always treats it as a header, regardless of the column names.
Recognized column names — Even without freezing, the Add-on recognizes specific column names and uses them to map your data correctly. This gives you flexibility when working with data exported from other systems.
Recognized Column Names
The following column names are automatically recognized:
Column Name | Aliases | What it does |
Date | — | The post date of the Transaction |
Amount | — | The amount on the Transaction |
From | Origin, From Account, Credit Account | The From Account on the Transaction |
To | Destination, To Account, Debit Account | The To Account on the Transaction |
Description | — | The description, including external URLs |
ID | — | Unique identifier for generating IDs |
Transaction ID | — | Used to update existing Transactions (see below) |
BookId | — | Target Book ID when saving to multiple Books |
Attachment | — | File attachment URL |
When using recognized column names, you can place them in any order on your Sheet.
When No Header is Recognized
If the first row is not frozen and contains no recognized column names, the Add-on falls back to positional parsing. In this mode, the order of the data determines its meaning — for example, the first Account name found on a row becomes the From Account.
Saving vs. Updating Transactions
When your data includes a Transaction ID column, the Add-on can update existing Transactions instead of recording new ones:
Rows with a Transaction ID value will update the existing Transaction in your Book
Rows without a Transaction ID value will record a new Transaction
This enables batch editing of Transactions directly from Google Sheets. Simply fetch your Transactions, make your changes, and save them back.
Note: Some columns are read-only and cannot be modified when updating: Transaction ID, Status, and Recorded At (or Created At).
Custom Properties
Any column with a header name that is not a recognized system column becomes a custom property. The column header becomes the property key and the cell value becomes the property value.
For example, a column named project_code with a cell value of PRJ-2025 will record the custom property project_code: PRJ-2025 on the Transaction.
To use custom properties, you should freeze the first row to ensure consistent header recognition.
Note: Custom properties for Books cannot be recorded via Google Sheets.
Ignoring Columns
Columns with blank headers are ignored when saving data with the Bkper Add-on.
This is useful when your Sheet contains additional information used for other purposes — such as checkboxes for internal approval workflows — that should not be recorded in Bkper.
Summary
Scenario | Header Recognition | Custom Properties |
First row frozen | Always recognized | Supported |
Recognized column names (not frozen) | Recognized | Supported |
No freeze, no recognized names | Falls back to positional parsing | Not supported |
Recommendation: For maximum flexibility and to ensure custom properties work correctly, freeze your first row.
Also see: Record Transactions from Google Sheets