Customer Merge

Purpose

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.

Prerequisites

Parameters

Safety

> ⚠️ Steps 2–4 execute mutations that modify customer records. customerMerge is irreversible — once orders and addresses are moved to the winner, the loser record is closed and cannot be split back. Run with dry_run: true first to confirm winner/loser GIDs and the merge plan. The default is dry_run: true. Always verify both records belong to the same human (matching email, phone, name) using duplicate-customer-finder output before committing. Do not merge a customer with active subscriptions or unfulfilled orders without confirming downstream systems will follow the new owner GID.

Workflow Steps

Inputs: 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

Inputs: customerOneId: , customerTwoId: , 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.

Inputs: input.id: , input.tags: (only if merge_tags), input.note: :\n" + loser.note> (only if merge_note)

Expected output: customer.id, customer.tags, customer.note, userErrors

Inputs: input.id: , input.note: "\n[YYYY-MM-DD] DUPLICATE — merge target: . Manually close in Shopify Admin once orders are reviewed.", input.tags:

Expected output: customer.id, customer.tags, customer.note, userErrors

GraphQL Operations

# 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 }
  }
}

Session Tracking

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
  }
}

Output Format

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 Handling

Best Practices