Set up your Amazon toolkit

1. 1

   Put the toolkit folders in place

   This guide covers both Amazon toolkits in one go: the amazon folder (the Seller toolkit, for listings, orders, finances, FBA stock and daily sales) and the amazon-ads folder (the Ads toolkit, for campaigns, keywords, search terms and day-by-day ad performance). If they arrived as a zip file, unzip it first: right-click the zip and choose Extract All on Windows, or double-click it on Mac. Put both folders somewhere you can find them back, for example in your Documents. Both toolkits are read-only: they pull your data but can never change anything on your Amazon account.

   • Each folder contains the pull script, a verify_auth.py test script, a requirements.txt and a .env.example template.
   • The amazon-ads folder has one extra helper, get_refresh_token.py, which you use once in a later step.
   • The pulled data lands in an output folder that appears by itself next to the scripts on the first run.

   Optional, for the Seller toolkit: create a plain text file named extra-asins.txt next to the pull script, one ASIN per line, and the script also pulls per-ASIN data for those products, even when they are missing from your live listings. Without that file everything still works.

2. 2

   Install Python

   Both toolkits run on Python, a free program from python.org. Version 3.9 or newer works; the latest is fine.

   • Download the installer from python.org and run it. During install, tick the box that says Add python.exe to PATH.
   • From here on, every command uses python and pip.

   Check it worked

   python --version

   Copy

   If the computer says python is not recognized, Python is not on your PATH. Reinstall from python.org and tick Add python.exe to PATH on Windows, or type python3 instead on Mac.

3. 3

   Open a terminal in the folder and install the helper package

   All commands in this guide are typed in a terminal window that is standing in the toolkit folder you are working on. Opening one is easier than it sounds.

   • Now install the one helper package the scripts need. Do this once in the amazon folder and once in the amazon-ads folder.
   • Open the folder in File Explorer, click once in the address bar (the bar at the top showing the folder name), type cmd and press Enter. A black window opens, already in this folder.

   Install the helper package

   pip install -r requirements.txt

   Copy

   Seeing ModuleNotFoundError: requests later on means this install was skipped in that folder. Run it again there and you are set.

4. 4

   Register as an Amazon developer (the waiting step)

   Amazon does not hand out simple API keys. Instead you create your own small private app inside Seller Central once, and that app's codes are your keys. Before you can create it, Seller Central asks you to register as a developer, and Amazon reviews that request. Start this today so the wait runs in the background.

   • Log in to Seller Central (sellercentral.amazon.de or your own country's version; it is one EU account).
   • Go to Apps and Services, then Develop apps.
   • First time here, Seller Central asks you to register as a developer. Answer the questionnaire honestly but minimally: the app is private (only for your own seller account), and it does not handle buyer personal data.
   • Amazon reviews this request, which can take time. You get an email when it is approved.

   You cannot create the app until this review is approved, so send the registration in early.

   The Ads toolkit has its own separate approval wait at advertising.amazon.com (a later step in this guide). Feel free to jump ahead and submit that application now too, so both waits run at the same time.

5. 5

   Create the app and collect your Seller keys

   Once your developer registration is approved, the app itself is a one-time click-through. It sounds bigger than it is.

   • In Seller Central, go to Apps and Services, then Develop apps, and click Add new app client. Give it a simple name like my-data-pull. API type: SP-API.
   • Tick these roles: Inventory and Order Tracking, Pricing, Product Listing, Amazon Fulfillment, Finance and Accounting, Selling Partner Insights, plus Brand Analytics if it is offered to you.
   • Do not tick Tax Invoicing or Direct-to-Consumer Shipping. Those unlock buyer personal data, and this toolkit never reads that.
   • Save. On the app row, click View under LWA credentials and copy the Client ID (it starts with amzn1.application-oa2-client.) and the Client Secret.
   • On the same app row, click Authorize. This one-time step produces your refresh token (it starts with Atzr|).
   • One more value: your seller id, also called the merchant token. Find it under Settings, Account Info, Your Merchant Token.

   The Client Secret and the refresh token are each shown only once. Store all four values in your password manager right away.

   Lost a value? No drama: re-open View for the Client ID and Secret, or run Authorize again for a fresh refresh token. Good to know: if you ever change the app's roles, Amazon issues a new refresh token and the old one stops working, so update your .env after any role change.

6. 6

   Add your Seller keys and test them

   The .env file is where the scripts read your keys from. It stays on your own computer.

   • In the amazon folder, make a copy of .env.example and name the copy exactly .env.
   • Paste your four values after AMAZON_SP_CLIENT_ID=, AMAZON_SP_CLIENT_SECRET=, AMAZON_SP_REFRESH_TOKEN= and AMAZON_SP_SELLER_ID=.
   • Save the file. Never share it with anyone; it holds your real keys.
   • Now test it with the command below. A good result starts with OK | credentials valid and lists the marketplaces you sell on.
   • Notepad is all you need to open and edit .env.

   Test it, in a terminal in the amazon folder

   python verify_auth.py

   Copy

   The file must be named exactly .env. If the test says a value is missing or still the example value, the file was not filled in, not saved, or not named exactly right. Seeing invalid_grant? Run the Authorize step again and paste the new refresh token. Seeing invalid_client? Re-copy the Client ID and Secret from Seller Central.

7. 7

   Your first Seller data pull

   Start with a smoke run, a short test with a small bite of data, then do the full pull.

   • The full pull can take up to 90 minutes. Amazon prepares the big reports on its own side while the script politely waits, so let it run.
   • At the end you see a line like: Done. 41 CSVs written, 3 fail/empty. The files are in the output folder; open them in Excel.
   • EMPTY lines in the run are usually good news, for example no stranded inventory. Lines with HTTP 429 (rate limited) are normal too; the script waits and retries by itself.

   Short test run first

   python pull_amazon_sp.py --smoke

   Copy

   Then the full pull

   python pull_amazon_sp.py

   Copy

   Ran it twice on the same day? The script says Fresh data already exists and stops. That is intentional; add --force to pull again anyway.

8. 8

   Apply for Amazon Ads API access

   The Ads toolkit needs three values of its own: a Client ID, a Client Secret and a refresh token. Getting them is a one-time job with a waiting step in the middle.

   • Go to developer.amazon.com, sign in with your Amazon account, open Login with Amazon and create a new security profile. Name it something clear, like My ads data.
   • Open the profile's Web Settings. This page holds your Client ID (it starts with amzn1.application-oa2-client.) and your Client Secret. The secret is shown once, so store both in your password manager immediately.
   • Go to advertising.amazon.com and apply for API access for that security profile (look for the Amazon Ads API or API access section in the Ads console). Amazon reviews this request, and you get an email when it is approved. The next steps only work after approval.
   • Back in the security profile's Web Settings, add this as an Allowed Return URL, exactly as written, including the port and the path: http://127.0.0.1:8765/callback

   The number-one wrong-key trap: the Ads Client ID and Secret come from developer.amazon.com (Login with Amazon), not from Seller Central. And the merchant or seller token from Seller Central is not used anywhere in the Ads toolkit.

   Lost or leaked the secret? Just reset it on that same Web Settings page and fill it in again. You will then also need a fresh refresh token from the next step.

9. 9

   Capture your Ads refresh token

   After your API access is approved, a small helper script walks you through Amazon's consent screen and prints your refresh token.

   • The script asks for your region (EU, NA or FE), your Client ID and your Client Secret, then prints a link.
   • Open the link in your browser, log in as the Amazon account that runs the ads, and click Allow.
   • The script catches the answer and prints your refresh token on the screen, once. Store it in your password manager right away. It writes no file, on purpose.

   Run in a terminal in the amazon-ads folder

   python get_refresh_token.py

   Copy

   Do the consent while logged in as the Amazon account that runs the ads. Consent done with another login leads to errors or zero profiles later.

   If the browser reports it cannot reach the page after you click Allow (a firewall blocking the local listener), use the script's fallback: copy the full address of the page you landed on and paste it into the script. It reads the code from that address.

10. 10

    Add your Ads keys and test them

    Same routine as the Seller toolkit, now in the amazon-ads folder.

    • In the amazon-ads folder, make a copy of .env.example and name the copy exactly .env.
    • Open it and paste your Client ID, Client Secret and refresh token after the = signs.
    • Check the region line: AMAZON_ADS_REGION=EU is right if you sell in Europe; use NA for the Americas or FE for Japan, Australia or Singapore.
    • Save and close. Never share this file.
    • Now test it with the command below. A good result starts with OK | credentials valid and lists the seller profiles the pull script will use.
    • Notepad is all you need to open and edit .env.

    Test it, in a terminal in the amazon-ads folder

    python verify_auth.py

    Copy

    The most likely failure is a line containing invalid_grant: the refresh token is expired, revoked or pasted wrong. Run get_refresh_token.py again for a fresh one and update .env. A FAILED line that names a .env value means exactly that: open .env and fill in the named value.

11. 11

    Your first Ads data pull

    Amazon keeps roughly 95 days of report history. Catch all of it once with the backfill command, then use the plain command for every pull after that.

    • The run takes several minutes. Amazon builds the reports on its side while the script waits politely.
    • At the end you see a line like: Done. 17 CSVs written, 1 fail/empty. The files are in the output folder, with the date and time in every filename.
    • Lines that say SKIP or EMPTY are normal. SKIP means your account does not have that optional feature enabled; EMPTY means you genuinely have zero of that thing, for example no negative targets. Only FAIL lines need a look.

    First run: catch all available history

    python pull_amazon_ads.py --backfill 95

    Copy

    Every run after that

    python pull_amazon_ads.py

    Copy

    The script pulls once per day and politely refuses a second run on the same day. Want to re-pull anyway? Add --force.

12. 12

    Run both pulls automatically every day

    Both toolkits are read-only, so they are safe to schedule. Set up one daily task per toolkit.

    • Press Start, type Task Scheduler, open it. Click Create Basic Task and give it a name like Amazon data pull.
    • Choose Daily and pick a quiet time, for example 06:30. Then choose Start a program.
    • Program: python. Add arguments: the full path to the pull script in quotes (right-click the file and choose Copy as path). Start in: the full path of the toolkit folder.
    • Finish, then repeat the same recipe for the other toolkit's pull script.

    Give the Seller task room: a full run can take up to 90 minutes. An accidental double schedule costs nothing; the built-in freshness check makes the second run stop by itself.

Stuck on any step? Mail us at support@toqool.com and a founder answers.