Skip to content
Open Net Worth Docs

YNAB data sync

The YNAB data sync brings your history in from YNAB and then keeps the two in step: accounts, categories, envelopes, every transaction and each month’s Assigned amounts, checked against YNAB’s own figures. After the import, transactions, categories and category groups (both ways) and the Assigned of an envelope that holds one category stay in step. Changes can flow Both ways, only From YNAB, or only To YNAB. It is a data sync: open Automations, switch to Data sync at the top and pick YNAB. A data sync follows fixed rules rather than a Lucius prompt, so no AI is involved and it costs nothing to run. Every run is saved, so you can come back to its report whenever you like, from any device.

Experimental, on by default. It has a switch in Settings → Developer → Experimental (Ynab import and sync). Turning it off stops the sync and hides the Data sync tab, but keeps its settings, review list and history, so turning it back on carries on where it left off. The YNAB connector itself works the same either way.

This is separate from importing a statement, which reads one bank or card file, and from the one-way Sync YNAB template, where Lucius fetches new YNAB transactions on a schedule.

Set it up

Until it is set up, its page is two steps, the second unlocked by the first:

  1. Connect YNAB. Click Connect YNAB…: the YNAB connector opens right over this page, the same panel as Connectors → YNAB. Paste your access token and Save. Once a token is saved, Change beside “Token saved” opens it again — use it if step 2 says YNAB refused the token. Where to find a token: Bank & brokerage connectors.

  2. Bring your plan in and keep it in sync. Choose your plan and click Review…. It reads the plan afresh and opens it in one window; nothing is written. Under the title, one line says what the plan holds (currency, accounts, transactions, categories, budget months), then a note for anything the import would change in this book: a base-currency change (only in a book with no money data yet), the starter categories you never used, which it removes (pick one for a YNAB category to keep it), accounts here that didn’t come from YNAB (they stay as they are and the plan is added beside them), and any warnings. A plan in another currency than a book that already holds data can’t be imported, and the note says so. Three tabs show the plan itself:

    • Accounts: each account with its type, where it goes in this book, how many transactions it has and its opening balance;
    • Categories: each group with its categories, and where each one goes in this book (below);
    • Transactions: newest first (date, account, payee, category, amount; a long history shows its newest 500, and the import brings them all).

    Already have some of these accounts here? In the Accounts tab, In this book says where each YNAB account goes: New account (the default), or Use one of your accounts that fits it — open, in the plan’s currency, and of a matching type (a budget account goes into an account of its own type: cash into cash, a card into a card; a tracking account into any off-budget asset account, a tracking loan into a loan). A closed YNAB account always gets a new one. Choosing an account checks which of its transactions YNAB also has, and the line under it says how many are already there (matched, so they are not booked twice), how many are added, and how many to check. A matched transaction keeps your payee, category and memo; YNAB only fills the ones you left blank. The account keeps its name, opening balance and history. Transactions to check are ones that may be the same but the app isn’t sure (the same amount on the same day, worded differently, say): each is listed beside your one and is added as a new transaction unless you tick Same as…. The line also says how many of the account’s own transactions YNAB doesn’t have; a sync to YNAB sends those there. An account a previous import linked shows as linked and stays so.

    Already have some of these categories here? A YNAB category has a label (what its transactions are tagged with) and a budget; here the label is a category and the budget belongs to an envelope that can hold several categories. So the Categories tab gives each YNAB category two columns:

    • Category here: one of your categories, or New category. One of yours is pre-selected when its name reads the same, ignoring emoji, symbols, capitals and extra spaces (YNAB’s ”🛒 Groceries” goes with your “Groceries”). When nothing reads the same, the closest name is pre-selected: your “Transport” for YNAB’s “Transportation”, “Grocery” for “Groceries”, “Rent” for “Rent/Mortgage” (one side of a slash). A name that reads the same always wins, and no category of yours is suggested for two rows. When several of yours read the same, the one spelled most like YNAB’s is picked (your “fun money” over “Fun money!” for YNAB’s “Fun Money”); only two spelled exactly alike are left for you to choose. Nothing of yours is renamed or moved.
    • Envelope: for one of your categories, the envelope it is already in, shown by name; its Assigned syncs with YNAB. In no envelope it reads Not budgeted, or the name of the envelope the import makes for it, such as Old Cats (new), when YNAB has money assigned to it. For a New category, pick its own new envelope (named after it) or one of your envelopes. An empty envelope of the same name is pre-selected; one that already holds categories is listed first but not pre-selected, because adding to it shares it.

    Each category and envelope wears its own colour, as it does on the Plan screen. A warning mark beside a choice means it’s worth a look; hover over it or tap it to read why: the match was picked by a close name, or from several that read the same, or the envelope holds other categories too, so its Assigned won’t sync (the labels still do).

    Both lists are searchable when they are long. A category hidden in YNAB comes in hidden, and under the group it came from. If two of yours are spelled exactly alike, nothing is guessed: it asks you to pick, and Import waits. A YNAB group goes with the group of yours that reads the same, else a new one. The two-way sync later pairs a category that is new in YNAB only on the same name, never a similar one.

    After import sets the sync (Keep in sync both ways, Sync from YNAB only, Sync to YNAB only, or Don’t sync, import once); then Import. The app takes a backup before it writes anything and names it in the report; if the backup fails, nothing is imported. View live report opens the run while it works. You can close the tab: the work continues on the server, and the sync turns on by itself when the import succeeds (every hour by default). If it can’t turn on, the report says why and step 2 offers Turn on. Running again is safe: nothing is booked twice.

Once it has been imported it appears under Automations → Data sync with its schedule and an N to review tag when something needs you (the Data sync switch shows the same count). Its menu has Sync now, Turn on / Turn off and Open.

Once it’s running

The page reads like any Automation: the switch turns it on or off (off keeps the plan it is paired with), the next sync is next to it, and Sync now runs one on demand. Only one run happens at a time.

  • Needs your review comes first when something does: where both sides changed the same thing (a transaction, a month’s Assigned, a category’s name, hidden state or group), with Keep Open Net Worth’s and Keep YNAB’s; a YNAB category that could go with several of yours, or with an envelope that already holds others, which asks you to pick; and an account with a synced transaction dated before its Starting Balance, which moves only if you confirm Move the Starting Balance (or choose Keep as history).
  • Direction and Schedule: each reads like an Automation’s trigger; click it to change it. How often: every 15 or 30 minutes, hourly, every 6 hours, daily, or manual only. Below them, the last sync and what it did (“3 sent to YNAB, 1 pulled, 1 needs review”), or why it failed. A sync that’s due shows Next sync: within a minute: the app checks every minute.
  • Red flag in YNAB. Every transaction the sync adds or changes in YNAB gets YNAB’s red flag, so you can spot what came from Open Net Worth there.
  • Direction. From YNAB brings YNAB’s changes in and never writes to YNAB; To YNAB sends this book’s changes and never changes the book from YNAB. Either way, a transaction or a month’s Assigned changed on both sides still goes to Needs your review, and keeping the side the direction protects leaves the other one untouched. What one way held back is not lost: switch back to Both ways and the next sync sends or pulls it.
  • Categories and groups. Each YNAB category stays paired with the category it was imported into, even when either is renamed. A new category on one side is created on the other (a new YNAB category goes with one of yours that reads the same, else is created here with an envelope of its own, in the group paired with its YNAB group; a new category here is created in YNAB, in the group paired with its envelope’s group). A rename, a move to another group (for a category alone in its envelope) and hiding reach the other side. Nothing is ever deleted by the sync: a category hidden or deleted in YNAB is hidden here. YNAB’s API can neither delete nor hide a category, so one hidden, deleted or merged here is moved into a YNAB group called “Hidden in Open Net Worth” (made once; hide it in YNAB yourself if you like, and showing it again here moves it back), with its transactions relabelled as usual. A category that sits in no envelope is created in a YNAB group called Not budgeted; if YNAB later assigns money to it, it gets an envelope here. Categories in those two groups are never followed into a group here. A group renamed on one side is renamed on the other. Income categories are not sent: their transactions go to YNAB as Ready to Assign inflows. When a YNAB category is matched with one of yours, whether at import or later, both are taken as they stand: it is never moved or renamed on the first sync, only when someone changes something afterwards.
  • Assigned only for one-category envelopes. A category’s Assigned syncs with its envelope only while the envelope holds just that category. If you put another category in, the run says so once (“Food holds several categories, so its Assigned isn’t synced with YNAB.”); take it out again and the Assigned syncs again, with any difference listed for your review. The same holds whenever a category moves to another envelope, or is matched with a YNAB category that already existed: the two sides’ figures are compared afresh, and the sync never sends or takes a month’s Assigned over the other side’s without your choice. If YNAB assigns money to a category you took out of its envelope, the review asks Give it one? rather than making an envelope for you.
  • YNAB plan: the plan it pairs with and when it was imported.
  • ⋯ → Re-check against YNAB compares the book with YNAB’s current figures and reports any difference, without writing; Sync now is the one that moves changes.

How the sync decides, what it sends and its limits are in Bank & brokerage connectors.

History

Every preview, import, re-check and sync is listed newest first with when it started and a one-line outcome; Needs attention shows only the ones that failed or were interrupted. Click one to open its report. Archive (on the report) hides a finished run from the list; nothing is deleted, and a run in progress can’t be archived.

If the server stopped while a run was in progress, the run is kept and marked Interrupted. Run it again to finish: everything already booked is recognised.

A sync you start with Sync now is always a run in the history, and so is a scheduled sync that has something to report: a change, a review item, a deferral or a new failure. A scheduled sync that finds nothing to do (most hourly runs) is not added; the Schedule section’s last-sync line shows it ran. The same failure repeated every hour is recorded once. Choosing Keep Open Net Worth’s on a review item that sends a change to YNAB is a run too.

Reading a report

  • Setup (imports): whether this was a first import or a re-import, and the backup taken first.
  • Results: per item (accounts, categories, envelopes, transactions, assigned months), how many were created, were already there, were refused or failed. A refused transaction is one the book treats as a duplicate or that you deleted earlier.
  • Needs attention: each problem with the reason and what you can do about it.
  • Verification: how many checks were made and how many match. The ones that differ come first, with YNAB’s figure, the book’s figure and the difference; Show all lists those that match. A transaction count that differs usually means a row wasn’t booked; an envelope or Ready to Assign difference means the two apps’ budget rules gave different numbers for your history.
  • Log: a timestamped account of what the run did, open while it runs and folded once it ends.

Sync runs

A sync run reports what it did, leaving out empty sections (a run that changed nothing says Nothing changed):

  • Counts: sent to YNAB, pulled in, Assigned changes, category changes, conflicts filed, deferred, errors, and how many YNAB requests the run used. Categories lists each category or group change in a sentence, and Worth knowing notes anything not synced and why.
  • Transactions: Sent and Pulled tabs with date, payee, account, amount and the change: Created, Deleted, or one line per field such as Amount -60.00 → -62.50.
  • Assigned: category, month, before and after, and the direction.
  • Conflicts filed: both versions; the ones still open carry the Keep buttons.
  • Deferred: what waits for the next run because of YNAB’s request limit. Errors: what YNAB or this book refused, with the reason.

Lists show 50 at a time. A run keeps at most 2,000 items of each kind; if there were more, the report says how many were not stored (the counts are always complete).

A run that failed shows why at the top, with everything it captured before it stopped.

Run history belongs to the book it describes: Reset clears it, and it is not part of an export. It never contains your YNAB token.