From shopify-admin-skills
Merges duplicate Shopify customer records using native customerMerge mutation where available, or consolidates tags and notes via customerUpdate. Useful after running duplicate-customer-finder.
npx claudepluginhub 40rty-ai/shopify-admin-skills --plugin shopify-admin-skillsThis skill uses the workspace's default tool permissions.
Resolves duplicate customer records identified by `duplicate-customer-finder`. Where the Shopify Admin API exposes `customerMerge` (a native merge that moves orders, addresses, subscriptions, and metafields onto a winner record), this skill calls it directly. When `customerMerge` is unavailable or fails for the given account pair, the skill falls back to consolidating searchable metadata — tags...
Finds likely duplicate Shopify customer records by matching email, phone, or name combinations. Read-only GraphQL queries flag issues like split order history and incorrect LTV/marketing segmentation.
Manages Shopify customers via GraphQL Admin API mutations/queries for create/update/delete/tags/metafields, Customer Account API, Multipass SSO, segmentation, B2B accounts.
Manages Shopify orders, customers, and fulfillments via GraphQL Admin API. Query orders, process fulfillments, handle customer records, create draft orders.
Share bugs, ideas, or general feedback.
Resolves duplicate customer records identified by duplicate-customer-finder. Where the Shopify Admin API exposes customerMerge (a native merge that moves orders, addresses, subscriptions, and metafields onto a winner record), this skill calls it directly. When customerMerge is unavailable or fails for the given account pair, the skill falls back to consolidating searchable metadata — tags, notes, marketing consent — onto the winner via customerUpdate, then writes a clear annotation to the loser record so staff can complete the merge manually in Shopify Admin.
shopify store auth --store <domain> --scopes read_customers,write_customersread_customers, write_customers| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| store | string | yes | — | Store domain (e.g., mystore.myshopify.com) |
| format | string | no | human | Output format: human or json |
| dry_run | bool | no | true | Preview merge plan without executing mutations |
| customer_winner_id | string | yes | — | GID of the customer record to keep (e.g., gid://shopify/Customer/12345) |
| customer_loser_id | string | yes | — | GID of the customer record to merge into the winner |
| use_native_merge | bool | no | true | Try customerMerge first; if it fails or is unavailable, fall back to consolidation via customerUpdate |
| merge_tags | bool | no | true | Union the loser's tags onto the winner |
| merge_note | bool | no | true | Append the loser's note to the winner (with timestamp prefix) |
| annotate_loser | bool | no | true | Write a note on the loser record pointing to the winner GID for manual cleanup |
⚠️ Steps 2–4 execute mutations that modify customer records.
customerMergeis irreversible — once orders and addresses are moved to the winner, the loser record is closed and cannot be split back. Run withdry_run: truefirst to confirm winner/loser GIDs and the merge plan. The default isdry_run: true. Always verify both records belong to the same human (matching email, phone, name) usingduplicate-customer-finderoutput before committing. Do not merge a customer with active subscriptions or unfulfilled orders without confirming downstream systems will follow the new owner GID.
OPERATION: customer — query (called twice: winner and loser)
Inputs: id: <customer_id>, select id, displayName, firstName, lastName, defaultEmailAddress { emailAddress }, phone, tags, note, numberOfOrders, amountSpent, emailMarketingConsent { marketingState }, smsMarketingConsent { marketingState }, addresses(first: 25) { id }, createdAt
Expected output: Both records' full identity payload — abort if either GID does not resolve
OPERATION: customerMerge — mutation (only if use_native_merge: true and not dry_run)
Inputs: customerOneId: <customer_winner_id>, customerTwoId: <customer_loser_id>, overrideFields: prefer winner's name/email/phone/locale/marketing-consent
Expected output: job.id (merge runs asynchronously), userErrors. If userErrors indicates merge is not supported for this pair (B2B, gift card holder, subscriber, etc.), proceed to step 3 fallback.
OPERATION: customerUpdate — mutation (winner) — fallback path or when use_native_merge: false
Inputs: input.id: <customer_winner_id>, input.tags: <union of winner.tags and loser.tags> (only if merge_tags), input.note: <winner.note + "\n[YYYY-MM-DD] Merged from <loser_email>:\n" + loser.note> (only if merge_note)
Expected output: customer.id, customer.tags, customer.note, userErrors
OPERATION: customerUpdate — mutation (loser) — only if annotate_loser: true
Inputs: input.id: <customer_loser_id>, input.note: "<existing note>\n[YYYY-MM-DD] DUPLICATE — merge target: <customer_winner_id>. Manually close in Shopify Admin once orders are reviewed.", input.tags: <existing + ["duplicate", "merged-loser"]>
Expected output: customer.id, customer.tags, customer.note, userErrors
# customer:query — validated against api_version 2025-01
query CustomerForMerge($id: ID!) {
customer(id: $id) {
id
displayName
firstName
lastName
defaultEmailAddress { emailAddress }
phone
tags
note
numberOfOrders
amountSpent { amount currencyCode }
emailMarketingConsent { marketingState marketingOptInLevel consentUpdatedAt }
smsMarketingConsent { marketingState marketingOptInLevel consentUpdatedAt }
addresses(first: 25) { id address1 city provinceCode countryCodeV2 zip }
createdAt
}
}
# customerMerge:mutation — validated against api_version 2025-01
mutation CustomerMerge(
$customerOneId: ID!
$customerTwoId: ID!
$overrideFields: CustomerMergeOverrideFields
) {
customerMerge(
customerOneId: $customerOneId
customerTwoId: $customerTwoId
overrideFields: $overrideFields
) {
job { id done }
resultingCustomerId
userErrors { field message code }
}
}
# customerUpdate:mutation — validated against api_version 2025-01
mutation CustomerConsolidate($input: CustomerInput!) {
customerUpdate(input: $input) {
customer { id displayName tags note }
userErrors { field message }
}
}
Claude MUST emit the following output at each stage. This is mandatory.
On start, emit:
╔══════════════════════════════════════════════╗
║ SKILL: Customer Merge ║
║ Store: <store domain> ║
║ Started: <YYYY-MM-DD HH:MM UTC> ║
╚══════════════════════════════════════════════╝
After each step, emit:
[N/TOTAL] <QUERY|MUTATION> <OperationName>
→ Params: <brief summary of key inputs>
→ Result: <count or outcome>
If dry_run: true, prefix every mutation step with [DRY RUN] and do not execute it.
On completion, emit:
For format: human (default):
══════════════════════════════════════════════
CUSTOMER MERGE OUTCOME
Winner: <name> (<email>) Orders: <n> Spent: $<n>
Loser: <name> (<email>) Orders: <n> Spent: $<n>
Path used: <native|fallback|skipped>
Merge job: <id or "n/a">
Tags consolidated: <n>
Note appended: <yes/no>
Loser annotated: <yes/no>
Errors: <n>
Output: none
══════════════════════════════════════════════
For format: json, emit:
{
"skill": "customer-merge",
"store": "<domain>",
"started_at": "<ISO8601>",
"completed_at": "<ISO8601>",
"dry_run": true,
"winner_id": "<gid>",
"loser_id": "<gid>",
"outcome": {
"path": "native|fallback",
"merge_job_id": "<id or null>",
"resulting_customer_id": "<gid or null>",
"tags_consolidated": 0,
"note_appended": false,
"loser_annotated": false,
"errors": 0,
"output_file": null
}
}
No CSV output. The session summary reports the merge job ID, the resulting customer GID, and which path was taken. For batch merges, run this skill once per pair and capture the JSON output.
| Error | Cause | Recovery |
|---|---|---|
THROTTLED | API rate limit exceeded | Wait 2 seconds, retry up to 3 times |
customerMerge userError: customer has subscriptions | Active subscription on loser | Cancel subscription before merge or use fallback path |
customerMerge userError: B2B customer | Company-affiliated record | Use fallback path; manual merge in Shopify Admin |
customerMerge userError: gift card holder | Loser owns gift card balance | Transfer gift card or use fallback path |
| Either GID not found | Wrong ID or deleted customer | Re-run duplicate-customer-finder |
| Merge job pending | Async merge not yet complete | Re-query Job(id) to confirm done: true |
duplicate-customer-finder first to confirm the pair is genuinely duplicate. Manual misclassifications are unrecoverable.createdAt. Avoid making the marketing-consenting record the loser.dry_run: true first; the preview shows both records' order counts and spend so you can sanity-check before committing.duplicate-customer-finder's CSV output — never batch merges in a single call.job.done: false response is normal — Shopify processes merges asynchronously. Re-query the job ID until completion before assuming the loser is closed.customerUpdate consolidation only) does not move orders. It preserves searchability via tags/notes so a human can finish the merge in Shopify Admin (Customers → Merge).