shopify-admin-duplicate-customer-finder

Name: shopify-admin-duplicate-customer-finder
Author: 40RTY-ai

168stars17forks

How to install shopify-admin-duplicate-customer-finder?

40rty-ai/shopify-admin-skills/shopify-admin-duplicate-customer-finder

$npx -y skills add 40RTY-ai/shopify-admin-skills --skill shopify-admin-duplicate-customer-finder

Installs into the current project.

Summary

Read-only: finds likely duplicate customer records by matching email, phone, or name combinations.

Files · 1

View on GitHub

SKILL.md

1	## Purpose
2	Scans the customer database for likely duplicate records using email, phone, and name matching. Duplicate customer records cause split order history, incorrect LTV calculations, and incorrect marketing segmentation. Read-only — no mutations.
3
4	## Prerequisites
5	- Authenticated Shopify CLI session: `shopify store auth --store <domain> --scopes read_customers`
6	- API scopes: `read_customers`
7
8	## Parameters
9
10	\| Parameter \| Type \| Required \| Default \| Description \|
11	\|-----------\|------\|----------\|---------\|-------------\|
12	\| store \| string \| yes \| — \| Store domain (e.g., mystore.myshopify.com) \|
13	\| match_on \| string \| no \| email \| Match strategy: `email`, `phone`, `name`, or `all` \|
14	\| min_orders \| integer \| no \| 0 \| Only flag duplicates where at least one record has this many orders \|
15	\| format \| string \| no \| human \| Output format: `human` or `json` \|
16
17	## Safety
18
19	> ℹ️ Read-only skill — no mutations are executed. Safe to run at any time. Duplicate merging is not supported by the Shopify Admin API — flagged duplicates must be merged manually in Shopify Admin.
20
21	## Workflow Steps
22
23	1. OPERATION: `customers` — query
24	Inputs: `first: 250`, select `email`, `phone`, `firstName`, `lastName`, `numberOfOrders`, `totalSpentV2`, pagination cursor
25	Expected output: All customers with contact and order data; paginate until `hasNextPage: false`
26
27	2. Build in-memory lookup maps:
28	- `email → [customer_ids]`
29	- `phone → [customer_ids]` (if `match_on` includes phone)
30	- `"firstName lastName" → [customer_ids]` (if `match_on` includes name)
31
32	3. Report groups with > 1 customer per key as likely duplicates
33
34	## GraphQL Operations
35
36	```graphql
37	# customers:query — validated against api_version 2025-01
38	query CustomersForDeduplication($after: String) {
39	customers(first: 250, after: $after) {
40	edges {
41	node {
42	id
43	displayName
44	firstName
45	lastName
46	defaultEmailAddress {
47	emailAddress
48	}
49	phone
50	numberOfOrders
51	amountSpent {
52	amount
53	currencyCode
54	}
55	createdAt
56	}
57	}
58	pageInfo {
59	hasNextPage
60	endCursor
61	}
62	}
63	}
64	```
65
66	## Session Tracking
67
68	Claude MUST emit the following output at each stage. This is mandatory.
69
70	On start, emit:
71	```
72	╔══════════════════════════════════════════════╗
73	║ SKILL: Duplicate Customer Finder ║
74	║ Store: <store domain> ║
75	║ Started: <YYYY-MM-DD HH:MM UTC> ║
76	╚══════════════════════════════════════════════╝
77	```
78
79	After each step, emit:
80	```
81	[N/TOTAL] <QUERY\|MUTATION> <OperationName>
82	→ Params: <brief summary of key inputs>
83	→ Result: <count or outcome>
84	```
85
86	On completion, emit:
87
88	For `format: human` (default):
89	```
90	══════════════════════════════════════════════
91	DUPLICATE CUSTOMER REPORT
92	Customers scanned: <n>
93	Duplicate groups found: <n>
94	Customers affected: <n>
95
96	Duplicate groups (sample):
97	Email: user@example.com
98	Customer A — <n> orders, $<n> spent, created <date>
99	Customer B — <n> orders, $<n> spent, created <date>
100	Output: duplicate_customers_<date>.csv
101	══════════════════════════════════════════════
102	```
103
104	For `format: json`, emit:
105	```json
106	{
107	"skill": "duplicate-customer-finder",
108	"store": "<domain>",
109	"customers_scanned": 0,
110	"duplicate_groups": 0,
111	"customers_affected": 0,
112	"output_file": "duplicate_customers_<date>.csv"
113	}
114	```
115
116	## Output Format
117	CSV file `duplicate_customers_<YYYY-MM-DD>.csv` with columns:
118	`duplicate_group_id`, `match_key`, `match_type`, `customer_id`, `name`, `email`, `phone`, `number_of_orders`, `total_spent`, `created_at`
119
120	## Error Handling
121	\| Error \| Cause \| Recovery \|
122	\|-------\|-------\|----------\|
123	\| `THROTTLED` \| API rate limit exceeded \| Wait 2 seconds, retry up to 3 times \|
124	\| No duplicates found \| Clean customer database \| Exit with ✅ no duplicates found \|
125
126	## Best Practices
127	- Shopify does not provide a native merge API — flagged duplicates must be resolved manually in Shopify Admin (Customers → Merge).
128	- `match_on: email` finds the most reliable duplicates; `match_on: name` produces more false positives (common names).
129	- Prioritize duplicates where at least one record has orders — these affect LTV and marketing segmentation most.
130	- Common causes of duplicates: guest checkout followed by account creation, manual customer imports, or customers using multiple email addresses.

People who liked this also viewed

6 picks

Type

shopify-admin-duplicate-customer-finder

168stars17forks

View on GitHub

How to install shopify-admin-duplicate-customer-finder?

40rty-ai/shopify-admin-skills/shopify-admin-duplicate-customer-finder

$npx -y skills add 40RTY-ai/shopify-admin-skills --skill shopify-admin-duplicate-customer-finder

Installs into the current project.

Summary

Read-only: finds likely duplicate customer records by matching email, phone, or name combinations.

Files · 1

View on GitHub

SKILL.md

1	## Purpose
2	Scans the customer database for likely duplicate records using email, phone, and name matching. Duplicate customer records cause split order history, incorrect LTV calculations, and incorrect marketing segmentation. Read-only — no mutations.
3
4	## Prerequisites
5	- Authenticated Shopify CLI session: `shopify store auth --store <domain> --scopes read_customers`
6	- API scopes: `read_customers`
7
8	## Parameters
9
10	\| Parameter \| Type \| Required \| Default \| Description \|
11	\|-----------\|------\|----------\|---------\|-------------\|
12	\| store \| string \| yes \| — \| Store domain (e.g., mystore.myshopify.com) \|
13	\| match_on \| string \| no \| email \| Match strategy: `email`, `phone`, `name`, or `all` \|
14	\| min_orders \| integer \| no \| 0 \| Only flag duplicates where at least one record has this many orders \|
15	\| format \| string \| no \| human \| Output format: `human` or `json` \|
16
17	## Safety
18
19	> ℹ️ Read-only skill — no mutations are executed. Safe to run at any time. Duplicate merging is not supported by the Shopify Admin API — flagged duplicates must be merged manually in Shopify Admin.
20
21	## Workflow Steps
22
23	1. OPERATION: `customers` — query
24	Inputs: `first: 250`, select `email`, `phone`, `firstName`, `lastName`, `numberOfOrders`, `totalSpentV2`, pagination cursor
25	Expected output: All customers with contact and order data; paginate until `hasNextPage: false`
26
27	2. Build in-memory lookup maps:
28	- `email → [customer_ids]`
29	- `phone → [customer_ids]` (if `match_on` includes phone)
30	- `"firstName lastName" → [customer_ids]` (if `match_on` includes name)
31
32	3. Report groups with > 1 customer per key as likely duplicates
33
34	## GraphQL Operations
35
36	```graphql
37	# customers:query — validated against api_version 2025-01
38	query CustomersForDeduplication($after: String) {
39	customers(first: 250, after: $after) {
40	edges {
41	node {
42	id
43	displayName
44	firstName
45	lastName
46	defaultEmailAddress {
47	emailAddress
48	}
49	phone
50	numberOfOrders
51	amountSpent {
52	amount
53	currencyCode
54	}
55	createdAt
56	}
57	}
58	pageInfo {
59	hasNextPage
60	endCursor
61	}
62	}
63	}
64	```
65
66	## Session Tracking
67
68	Claude MUST emit the following output at each stage. This is mandatory.
69
70	On start, emit:
71	```
72	╔══════════════════════════════════════════════╗
73	║ SKILL: Duplicate Customer Finder ║
74	║ Store: <store domain> ║
75	║ Started: <YYYY-MM-DD HH:MM UTC> ║
76	╚══════════════════════════════════════════════╝
77	```
78
79	After each step, emit:
80	```
81	[N/TOTAL] <QUERY\|MUTATION> <OperationName>
82	→ Params: <brief summary of key inputs>
83	→ Result: <count or outcome>
84	```
85
86	On completion, emit:
87
88	For `format: human` (default):
89	```
90	══════════════════════════════════════════════
91	DUPLICATE CUSTOMER REPORT
92	Customers scanned: <n>
93	Duplicate groups found: <n>
94	Customers affected: <n>
95
96	Duplicate groups (sample):
97	Email: user@example.com
98	Customer A — <n> orders, $<n> spent, created <date>
99	Customer B — <n> orders, $<n> spent, created <date>
100	Output: duplicate_customers_<date>.csv
101	══════════════════════════════════════════════
102	```
103
104	For `format: json`, emit:
105	```json
106	{
107	"skill": "duplicate-customer-finder",
108	"store": "<domain>",
109	"customers_scanned": 0,
110	"duplicate_groups": 0,
111	"customers_affected": 0,
112	"output_file": "duplicate_customers_<date>.csv"
113	}
114	```
115
116	## Output Format
117	CSV file `duplicate_customers_<YYYY-MM-DD>.csv` with columns:
118	`duplicate_group_id`, `match_key`, `match_type`, `customer_id`, `name`, `email`, `phone`, `number_of_orders`, `total_spent`, `created_at`
119
120	## Error Handling
121	\| Error \| Cause \| Recovery \|
122	\|-------\|-------\|----------\|
123	\| `THROTTLED` \| API rate limit exceeded \| Wait 2 seconds, retry up to 3 times \|
124	\| No duplicates found \| Clean customer database \| Exit with ✅ no duplicates found \|
125
126	## Best Practices
127	- Shopify does not provide a native merge API — flagged duplicates must be resolved manually in Shopify Admin (Customers → Merge).
128	- `match_on: email` finds the most reliable duplicates; `match_on: name` produces more false positives (common names).
129	- Prioritize duplicates where at least one record has orders — these affect LTV and marketing segmentation most.
130	- Common causes of duplicates: guest checkout followed by account creation, manual customer imports, or customers using multiple email addresses.

People who liked this also viewed

6 picks

Type