shopify-admin-customer-merge

Merge duplicate Shopify customer records via Admin API mutations with dry-run previews.

174|18|Updated Apr 11, 2026

Search Tags:#graphql #deduplication #shopify #customer merge #customerUpdate #customerMerge #admin automation

Ready to run

npx skills add https://github.com/40RTY-ai/shopify-admin-skills --skill shopify-admin-customer-merge

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: shopify-admin-customer-merge
Source: https://github.com/40RTY-ai/shopify-admin-skills/tree/main/skills/customer-support/shopify-admin-customer-merge
Command: npx skills add https://github.com/40RTY-ai/shopify-admin-skills --skill shopify-admin-customer-merge

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It resolves duplicate Shopify customer records by merging identities and consolidating customer data so support staff don’t have to manually clean up customer records and metadata.

Core Features & Use Cases

Native customer merge with guardrails: Uses Shopify’s customerMerge mutation when available to move related data onto the chosen winner record.
Fallback consolidation when merge is unsupported: Uses customerUpdate to union tags and notes onto the winner and annotates the loser for manual follow-up when native merge fails.
Dry-run planning and detailed outcomes: Supports a dry_run preview and emits step-by-step operation summaries plus a completion report that shows the path used and outcomes.

Quick Start

Merge the two duplicate customers on mystore.myshopify.com by keeping gid://shopify/Customer/12345 as the winner and using dry_run true to preview the result before executing the merge.

Frequently Asked Questions about shopify-admin-customer-merge

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I merge duplicate customers in Shopify?▼

You can merge duplicate customers by running this Skill with a winner customer ID and a loser ID. It uses Shopify's native customerMerge mutation to consolidate identities, tags, and notes while preserving data integrity.

What happens if Shopify customerMerge is unsupported or fails?▼

If the native customerMerge mutation fails, the Skill falls back to customerUpdate to union tags and notes onto the winner record and annotates the loser customer profile for manual follow-up.

Do I need specific Shopify Admin API permissions to merge customer records?▼

Yes, merging customer records requires authenticated Shopify Admin API access with read_customers and write_customers scopes to execute the deduplication operations successfully.

Can I preview a Shopify customer merge before applying changes?▼

Yes, you can preview a Shopify customer merge by enabling the dry_run option. This suppresses actual mutations and generates a step-by-step operation summary and completion report showing the planned path and outcomes.

Does this Shopify customer merge tool handle async jobs and structured reporting?▼

Yes, the Shopify customer merge process supports async merge jobs and emits structured outcome reporting. It provides a completion report detailing the path used and the final results of the deduplication workflow.

What is the best way to consolidate Shopify customer tags and notes during deduplication?▼

The best way to consolidate Shopify customer tags and notes during deduplication is to use automated customerMerge or customerUpdate fallback methods, which union metadata fields onto the winner record while preventing data loss.