Loading…
Loading…
about 20 minutes of your work, and Moneybird tokens are ready the moment you create themNo experience assumed: the guide starts at "install Python".
Using an AI assistant? Let it do the busywork.
Claude Code, Cursor, Copilot: paste this prompt and your own AI handles the installing, checking and scheduling, on your machine. You keep the key steps.
The prompt forbids your assistant from asking for keys in chat, and from ever touching the push side: you create credentials yourself, and changes always need your typed YES.
Unzip the toolkit into a folder you can find back easily, for example in your Documents. Inside you will see two halves that are deliberately kept apart.
You give each half its own API token later in this guide. The pull folder gets a read-only token, so that half could not change anything even if it tried.
The scripts run on Python, a free program. Get it from python.org and install it. Version 3.9 or newer is needed, and the latest version is fine.
Check it worked (in a terminal)
python --versionOn Windows, do not skip the box Add python.exe to PATH. If you skip it, the computer later answers that python is not recognized. The fix is to reinstall from python.org and tick the box.
Every command in this guide is typed in a terminal window that is standing in the right folder. Opening one takes a few seconds once you know the trick.
The scripts need one helper package. Open a terminal in the pull folder (the trick from the previous step) and run the command below. Then do exactly the same in the push folder.
In the pull folder, then again in the push folder
pip install -r requirements.txtYou create two personal API tokens in Moneybird: a read-only one for the pull and a read-and-write one for the push. This is the click-path from the toolkit's guide.
Each token is shown only once. Copy it immediately and store it in your password manager. Lost or leaked a token? Create a new one in the same menu, delete the old one there, and fill in the new one in the next step. Nothing else needs changing.
Leaving the Settings feature unticked is fine: a few extra data sets then politely report skipped during a pull. That is normal, not an error.
Each folder gets its own small settings file holding its token.
The copy must be named exactly .env. If a script later says the token is missing or still the example value, the file was not filled in, not saved, or not named exactly .env.
More than one administration on your Moneybird account? Also fill in MONEYBIRD_ADMINISTRATION_ID in .env. The number sits in the web address after moneybird.com/ when you are logged in. With a single administration you can leave it alone.
Open a terminal in the pull folder and run the check below. A good result starts with OK, credentials valid, then shows your administration (name, currency, country) and a list of feature scopes with GRANTED behind the ones your token carries. Then run the same check in the push folder.
In the pull folder, then in the push folder
python verify_auth.pySeeing token refused (HTTP 401)? The token was pasted wrong or was deleted in Moneybird. Create a fresh token and update .env, then run the check again.
In the push folder the same check also prints a reminder that this is the push token, so you always know the read-and-write token landed in the right folder.
Open a terminal in the pull folder. Start with the smoke run, a short test with a small bite of data. When that looks good, run the full pull. The full run pulls everything and can take a while, because the script pauses politely between calls to stay inside Moneybird's rate limits.
Short test run first
python pull_moneybird.py --smokeThen the full pull
python pull_moneybird.pyA few SKIP lines (data sets your token cannot see) and EMPTY lines (data sets with 0 rows) are normal, not errors. A pause mid-run is Moneybird's rate limit: the script waits exactly as long as asked and continues by itself.
Moneybird ids are 18-digit numbers. If Excel shows them as something like 1,23457E+17, format that column as text (or use the import wizard) before analysing.
The push commits one reviewed change at a time. In the push folder, copy changes-example.json to a new file changes.json and edit it: the action, the record id, and the new values. The push README lists all 44 actions. Then look before anything happens.
First look, nothing happens at all
python push_moneybird.py --plan changes.json --dry-runMake the real plan (still nothing changes)
python push_moneybird.py --plan changes.jsonThe two send actions (send a sales invoice, send a quote) cannot be undone. The customer receives it the moment it applies. The plan warns you about this in advance.
The pull can only read, so it is safe to run on a schedule. Set it up once and fresh CSVs appear every day.
Only ever automate the pull script. Never automate the push: changing your bookkeeping always deserves human eyes, and the push script refuses to run unattended by design.
Where your CSVs land. Every pull writes dated CSV files into the output folder that appears by itself inside the pull folder, right next to the pull script. Files are never overwritten, every run gets its own timestamp. Those are the files you open in Excel. Plans and receipts from the push land in a work folder next to the push script, your paper trail and your revert source.
Stuck on any step? Mail us at support@toqool.com and a founder answers.