Connect Shopify

1Find your store domain

• picoask needs your permanent .myshopify.com domain — e.g. acme.myshopify.com.
• Not your customer-facing domain. acme.com can change when you rebrand; the .myshopify.com one never does, which is why it is the key everything joins on.
• Find it in Settings → Domains, listed as the store's permanent domain.

2Which setup applies to your store

There are two ways to connect, and your store uses exactly one — it depends on when the store was created.

• Store created before 1 January 2026 → follow steps 3–5 (create a custom app in your store admin and paste its permanent shpat_ token). This is the classic flow and nothing about it has changed.
• Store created on or after 1 January 2026 → follow step 6 instead. Shopify retired in-admin custom-app tokens on that date, so newer stores create an app in the Shopify Dev Dashboard and paste its client ID and client secret. picoask exchanges those for a fresh 24-hour token before every sync — you paste them once and never touch them again.

Either way you paste into the same Shopify connector form: fill the token field or the client ID + secret fields, whichever your store has. Leave the other fields blank.

3Older stores: create a custom app

Shopify calls a private, store-owned integration a custom app. You create it yourself — nothing goes through the App Store, and no Shopify review is involved. Skip this step if your store was created on or after 1 January 2026 — go to step 6.

• In your store admin, open Settings → Apps and sales channels → Develop apps.
• Choose Create an app, name it something recognisable (picoask), and select yourself as the developer.

If “Develop apps” is missing or “Create an app” is disabled, your store is on the newer model — go to step 6.

4Older stores: grant the Admin API scopes

Open Configuration → Admin API integration → Configure and tick:

• read_orders — orders, line items, refunds and discounts. Required.
• read_customers — customer records, for repeat-purchase and lifetime-value questions. Required.
• read_products — product and variant details on each line.
• read_all_orders — strongly recommended. Without it Shopify exposes only the last 60 days of orders, so no year-on-year or seasonal question can be answered. See the note below.
• read_inventory — optional. The only source of unit cost, which is what makes margin questions possible.

picoask only ever reads. No scope it asks for can change anything in your store.

5Older stores: install and copy the token

• Choose Save, then Install app.
• Under API credentials, reveal the Admin API access token. It starts with shpat_.
• Shopify shows this token once. Copy it straight into picoask — if you lose it you will need to uninstall and reinstall the app to get a new one.

Then go to step 7 to connect. Older stores are done after this — skip step 6.

6Newer stores: create a Dev Dashboard app

For stores created on or after 1 January 2026. Shopify no longer issues permanent custom-app tokens for these, so you create an app in the Shopify Dev Dashboard and picoask mints a fresh 24-hour token from its credentials before each sync. This works because the app and your store are in the same Shopify organisation — you own both.

• Go to the Shopify Dev Dashboard (dev.shopify.com), signed in with the same account that owns your store, and create an app. Name it picoask.
• Open the app's API access / Configuration and add the Admin API scopes: read_orders, read_customers, read_products, and read_all_orders (for history beyond 60 days — see step 8). read_inventory is optional and adds unit cost.
• Install the app on your store when prompted, so the scopes take effect.
• Under the app's client credentials / API credentials, copy the Client ID and the Client secret.

You paste both into picoask once. picoask exchanges them for a short-lived read-only token on every sync — it never charges, refunds, or changes anything, and the credentials are stored encrypted and never logged.

7Connect in picoask

In your project's Integrations tab, choose Shopify → Connect and fill in:

• Store domain — the .myshopify.com domain from step 1.
• Older stores — paste the shpat_… token from step 5 into Admin API access token, and leave the client ID and secret blank.
• Newer stores — paste the Client ID and Client secret from step 6, and leave the access-token field blank.

Fill one path or the other, never both — empty fields are ignored. picoask checks whatever you supplied (for a Dev Dashboard app it mints a test token there and then) and verifies the granted scopes before saving, so a wrong secret or a missing scope is reported immediately rather than showing up later as missing data. Credentials are stored encrypted and used only by the sync worker.

8About the 60-day limit

This is the one thing worth understanding before you connect.

• With read_orders alone, Shopify's API returns only orders from the last 60 days — no matter how long your store has been trading.
• read_all_orders lifts that. If the checkbox is greyed out in your admin, Shopify requires a request for it; the option to ask sits beside the scope.
• picoask will not quietly import two months and present it as your history. If the scope is missing, the initial import stops and tells you — you can then either grant it, or explicitly accept the 60-day window and continue.

9What gets synced

• Orders — totals, taxes, shipping, tips, currency, sales channel, and where the visit came from.
• Line items — product, variant, SKU, quantity, list and realised price, and the discount applied.
• Refunds — broken down by what was refunded (items, shipping, duties), and flagged for whether money actually moved. A restocked return with no refund is recorded as goods returned, not as revenue lost.
• Discounts — per code, with the amount actually given away rather than the configured percentage.
• Customers — order counts and lifetime spend. Email addresses are hashed, never stored.

An order refunded months after it was placed stays booked to the day it was placed, while the refund is dated to the day it happened — so "revenue in March" and "refunds in June" are both answerable, and neither borrows from the other.

10Troubleshooting

• Access token rejected — the token was copied incompletely, or the app was uninstalled and reinstalled (which issues a new one).
• Client credentials rejected (newer stores) — the client ID or secret was copied incompletely, or the Dev Dashboard app is not in the same Shopify organisation as the store. Create the app from the account that owns the store, install it on the store, then re-copy both values.
• Missing scope — the error names the scope. Add it under the app's configuration, then reinstall the app (older stores also paste the new token): changing scopes does not update an existing token.
• Only 60 days of orders — read_all_orders was not granted. See step 8.
• Store not found — the customer-facing domain was entered instead of the .myshopify.com one.
• Costs and margins are empty — read_inventory was not granted; it is the only source of unit cost.