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.

2Create 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.

• 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.

3Grant 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.

4Install 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.

5Connect in picoask

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

• Store domain — the .myshopify.com domain from step 1.
• Admin API access token — the shpat_… token from step 4.

picoask checks the token and the granted scopes before saving, so a missing scope is reported immediately rather than showing up later as missing data. The token is stored encrypted and used only by the sync worker.

6About 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.

7What 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.

8Troubleshooting

• Access token rejected — the token was copied incompletely, or the app was uninstalled and reinstalled (which issues a new one).
• Missing scope — the error names the scope. Add it under Configuration, then reinstall the app and 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 6.
• 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.