CSV Expense Import
CSV import is only for a user's master list of expenses. It is not a bank transaction import tool.
Use this page for
- Building or migrating your master expense list.
- Setting up split rows, payoff balances, accounts, and payment links.
- Understanding the review and correction step before import.
Do not use it for
- It does not import bank transactions.
- It does not create paid logs.
- It does not mark existing rows as already paid.
Before you upload
The importer is most reliable when the CSV is shaped like the template instead of a bank export or a custom sheet with guessed headers.
Each row represents one expense setup record. That means the row should describe how you want the expense to behave in KindaBroke, not a payment that already happened in the past.
The required columns are Name, Amount, and Category. The importer recognizes many common header aliases too, but the built-in template is still the safest path because it matches the live parser exactly.
How the import flow works
The upload does not save immediately. It always stops in a review step first.
1. Download the template
The safest starting point is the template that the modal downloads for you. It already uses the exact field names the importer expects.
2. Fill the rows that describe your expense list
Each row should describe an expense setup record, not a payment that already happened. Think of it as building the recurring expense list you want in the app.
3. Upload the file and review normalized values
Nothing is saved right away. The review table shows what the importer understood, what it normalized, and which rows still need attention.
4. Fix red cells before import
Rows with errors stay blocked until you correct them in the review step. You can edit the normalized values directly inside the modal.
5. Import only the valid rows
When the rows pass review, the importer creates expense records, tries to save any missing custom categories for reuse, then refreshes the budget data.
Field guide
These are the live fields the importer knows about right now.
| Field | Required | When to use it | Example |
|---|---|---|---|
| Name | Yes | Use for the expense name on every row. | Rent |
| Amount | Yes | Use for the total amount tied to that expense setup. | $180.50 |
| Category | Yes | Use for the default or custom category the expense belongs to. | Car Insurance |
| Due day | Yes | Use for the due day. Envelopes can fall back to 1st if you leave it blank, but normal rows should still be filled intentionally. | 1st, 15, last day, or 2026-07-03 |
| Budget behavior | Optional | Use when the row should be treated as a split, envelope, or envelope split. Blank defaults to normal_bill. | normal_bill, split_bill, envelope, envelope_split |
| Split cadence | Optional | Use only for split rows. Blank defaults to pay_period when split behavior is active. | pay_period, weekly, biweekly |
| Split weekday | Optional | Use only when the split cadence is weekly or biweekly and needs a weekday anchor. | Friday |
| Split amount mode | Optional | Use for split rows when you want the app to calculate the split or use a manual per-payment amount. | calculated or manual |
| Per-payment amount | Optional | Use only when split_amount_mode is manual. | $80 |
| First payment date | Optional | Use when a weekly or biweekly split needs a start date for its schedule. | 2026-07-03 |
| Loan payoff | Optional | Use when the expense should track a loan-style payoff balance. | yes, true, or 1 |
| Loan balance | Optional | Use when you want to start the row with a remaining loan balance. | $4,200 |
| Card payoff | Optional | Use when the row should track a credit-card payoff balance. | yes, true, or 1 |
| Card balance | Optional | Use when you want to start the row with a remaining card balance. | $925 |
| Default account | Optional | Use when you want the expense to remember which account it is usually paid from. | Main Checking |
| Payment link | Optional | Use when the expense should keep a payment or account link. The link must resolve to a valid http or https URL. | https://insurance.example.com |
What the review step normalizes
The review table is not only a preview. It is the place where the importer cleans up recognizable values and flags anything it still cannot trust.
- Required columns are Name, Amount, and Category. If those headers are missing, the file is blocked immediately.
- Header aliases are recognized for many common names, but the template is still the safest way to avoid surprises.
- Blank budget behavior defaults to normal_bill.
- Blank split cadence defaults to pay_period for split rows.
- Blank split amount mode defaults to calculated for split rows.
- Weekly and biweekly split rows must include a weekday.
- Manual split rows must include a per-payment amount greater than $0.
- Dates are normalized into YYYY-MM-DD when the importer can recognize them.
- Due values like last, last day, end, and end of month are normalized to 31st.
- If a loan or card balance is present, the related payoff tracking can switch on automatically.
- If a category is not one of the default categories, the importer treats it like a custom category name and tries to save it for reuse after import.
- Payment links can be typed without a protocol. The importer adds https:// if needed, but the final result still has to be a valid web address.
Common row examples
These examples show the kinds of rows the importer is designed around.
Simple monthly bill
A rent row can use Name, Amount, Category, Due, and Budget behavior. That is enough for a normal monthly expense.
- Name: Rent
- Amount: 1500
- Category: Rent
- Due: 1st
Split bill funded every paycheck
A bill like car insurance can use split_bill plus pay_period so the app spreads the funding across normal paydays.
- Name: Car insurance
- Budget behavior: split_bill
- Split cadence: pay_period
- Split amount mode: calculated
Weekly manual split
A BNPL or weekly payment plan can use weekly cadence, a weekday, manual split amount, and a first payment date.
- Budget behavior: split_bill
- Split cadence: weekly
- Split weekday: Friday
- Split amount mode: manual
- Per-payment amount: $80
- First payment date: 2026-07-03
Limits and boundaries
A few rules matter because they affect what the importer is allowed to create.
- CSV import builds expense setup records only.
- It does not import bank transactions.
- It does not create paid logs.
- It does not mark existing rows as already paid.
- Free accounts can only manage up to 10 expenses total, so the importer stops if the valid rows would push the account past that limit.
Common mistakes
These are the patterns most likely to turn cells red or make the import feel confusing.
- Uploading a transaction export instead of the expense template.
- Using split fields on a row that is not actually a split bill or envelope split.
- Leaving the split weekday blank for weekly or biweekly schedules.
- Using manual split mode without a per-payment amount.
- Typing a payment link that is not a valid website address.
- Assuming the upload saves immediately without the review step.