Set up your Shopify toolkit

1. 1

   Unzip the toolkit

   Unzip the toolkit into a folder you can find back, for example in your Documents. Inside you will find two folders that do very different things.

   • pull/ reads data OUT of your store. It cannot change anything, and that guarantee is enforced in the code itself.
   • push/ writes changes INTO your store. It always shows a plan of exactly what will change first, and changes nothing until you type YES at the keyboard.
   • Both folders contain a .env.example file (the template for your keys) and a requirements.txt (the Python dependency).

   Fetching data can never accidentally change your store. That is why pull and push are separate, each with its own API key.

2. 2

   Install Python

   The toolkit runs on Python, a free program. Get it at python.org, version 3.9 or newer.

   • Run the installer from python.org and tick the box that says Add python.exe to PATH.

   On Windows, do not skip the Add python.exe to PATH checkbox in the installer. Without it your terminal will not know what python means.

   On Mac and Linux the commands are pip3 and python3. On Windows they are pip and python. This guide shows both where they differ.

3. 3

   Learn to open a terminal in a folder

   You will type the commands in a terminal, and it matters which folder that terminal is standing in. Here is the trick for each system.

   • Open the folder in Explorer, click in the address bar at the top, type cmd and press Enter. A black window opens, already in that folder.
4. 4

   Install the Python dependency

   A one-time install. Open a terminal in the pull folder and run the command below. Then do the same in the push folder.

   In the pull folder, then again in the push folder

   pip install -r requirements.txt

   Copy
5. 5

   Create your pull app in the Shopify Dev Dashboard

   You create two separate apps in the Shopify Dev Dashboard: a read app for pull and a write app for push. First the pull app. Note that the app and your store must be in the same Shopify organization.

   • Go to dev.shopify.com (the Shopify Dev Dashboard) and log in with your store's account.
   • Click Apps in the left menu, then Create app (top right), choose Start from Dev Dashboard, name it (for example your-store-pull) and click Create.
   • Choose the app's permissions (scopes) with the visual picker. For the pull app, tick READ permissions (names starting with read_).
   • After choosing, click Release. Permissions only take effect once released.
   • In the app, go to Home -> Install app, pick your store, and install.
   • Go to Settings and copy the Client ID and Client secret. Those are your two pull keys. The secret is shown once, so store both in your password manager.
   • If your screen looks different: Shopify refreshes this dashboard now and then. Search shopify.dev for Create apps using the Dev Dashboard and follow that.

   Choose permissions with the visual picker, never by pasting a list of scope names. One wrong name makes Shopify reject the whole list.

   Tick read_all_orders too if you want order history older than 60 days. Without it Shopify silently limits orders to the last 60 days.

6. 6

   Create your push app the same way

   Repeat the same steps for the push app (for example your-store-push). This time also tick WRITE permissions.

   • Start small: read_products, write_products, read_inventory, write_inventory, read_locations, read_publications.
   • You can add more scopes later for pages, discounts and the other capabilities when you start using them.
   • As before: install the app on your store and copy the Client ID and Client secret from Settings.

   Release first, then install. An installed app only has the permissions of its released version.

   Key lost or leaked? Go to the app's Settings and generate a new secret, then update your .env file. Want to stop everything at once? Uninstall the app from your store; the other app keeps working.

7. 7

   Add your keys to the .env files

   Open the pull folder. Copy the file .env.example and name the copy exactly .env, in the same folder. Open .env with Notepad (Windows) or TextEdit (Mac), fill in your .myshopify.com address plus the Client ID and Client secret of your PULL app, and save. Then do the same in the push folder, with the keys of your PUSH app.

   • SHOPIFY_STORE_DOMAIN: your .myshopify.com address
   • SHOPIFY_CLIENT_ID: the Client ID of that folder's app
   • SHOPIFY_CLIENT_SECRET: the Client secret of that folder's app

   Common trap: filling in your normal web address as the store domain. The scripts need the address that ends in .myshopify.com. You find it in Shopify admin -> Settings -> Domains.

   Never share the .env file with anyone and never email it.

8. 8

   Test your keys with verify_auth

   Time for the first real test. In a terminal in the pull folder, run verify_auth. A good result starts with OK | credentials valid and shows your shop name, domain, plan and the number of granted scopes. Then run the same command in the push folder. A good result there starts with OK | credentials valid | WRITE scope confirmed, with an OK line per capability group.

   In the pull folder, then again in the push folder

   python verify_auth.py

   Copy

   The most likely failure is FAILED | token exchange returned HTTP 401. That means a wrong Client ID or secret, or the app is not installed on your store. Re-copy the keys from the Dev Dashboard and check the app is installed.

   On the push side, capabilities marked MISSING just mean you have not granted that scope. That is fine if you do not plan to use them.

9. 9

   Run your first pull

   In a terminal in the pull folder, start with the smoke run: a mini test (2 rows per list) to see that everything works. Then run the full pull. The full run takes a few minutes and ends with a line like Done. 47 CSVs written, 0 fail/empty.

   • The number of CSVs differs per store. Features your store does not use (say, gift cards) write no file. That is normal, not an error.
   • What matters is the end of the line: 0 fail/empty.

   Mini test run first

   python pull_shopify_admin.py --smoke

   Copy

   Then the full pull

   python pull_shopify_admin.py

   Copy

   Rate-limit waits are normal. The script waits and retries by itself, so a run that pauses now and then is healthy, not stuck.

10. 10

    Run it automatically every day

    The pull side is safe to run on a schedule, because it can only read. On Windows you use Task Scheduler, on Mac and Linux you use cron.

    • Press Start, type Task Scheduler, open it.
    • Click Create Basic Task, name it (for example Shopify pull), choose Daily and pick a time (say 06:30).
    • Choose Start a program. Program: python. Argument: the full path to pull_shopify_admin.py in quotes. Start in: the full path of the pull folder.
    • Finish, then right-click the task and choose Run once to check it works.

    Only ever automate the PULL script. Never automate push: a change to your live store always deserves human eyes, and the YES question blocks schedulers on purpose.

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