Loading…
Loading…
about 30 minutes of your work, covering both toolkitsNo 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 download somewhere easy to find, for example your Documents folder. Inside are two toolkit folders, each with its own START-HERE.md you can always fall back on.
Pull and push are deliberately separate. Pull can only read, so it is safe to run automatically. Push always shows a plan first, and changes nothing until you type YES at the keyboard.
Python is the free program that runs the scripts. Get it from python.org and install it. Version 3.9 or newer; the latest is fine. You only do this once, both toolkits use the same Python.
Check it worked
python --versionWindows: during install, tick the box "Add python.exe to PATH". If you skip it, the python command is not recognized later. The fix is to reinstall from python.org with that box ticked.
Mac users who use Homebrew can also run brew install python. From here on, every command is shown once: Windows users type python, Mac users type python3.
All commands in this guide are typed in a terminal window that is standing in the right folder. Here is the trick, once for each system.
The scripts need one small helper package. Open a terminal in the bol/pull folder and run the command below. Then do the same in the bol/push folder, and once more in the bol-ads folder.
In each of the three folders
pip install -r requirements.txtSeeing ModuleNotFoundError: requests later on? That means this step was skipped for that folder. Run the install command there and try again.
First the Retailer toolkit. It needs an API key from the Bol partner portal.
Do not create the key under the Advertising section. That is a different key (for ads) and it will not work here. This is the number one setup mistake.
If your portal opens in Dutch, use its language switch, it is the same settings menu. Key lost or leaked? Just create a new key in the portal and fill it in again, nothing else needs changing.
Now give the scripts your codes, in a small file called .env.
Never share the .env file. It holds your real API key.
Time for the first real command. It only checks your key and pulls no data.
In the pull folder
python verify_auth.pyThen in the push folder
python verify_auth.pySeeing retailer scope: MISSING? Then you accidentally created an advertising key. Go back one step and create a key for the Retailer API instead, then update .env.
Seeing a message that a value is missing or still the example value? Then .env was not filled in, not saved, or not named exactly .env.
Open a terminal in the pull folder and run these one at a time. Start with the short test run, then do the full pull.
Short test run first
python pull_bol_retailer.py --smokeThen the full pull
python pull_bol_retailer.pyLines with HTTP 429 (rate limited) are normal on long runs. Bol asks the script to slow down; the script waits and retries by itself. No action needed.
Now the Advertising toolkit in the bol-ads folder. Careful: the Advertising key is a different key from the Retailer key you just made. The Bol portal has two separate key sections, and this time you need the Advertising one.
A key from the wrong section gets an error (403) on everything. This is the number one setup mistake for this toolkit: the Retailer key will not work here, and the Advertising key will not work in the Retailer toolkit.
If your portal shows Dutch, it is the same menu in the same place, or use the portal's language switch.
Same idea as before, now in the bol-ads folder.
Test it, in the bol-ads folder
python verify_auth.pySeeing OAuth returned HTTP 401? The Client ID or Secret is wrong. Check for missing characters, or create a fresh key in the portal and fill it in again.
Every time you want fresh numbers: open a terminal in the bol-ads folder and run these one at a time.
Check the key, then pull
python verify_auth.pyThe pull itself
python pull_bol_ads.pyBoth pull scripts are read-only, so they are safe to automate. On Windows you use Task Scheduler; on a Mac you use cron. Set up one task per pull script.
Only ever automate the PULL scripts. Never automate the push: changing prices or stock always deserves human eyes, and the push script refuses to run unattended by design.
Where your CSVs land. Every run writes dated CSV files into an output folder that appears by itself next to each pull script: inside bol/pull for your seller data, and inside bol-ads for your advertising data. Your Bol invoices also land there as PDFs, in output/invoices. Files are never overwritten, every run gets its own timestamp. Those are the files you open in Excel or drop into Toqool Local.
Stuck on any step? Mail us at support@toqool.com and a founder answers.