Short answer
Read your apps' events from the Partner API and treat each shop as a client. Local CRM's Shopify Partners plugin creates one contact per shop, linked by shop ID so it's never duplicated, adds a timeline entry for every install, uninstall and charge, tags it, keeps its plan and billing fields current, and adds a follow-up todo for new installs. It runs on your own devices, with your own Partner API token.
For a Shopify app developer, every install is a merchant who chose your app, and every uninstall is a merchant who stopped. The Partner Dashboard shows those events as counts and charts. The merchants behind them, and what happened with each one, are easy to lose: who installed last week, who's on which plan, who came back after leaving, who you meant to write to.
What the Partner API tells you#
The Partner API reports what happens to your apps as events. There are 21 event types, in three groups:
| Group | Events |
|---|---|
| Installs | Installed, reactivated |
| Uninstalls | Uninstalled, deactivated |
| Billing | Subscription charges accepted, activated, canceled, declined, expired, frozen and unfrozen; capped amount updated or approaching; one-time charges accepted, activated, declined and expired; usage charges; credits applied, failed and pending |
Each event names its shop: its name, myshopify domain, ID and logo. That's all the API knows about the shop. Store emails and countries aren't part of it.
From events to a client#
Local CRM's Shopify Partners plugin turns that stream into clients. It reads the events of the apps you choose, with a Partner API client you create in the Partner Dashboard, and on each sync:
- Creates a client for each shop it hasn't seen, linked to the shop's ID.
- Adds one timeline entry per event.
- Tags installs and reactivations with “Shopify” and the app's name.
- Updates the client's fields: shop ID, myshopify domain, first install and, for each app, its status, plan with price and next billing date.
- Adds a follow-up todo for each new install: Follow up with Northwind Goods. New Stock Sync install. Say hello and help them get set up.
Partner API events
No client yet. Send an event and Northwind Goods appears here.
Send an event, as Shopify would after something happens in your app.
Rules that keep the history trustworthy#
A client's timeline is only useful if you can trust it: no gaps, no doubles, no stale alarms. Four rules see to that.
Read twice, record once. Each sync reads the last hour again, so an event Shopify reports late isn't missed. Every timeline entry is keyed by its event ID, so the second copy adds nothing.
The 48-hour rule. The first sync of an app can bring in years of history. Treating all of it as news would bury you in todos for merchants who installed in 2023. So while importing history, only installs and returns from the last 48 hours count as new; older events get their timeline entries, without a todo or a notification. After the first sync, every new event is news, however late it's seen, for example after your Mac was switched off for a weekend.
One summary instead of a burst. You get a notification for each new client, and for existing clients who come back by installing another of your apps, reinstalling or reactivating. When one sync finds more than three of them, you get a single summary instead. Tapping a notification opens the client.
Your edits win. If a shop renames itself in Shopify, its client follows, unless you've renamed the client yourself.
What stays out#
No scraping. Local CRM doesn't read the Partner Dashboard; Shopify's terms don't allow it. For store emails and countries, it imports the merchant CSV the Partner Dashboard emails you when you export current merchants, matches each store to its client, and fills in a work email and the country. A later import only replaces what an earlier import wrote, never what you entered.
Your token stays yours. The Partner API token is kept in the Keychain on your device, or in iCloud Keychain when iCloud sync is on, and Local CRM uses it to talk to Shopify directly. There's no h2made server in between.
Merchant data is for serving the merchant. Shopify's Partner Program Agreement allows merchant data only for providing your services to that merchant. A CRM that helps you follow up with the people who use your app is that; a mailing list for something else isn't.
On the Free plan#
The Free plan covers one Shopify app, one Partner organization and 20 active shops. The first sync brings in the 20 most recently installed shops, and later installs wait until there's room. Waiting shops aren't lost: after an upgrade, they arrive with their whole history, without a burst of notifications. More on that in how Local CRM's limits work.
See the plugin among the rest of Local CRM's features on the Local CRM page, or read what it needs to connect in the FAQ. When two of your devices import the same shop before syncing, Local CRM merges the duplicates.
Questions this note answers
- Which Shopify events does Local CRM read?
- All 21 app event types of the Partner API: installs, uninstalls, deactivations and reactivations; subscription, one-time and usage charges; and credits.
- Will importing my app's history flood me with todos and notifications?
- No. When importing history, only installs and returns from the last 48 hours count as new. Older events go on the timeline without a follow-up todo or a notification.
- Can syncing create the same shop twice?
- No. Each client is linked to its shop ID and each timeline entry to its event ID, so reading the same events again changes nothing. If two devices import the same shop before they sync, Local CRM merges the two.
- Where do store emails and countries come from?
- The Partner API doesn't include them. Local CRM imports the merchant CSV that the Partner Dashboard emails you, and fills them in on the matching clients.
Select any passage to quote it with a link straight to it.