Choose a version:

customerMerge

mutation

Requires write_customer_merge access scope.

Merges two customers.

The customerOneId and customerTwoId arguments don't guarantee which customer is kept. Shopify selects the resulting customer in this order:

If overrideFields.customerIdOfEmailToKeep is provided and valid, then the selected customer is kept.
If exactly one customer has an email address, then that customer is kept.
If both customers have email addresses, then account state and email marketing consent determine the customer that's kept: an enabled account wins over other account states; otherwise, an invited account can win when consent doesn't already prefer subscribed or pending; otherwise the consent result is used. If those rules don't prefer either customer, then customerTwoId is kept.
If neither customer has an email address, then customerTwoId is kept.

Use customerMergePreview and resultingCustomerId to check which customer will be kept before merging.

Anchor to Arguments

Arguments

Anchor to customerOneIdcustomerOneId

•ID!

required

The ID of one customer to merge. This customer isn't guaranteed to be kept.

Anchor to customerTwoIdcustomerTwoId

•ID!

required

The ID of another customer to merge. This customer is kept when neither customer has an email address.

Anchor to overrideFieldsoverrideFields

•CustomerMergeOverrideFields

The field-specific overrides for default customer merge rules.

Was this section helpful?

Anchor to CustomerMergePayload returnsCustomerMergePayload returns

Anchor to jobjob •Job: The asynchronous job for merging the customers.
Anchor to resultingCustomerIdresultingCustomerId •ID: The ID of the customer that's kept after the merge. Treat this ID as authoritative.
Anchor to userErrorsuserErrors •[CustomerMergeUserError!]! non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Merge customers with override fields

Description

Merge customers with override fields.

Query

mutation CustomerMerge {
  customerMerge(customerOneId: "gid://shopify/Customer/544365967", customerTwoId: "gid://shopify/Customer/624407574", overrideFields: {customerIdOfFirstNameToKeep: "gid://shopify/Customer/544365967", customerIdOfLastNameToKeep: "gid://shopify/Customer/624407574"}) {
    resultingCustomerId
    job {
      id
      done
    }
    userErrors {
      code
      field
      message
    }
  }
}

Variables

{
  "customerOneId": "gid://shopify/Customer/544365967",
  "customerTwoId": "gid://shopify/Customer/624407574",
  "overrideFields": {
    "customerIdOfFirstNameToKeep": "gid://shopify/Customer/544365967",
    "customerIdOfLastNameToKeep": "gid://shopify/Customer/544365967"
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation CustomerMerge { customerMerge(customerOneId: \"gid://shopify/Customer/544365967\", customerTwoId: \"gid://shopify/Customer/624407574\", overrideFields: {customerIdOfFirstNameToKeep: \"gid://shopify/Customer/544365967\", customerIdOfLastNameToKeep: \"gid://shopify/Customer/624407574\"}) { resultingCustomerId job { id done } userErrors { code field message } } }",
 "variables": {
    "customerOneId": "gid://shopify/Customer/544365967",
    "customerTwoId": "gid://shopify/Customer/624407574",
    "overrideFields": {
      "customerIdOfFirstNameToKeep": "gid://shopify/Customer/544365967",
      "customerIdOfLastNameToKeep": "gid://shopify/Customer/544365967"
    }
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation CustomerMerge {
    customerMerge(customerOneId: "gid://shopify/Customer/544365967", customerTwoId: "gid://shopify/Customer/624407574", overrideFields: {customerIdOfFirstNameToKeep: "gid://shopify/Customer/544365967", customerIdOfLastNameToKeep: "gid://shopify/Customer/624407574"}) {
      resultingCustomerId
      job {
        id
        done
      }
      userErrors {
        code
        field
        message
      }
    }
  }`,
  {
    variables: {
        "customerOneId": "gid://shopify/Customer/544365967",
        "customerTwoId": "gid://shopify/Customer/624407574",
        "overrideFields": {
            "customerIdOfFirstNameToKeep": "gid://shopify/Customer/544365967",
            "customerIdOfLastNameToKeep": "gid://shopify/Customer/544365967"
        }
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation CustomerMerge {
    customerMerge(customerOneId: "gid://shopify/Customer/544365967", customerTwoId: "gid://shopify/Customer/624407574", overrideFields: {customerIdOfFirstNameToKeep: "gid://shopify/Customer/544365967", customerIdOfLastNameToKeep: "gid://shopify/Customer/624407574"}) {
      resultingCustomerId
      job {
        id
        done
      }
      userErrors {
        code
        field
        message
      }
    }
  }
QUERY

variables = {
  "customerOneId": "gid://shopify/Customer/544365967",
  "customerTwoId": "gid://shopify/Customer/624407574",
  "overrideFields": {
    "customerIdOfFirstNameToKeep": "gid://shopify/Customer/544365967",
    "customerIdOfLastNameToKeep": "gid://shopify/Customer/544365967"
  }
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation CustomerMerge {
      customerMerge(customerOneId: "gid://shopify/Customer/544365967", customerTwoId: "gid://shopify/Customer/624407574", overrideFields: {customerIdOfFirstNameToKeep: "gid://shopify/Customer/544365967", customerIdOfLastNameToKeep: "gid://shopify/Customer/624407574"}) {
        resultingCustomerId
        job {
          id
          done
        }
        userErrors {
          code
          field
          message
        }
      }
    }`,
    "variables": {
        "customerOneId": "gid://shopify/Customer/544365967",
        "customerTwoId": "gid://shopify/Customer/624407574",
        "overrideFields": {
            "customerIdOfFirstNameToKeep": "gid://shopify/Customer/544365967",
            "customerIdOfLastNameToKeep": "gid://shopify/Customer/544365967"
        }
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation CustomerMerge {
  customerMerge(customerOneId: "gid://shopify/Customer/544365967", customerTwoId: "gid://shopify/Customer/624407574", overrideFields: {customerIdOfFirstNameToKeep: "gid://shopify/Customer/544365967", customerIdOfLastNameToKeep: "gid://shopify/Customer/624407574"}) {
    resultingCustomerId
    job {
      id
      done
    }
    userErrors {
      code
      field
      message
    }
  }
}' \
--variables \
'{
  "customerOneId": "gid://shopify/Customer/544365967",
  "customerTwoId": "gid://shopify/Customer/624407574",
  "overrideFields": {
    "customerIdOfFirstNameToKeep": "gid://shopify/Customer/544365967",
    "customerIdOfLastNameToKeep": "gid://shopify/Customer/544365967"
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation CustomerMerge {
        customerMerge(customerOneId: "gid://shopify/Customer/544365967", customerTwoId: "gid://shopify/Customer/624407574", overrideFields: {customerIdOfFirstNameToKeep: "gid://shopify/Customer/544365967", customerIdOfLastNameToKeep: "gid://shopify/Customer/624407574"}) {
          resultingCustomerId
          job {
            id
            done
          }
          userErrors {
            code
            field
            message
          }
        }
      }
    `,
    variables: {
        "customerOneId": "gid://shopify/Customer/544365967",
        "customerTwoId": "gid://shopify/Customer/624407574",
        "overrideFields": {
            "customerIdOfFirstNameToKeep": "gid://shopify/Customer/544365967",
            "customerIdOfLastNameToKeep": "gid://shopify/Customer/544365967"
        }
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "customerMerge": {
    "resultingCustomerId": "gid://shopify/Customer/624407574",
    "job": {
      "id": "gid://shopify/Job/ab22429a-ea18-4dad-ac2c-5823288b1e59",
      "done": true
    },
    "userErrors": []
  }
}

Merge two customers

Description

Merge two customers.

Query

mutation CustomerMerge {
  customerMerge(customerOneId: "gid://shopify/Customer/544365967", customerTwoId: "gid://shopify/Customer/624407574") {
    resultingCustomerId
    job {
      id
      done
    }
    userErrors {
      code
      field
      message
    }
  }
}

Variables

{
  "customerOneId": "gid://shopify/Customer/544365967",
  "customerTwoId": "gid://shopify/Customer/624407574"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation CustomerMerge { customerMerge(customerOneId: \"gid://shopify/Customer/544365967\", customerTwoId: \"gid://shopify/Customer/624407574\") { resultingCustomerId job { id done } userErrors { code field message } } }",
 "variables": {
    "customerOneId": "gid://shopify/Customer/544365967",
    "customerTwoId": "gid://shopify/Customer/624407574"
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation CustomerMerge {
    customerMerge(customerOneId: "gid://shopify/Customer/544365967", customerTwoId: "gid://shopify/Customer/624407574") {
      resultingCustomerId
      job {
        id
        done
      }
      userErrors {
        code
        field
        message
      }
    }
  }`,
  {
    variables: {
        "customerOneId": "gid://shopify/Customer/544365967",
        "customerTwoId": "gid://shopify/Customer/624407574"
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation CustomerMerge {
    customerMerge(customerOneId: "gid://shopify/Customer/544365967", customerTwoId: "gid://shopify/Customer/624407574") {
      resultingCustomerId
      job {
        id
        done
      }
      userErrors {
        code
        field
        message
      }
    }
  }
QUERY

variables = {
  "customerOneId": "gid://shopify/Customer/544365967",
  "customerTwoId": "gid://shopify/Customer/624407574"
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation CustomerMerge {
      customerMerge(customerOneId: "gid://shopify/Customer/544365967", customerTwoId: "gid://shopify/Customer/624407574") {
        resultingCustomerId
        job {
          id
          done
        }
        userErrors {
          code
          field
          message
        }
      }
    }`,
    "variables": {
        "customerOneId": "gid://shopify/Customer/544365967",
        "customerTwoId": "gid://shopify/Customer/624407574"
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation CustomerMerge {
  customerMerge(customerOneId: "gid://shopify/Customer/544365967", customerTwoId: "gid://shopify/Customer/624407574") {
    resultingCustomerId
    job {
      id
      done
    }
    userErrors {
      code
      field
      message
    }
  }
}' \
--variables \
'{
  "customerOneId": "gid://shopify/Customer/544365967",
  "customerTwoId": "gid://shopify/Customer/624407574"
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation CustomerMerge {
        customerMerge(customerOneId: "gid://shopify/Customer/544365967", customerTwoId: "gid://shopify/Customer/624407574") {
          resultingCustomerId
          job {
            id
            done
          }
          userErrors {
            code
            field
            message
          }
        }
      }
    `,
    variables: {
        "customerOneId": "gid://shopify/Customer/544365967",
        "customerTwoId": "gid://shopify/Customer/624407574"
    },
  }),
});

const { data } = await response.json();
console.log(data);

Response

{
  "customerMerge": {
    "resultingCustomerId": "gid://shopify/Customer/624407574",
    "job": {
      "id": "gid://shopify/Job/ab22429a-ea18-4dad-ac2c-5823288b1e59",
      "done": true
    },
    "userErrors": []
  }
}

customerMerge reference

Examples

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`#graphql

mutation CustomerMerge {

customerMerge(customerOneId: "gid://shopify/Customer/544365967", customerTwoId: "gid://shopify/Customer/624407574", overrideFields: {customerIdOfFirstNameToKeep: "gid://shopify/Customer/544365967", customerIdOfLastNameToKeep: "gid://shopify/Customer/624407574"}) {

resultingCustomerId

job {

done

}

userErrors {

code

field

message

}

}`,

{

variables: {

"customerOneId": "gid://shopify/Customer/544365967",

"customerTwoId": "gid://shopify/Customer/624407574",

"overrideFields": {

"customerIdOfFirstNameToKeep": "gid://shopify/Customer/544365967",

"customerIdOfLastNameToKeep": "gid://shopify/Customer/544365967"

}

);

const json = await response.json();

return json.data;

}

GQL

mutation CustomerMerge {
  customerMerge(customerOneId: "gid://shopify/Customer/544365967", customerTwoId: "gid://shopify/Customer/624407574", overrideFields: {customerIdOfFirstNameToKeep: "gid://shopify/Customer/544365967", customerIdOfLastNameToKeep: "gid://shopify/Customer/624407574"}) {
    resultingCustomerId
    job {
      id
      done
    }
    userErrors {
      code
      field
      message
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2026-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "mutation CustomerMerge { customerMerge(customerOneId: \"gid://shopify/Customer/544365967\", customerTwoId: \"gid://shopify/Customer/624407574\", overrideFields: {customerIdOfFirstNameToKeep: \"gid://shopify/Customer/544365967\", customerIdOfLastNameToKeep: \"gid://shopify/Customer/624407574\"}) { resultingCustomerId job { id done } userErrors { code field message } } }",
 "variables": {
    "customerOneId": "gid://shopify/Customer/544365967",
    "customerTwoId": "gid://shopify/Customer/624407574",
    "overrideFields": {
      "customerIdOfFirstNameToKeep": "gid://shopify/Customer/544365967",
      "customerIdOfLastNameToKeep": "gid://shopify/Customer/544365967"
    }
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  mutation CustomerMerge {
    customerMerge(customerOneId: "gid://shopify/Customer/544365967", customerTwoId: "gid://shopify/Customer/624407574", overrideFields: {customerIdOfFirstNameToKeep: "gid://shopify/Customer/544365967", customerIdOfLastNameToKeep: "gid://shopify/Customer/624407574"}) {
      resultingCustomerId
      job {
        id
        done
      }
      userErrors {
        code
        field
        message
      }
    }
  }`,
  {
    variables: {
        "customerOneId": "gid://shopify/Customer/544365967",
        "customerTwoId": "gid://shopify/Customer/624407574",
        "overrideFields": {
            "customerIdOfFirstNameToKeep": "gid://shopify/Customer/544365967",
            "customerIdOfLastNameToKeep": "gid://shopify/Customer/544365967"
        }
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation CustomerMerge {
      customerMerge(customerOneId: "gid://shopify/Customer/544365967", customerTwoId: "gid://shopify/Customer/624407574", overrideFields: {customerIdOfFirstNameToKeep: "gid://shopify/Customer/544365967", customerIdOfLastNameToKeep: "gid://shopify/Customer/624407574"}) {
        resultingCustomerId
        job {
          id
          done
        }
        userErrors {
          code
          field
          message
        }
      }
    }`,
    "variables": {
        "customerOneId": "gid://shopify/Customer/544365967",
        "customerTwoId": "gid://shopify/Customer/624407574",
        "overrideFields": {
            "customerIdOfFirstNameToKeep": "gid://shopify/Customer/544365967",
            "customerIdOfLastNameToKeep": "gid://shopify/Customer/544365967"
        }
    },
  },
});

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  mutation CustomerMerge {
    customerMerge(customerOneId: "gid://shopify/Customer/544365967", customerTwoId: "gid://shopify/Customer/624407574", overrideFields: {customerIdOfFirstNameToKeep: "gid://shopify/Customer/544365967", customerIdOfLastNameToKeep: "gid://shopify/Customer/624407574"}) {
      resultingCustomerId
      job {
        id
        done
      }
      userErrors {
        code
        field
        message
      }
    }
  }
QUERY

variables = {
  "customerOneId": "gid://shopify/Customer/544365967",
  "customerTwoId": "gid://shopify/Customer/624407574",
  "overrideFields": {
    "customerIdOfFirstNameToKeep": "gid://shopify/Customer/544365967",
    "customerIdOfLastNameToKeep": "gid://shopify/Customer/544365967"
  }
}

response = client.query(query: query, variables: variables)

Shopify CLI

shopify app execute \
--query \
'mutation CustomerMerge {
  customerMerge(customerOneId: "gid://shopify/Customer/544365967", customerTwoId: "gid://shopify/Customer/624407574", overrideFields: {customerIdOfFirstNameToKeep: "gid://shopify/Customer/544365967", customerIdOfLastNameToKeep: "gid://shopify/Customer/624407574"}) {
    resultingCustomerId
    job {
      id
      done
    }
    userErrors {
      code
      field
      message
    }
  }
}' \
--variables \
'{
  "customerOneId": "gid://shopify/Customer/544365967",
  "customerTwoId": "gid://shopify/Customer/624407574",
  "overrideFields": {
    "customerIdOfFirstNameToKeep": "gid://shopify/Customer/544365967",
    "customerIdOfLastNameToKeep": "gid://shopify/Customer/544365967"
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation CustomerMerge {
        customerMerge(customerOneId: "gid://shopify/Customer/544365967", customerTwoId: "gid://shopify/Customer/624407574", overrideFields: {customerIdOfFirstNameToKeep: "gid://shopify/Customer/544365967", customerIdOfLastNameToKeep: "gid://shopify/Customer/624407574"}) {
          resultingCustomerId
          job {
            id
            done
          }
          userErrors {
            code
            field
            message
          }
        }
      }
    `,
    variables: {
        "customerOneId": "gid://shopify/Customer/544365967",
        "customerTwoId": "gid://shopify/Customer/624407574",
        "overrideFields": {
            "customerIdOfFirstNameToKeep": "gid://shopify/Customer/544365967",
            "customerIdOfLastNameToKeep": "gid://shopify/Customer/544365967"
        }
    },
  }),
});

const { data } = await response.json();
console.log(data);

Input variables

JSON

{

"customerOneId": "gid://shopify/Customer/544365967",

"customerTwoId": "gid://shopify/Customer/624407574",

"overrideFields": {

"customerIdOfFirstNameToKeep": "gid://shopify/Customer/544365967",

"customerIdOfLastNameToKeep": "gid://shopify/Customer/544365967"

}

Response

JSON

{

"customerMerge": {

"resultingCustomerId": "gid://shopify/Customer/624407574",

"job": {

"id": "gid://shopify/Job/ab22429a-ea18-4dad-ac2c-5823288b1e59",

"done": true

"userErrors": []

}