Choose a version:

customerUpdate

mutation

Requires write_customers access scope.

Updates a Customer's attributes including personal information and tax exemptions.

Apps using protected customer data must meet Shopify's protected customer data requirements.

Anchor to Arguments

Arguments

Anchor to inputinput

•CustomerInput!

required

Provides updated fields for the customer. To set marketing consent, use the customerEmailMarketingConsentUpdate or customerSmsMarketingConsentUpdate mutations instead.

Show input fields

Was this section helpful?

Anchor to CustomerUpdatePayload returnsCustomerUpdatePayload returns

Anchor to customercustomer •Customer: The updated customer.

Show fields
Anchor to userErrorsuserErrors •[UserError!]! non-null: The list of errors that occurred from executing the mutation.

Show fields

Was this section helpful?

Examples

Create a new metafield and update another on an existing customer

Description

Create a new metafield `my_field.nickname` and update an existing metafield `my_field.pronouns` on a specific customer. Alternatively, refer to the [metafieldsSet](https://shopify.dev/api/admin-graphql/latest/mutations/metafieldsset) mutation to create and/or update metafields on customer resources.

Query

mutation updateCustomerMetafields($input: CustomerInput!) {
  customerUpdate(input: $input) {
    customer {
      id
      metafields(first: 3) {
        edges {
          node {
            id
            namespace
            key
            value
          }
        }
      }
    }
    userErrors {
      message
      field
    }
  }
}

Variables

{
  "input": {
    "metafields": [
      {
        "namespace": "my_field",
        "key": "nickname",
        "type": "single_line_text_field",
        "value": "rob"
      },
      {
        "id": "gid://shopify/Metafield/1069230189",
        "value": "they/them"
      }
    ],
    "id": "gid://shopify/Customer/1018520244"
  }
}

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 updateCustomerMetafields($input: CustomerInput!) { customerUpdate(input: $input) { customer { id metafields(first: 3) { edges { node { id namespace key value } } } } userErrors { message field } } }",
 "variables": {
    "input": {
      "metafields": [
        {
          "namespace": "my_field",
          "key": "nickname",
          "type": "single_line_text_field",
          "value": "rob"
        },
        {
          "id": "gid://shopify/Metafield/1069230189",
          "value": "they/them"
        }
      ],
      "id": "gid://shopify/Customer/1018520244"
    }
  }
}'

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 updateCustomerMetafields($input: CustomerInput!) {
    customerUpdate(input: $input) {
      customer {
        id
        metafields(first: 3) {
          edges {
            node {
              id
              namespace
              key
              value
            }
          }
        }
      }
      userErrors {
        message
        field
      }
    }
  }`,
  {
    variables: {
        "input": {
            "metafields": [
                {
                    "namespace": "my_field",
                    "key": "nickname",
                    "type": "single_line_text_field",
                    "value": "rob"
                },
                {
                    "id": "gid://shopify/Metafield/1069230189",
                    "value": "they/them"
                }
            ],
            "id": "gid://shopify/Customer/1018520244"
        }
    },
  },
  );
  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 updateCustomerMetafields($input: CustomerInput!) {
    customerUpdate(input: $input) {
      customer {
        id
        metafields(first: 3) {
          edges {
            node {
              id
              namespace
              key
              value
            }
          }
        }
      }
      userErrors {
        message
        field
      }
    }
  }
QUERY

variables = {
  "input": {
    "metafields": [
      {
        "namespace": "my_field",
        "key": "nickname",
        "type": "single_line_text_field",
        "value": "rob"
      },
      {
        "id": "gid://shopify/Metafield/1069230189",
        "value": "they/them"
      }
    ],
    "id": "gid://shopify/Customer/1018520244"
  }
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation updateCustomerMetafields($input: CustomerInput!) {
      customerUpdate(input: $input) {
        customer {
          id
          metafields(first: 3) {
            edges {
              node {
                id
                namespace
                key
                value
              }
            }
          }
        }
        userErrors {
          message
          field
        }
      }
    }`,
    "variables": {
        "input": {
            "metafields": [
                {
                    "namespace": "my_field",
                    "key": "nickname",
                    "type": "single_line_text_field",
                    "value": "rob"
                },
                {
                    "id": "gid://shopify/Metafield/1069230189",
                    "value": "they/them"
                }
            ],
            "id": "gid://shopify/Customer/1018520244"
        }
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation updateCustomerMetafields($input: CustomerInput!) {
  customerUpdate(input: $input) {
    customer {
      id
      metafields(first: 3) {
        edges {
          node {
            id
            namespace
            key
            value
          }
        }
      }
    }
    userErrors {
      message
      field
    }
  }
}' \
--variables \
'{
  "input": {
    "metafields": [
      {
        "namespace": "my_field",
        "key": "nickname",
        "type": "single_line_text_field",
        "value": "rob"
      },
      {
        "id": "gid://shopify/Metafield/1069230189",
        "value": "they/them"
      }
    ],
    "id": "gid://shopify/Customer/1018520244"
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation updateCustomerMetafields($input: CustomerInput!) {
        customerUpdate(input: $input) {
          customer {
            id
            metafields(first: 3) {
              edges {
                node {
                  id
                  namespace
                  key
                  value
                }
              }
            }
          }
          userErrors {
            message
            field
          }
        }
      }
    `,
    variables: {
        "input": {
            "metafields": [
                {
                    "namespace": "my_field",
                    "key": "nickname",
                    "type": "single_line_text_field",
                    "value": "rob"
                },
                {
                    "id": "gid://shopify/Metafield/1069230189",
                    "value": "they/them"
                }
            ],
            "id": "gid://shopify/Customer/1018520244"
        }
    },
  }),
});

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

Response

{
  "customerUpdate": {
    "customer": {
      "id": "gid://shopify/Customer/1018520244",
      "metafields": {
        "edges": [
          {
            "node": {
              "id": "gid://shopify/Metafield/1069230189",
              "namespace": "my_field",
              "key": "pronouns",
              "value": "they/them"
            }
          },
          {
            "node": {
              "id": "gid://shopify/Metafield/1069230190",
              "namespace": "my_field",
              "key": "nickname",
              "value": "rob"
            }
          }
        ]
      }
    },
    "userErrors": []
  }
}

Creates a new address for a customer

Query

mutation CustomerAddressCreate($customerId: ID!, $addresses: [MailingAddressInput!]) {
  customerUpdate(input: {id: $customerId, addresses: $addresses}) {
    customer {
      id
      addressesV2(first: 10) {
        edges {
          node {
            id
            address1
            city
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Variables

{
  "customerId": "gid://shopify/Customer/1018520244",
  "addresses": [
    {
      "address1": "123 New Address",
      "city": "New City"
    }
  ]
}

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 CustomerAddressCreate($customerId: ID!, $addresses: [MailingAddressInput!]) { customerUpdate(input: {id: $customerId, addresses: $addresses}) { customer { id addressesV2(first: 10) { edges { node { id address1 city } } } } userErrors { field message } } }",
 "variables": {
    "customerId": "gid://shopify/Customer/1018520244",
    "addresses": [
      {
        "address1": "123 New Address",
        "city": "New City"
      }
    ]
  }
}'

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 CustomerAddressCreate($customerId: ID!, $addresses: [MailingAddressInput!]) {
    customerUpdate(input: {id: $customerId, addresses: $addresses}) {
      customer {
        id
        addressesV2(first: 10) {
          edges {
            node {
              id
              address1
              city
            }
          }
        }
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "customerId": "gid://shopify/Customer/1018520244",
        "addresses": [
            {
                "address1": "123 New Address",
                "city": "New City"
            }
        ]
    },
  },
  );
  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 CustomerAddressCreate($customerId: ID!, $addresses: [MailingAddressInput!]) {
    customerUpdate(input: {id: $customerId, addresses: $addresses}) {
      customer {
        id
        addressesV2(first: 10) {
          edges {
            node {
              id
              address1
              city
            }
          }
        }
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "customerId": "gid://shopify/Customer/1018520244",
  "addresses": [
    {
      "address1": "123 New Address",
      "city": "New City"
    }
  ]
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation CustomerAddressCreate($customerId: ID!, $addresses: [MailingAddressInput!]) {
      customerUpdate(input: {id: $customerId, addresses: $addresses}) {
        customer {
          id
          addressesV2(first: 10) {
            edges {
              node {
                id
                address1
                city
              }
            }
          }
        }
        userErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "customerId": "gid://shopify/Customer/1018520244",
        "addresses": [
            {
                "address1": "123 New Address",
                "city": "New City"
            }
        ]
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation CustomerAddressCreate($customerId: ID!, $addresses: [MailingAddressInput!]) {
  customerUpdate(input: {id: $customerId, addresses: $addresses}) {
    customer {
      id
      addressesV2(first: 10) {
        edges {
          node {
            id
            address1
            city
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}' \
--variables \
'{
  "customerId": "gid://shopify/Customer/1018520244",
  "addresses": [
    {
      "address1": "123 New Address",
      "city": "New City"
    }
  ]
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation CustomerAddressCreate($customerId: ID!, $addresses: [MailingAddressInput!]) {
        customerUpdate(input: {id: $customerId, addresses: $addresses}) {
          customer {
            id
            addressesV2(first: 10) {
              edges {
                node {
                  id
                  address1
                  city
                }
              }
            }
          }
          userErrors {
            field
            message
          }
        }
      }
    `,
    variables: {
        "customerId": "gid://shopify/Customer/1018520244",
        "addresses": [
            {
                "address1": "123 New Address",
                "city": "New City"
            }
        ]
    },
  }),
});

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

Response

{
  "customerUpdate": {
    "customer": {
      "id": "gid://shopify/Customer/1018520244",
      "addressesV2": {
        "edges": [
          {
            "node": {
              "id": "gid://shopify/MailingAddress/1053318591?model_name=CustomerAddress",
              "address1": "123 New Address",
              "city": "New City"
            }
          }
        ]
      }
    },
    "userErrors": []
  }
}

Performs bulk operations for multiple customer addresses

Query

mutation CustomerAddressSet($customerId: ID!, $addresses: [MailingAddressInput!]) {
  customerUpdate(input: {id: $customerId, addresses: $addresses}) {
    customer {
      id
      addressesV2(first: 10) {
        edges {
          node {
            id
            address1
            city
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Variables

{
  "customerId": "gid://shopify/Customer/1018520244",
  "addresses": [
    {
      "address1": "123 Main St",
      "city": "Metropolis"
    },
    {
      "address1": "456 Elm St",
      "city": "Gotham"
    }
  ]
}

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 CustomerAddressSet($customerId: ID!, $addresses: [MailingAddressInput!]) { customerUpdate(input: {id: $customerId, addresses: $addresses}) { customer { id addressesV2(first: 10) { edges { node { id address1 city } } } } userErrors { field message } } }",
 "variables": {
    "customerId": "gid://shopify/Customer/1018520244",
    "addresses": [
      {
        "address1": "123 Main St",
        "city": "Metropolis"
      },
      {
        "address1": "456 Elm St",
        "city": "Gotham"
      }
    ]
  }
}'

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 CustomerAddressSet($customerId: ID!, $addresses: [MailingAddressInput!]) {
    customerUpdate(input: {id: $customerId, addresses: $addresses}) {
      customer {
        id
        addressesV2(first: 10) {
          edges {
            node {
              id
              address1
              city
            }
          }
        }
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "customerId": "gid://shopify/Customer/1018520244",
        "addresses": [
            {
                "address1": "123 Main St",
                "city": "Metropolis"
            },
            {
                "address1": "456 Elm St",
                "city": "Gotham"
            }
        ]
    },
  },
  );
  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 CustomerAddressSet($customerId: ID!, $addresses: [MailingAddressInput!]) {
    customerUpdate(input: {id: $customerId, addresses: $addresses}) {
      customer {
        id
        addressesV2(first: 10) {
          edges {
            node {
              id
              address1
              city
            }
          }
        }
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "customerId": "gid://shopify/Customer/1018520244",
  "addresses": [
    {
      "address1": "123 Main St",
      "city": "Metropolis"
    },
    {
      "address1": "456 Elm St",
      "city": "Gotham"
    }
  ]
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation CustomerAddressSet($customerId: ID!, $addresses: [MailingAddressInput!]) {
      customerUpdate(input: {id: $customerId, addresses: $addresses}) {
        customer {
          id
          addressesV2(first: 10) {
            edges {
              node {
                id
                address1
                city
              }
            }
          }
        }
        userErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "customerId": "gid://shopify/Customer/1018520244",
        "addresses": [
            {
                "address1": "123 Main St",
                "city": "Metropolis"
            },
            {
                "address1": "456 Elm St",
                "city": "Gotham"
            }
        ]
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation CustomerAddressSet($customerId: ID!, $addresses: [MailingAddressInput!]) {
  customerUpdate(input: {id: $customerId, addresses: $addresses}) {
    customer {
      id
      addressesV2(first: 10) {
        edges {
          node {
            id
            address1
            city
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}' \
--variables \
'{
  "customerId": "gid://shopify/Customer/1018520244",
  "addresses": [
    {
      "address1": "123 Main St",
      "city": "Metropolis"
    },
    {
      "address1": "456 Elm St",
      "city": "Gotham"
    }
  ]
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation CustomerAddressSet($customerId: ID!, $addresses: [MailingAddressInput!]) {
        customerUpdate(input: {id: $customerId, addresses: $addresses}) {
          customer {
            id
            addressesV2(first: 10) {
              edges {
                node {
                  id
                  address1
                  city
                }
              }
            }
          }
          userErrors {
            field
            message
          }
        }
      }
    `,
    variables: {
        "customerId": "gid://shopify/Customer/1018520244",
        "addresses": [
            {
                "address1": "123 Main St",
                "city": "Metropolis"
            },
            {
                "address1": "456 Elm St",
                "city": "Gotham"
            }
        ]
    },
  }),
});

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

Response

{
  "customerUpdate": {
    "customer": {
      "id": "gid://shopify/Customer/1018520244",
      "addressesV2": {
        "edges": [
          {
            "node": {
              "id": "gid://shopify/MailingAddress/1053318585?model_name=CustomerAddress",
              "address1": "123 Main St",
              "city": "Metropolis"
            }
          },
          {
            "node": {
              "id": "gid://shopify/MailingAddress/1053318586?model_name=CustomerAddress",
              "address1": "456 Elm St",
              "city": "Gotham"
            }
          }
        ]
      }
    },
    "userErrors": []
  }
}

Update a customer with an ID that doesn't exist

Description

Trying to update a customer that doesn't exist will return an error

Query

mutation customerUpdate($input: CustomerInput!) {
  customerUpdate(input: $input) {
    userErrors {
      field
      message
    }
    customer {
      id
      firstName
    }
  }
}

Variables

{
  "input": {
    "id": "gid://shopify/Customer/1",
    "firstName": "Tobi"
  }
}

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 customerUpdate($input: CustomerInput!) { customerUpdate(input: $input) { userErrors { field message } customer { id firstName } } }",
 "variables": {
    "input": {
      "id": "gid://shopify/Customer/1",
      "firstName": "Tobi"
    }
  }
}'

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 customerUpdate($input: CustomerInput!) {
    customerUpdate(input: $input) {
      userErrors {
        field
        message
      }
      customer {
        id
        firstName
      }
    }
  }`,
  {
    variables: {
        "input": {
            "id": "gid://shopify/Customer/1",
            "firstName": "Tobi"
        }
    },
  },
  );
  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 customerUpdate($input: CustomerInput!) {
    customerUpdate(input: $input) {
      userErrors {
        field
        message
      }
      customer {
        id
        firstName
      }
    }
  }
QUERY

variables = {
  "input": {
    "id": "gid://shopify/Customer/1",
    "firstName": "Tobi"
  }
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation customerUpdate($input: CustomerInput!) {
      customerUpdate(input: $input) {
        userErrors {
          field
          message
        }
        customer {
          id
          firstName
        }
      }
    }`,
    "variables": {
        "input": {
            "id": "gid://shopify/Customer/1",
            "firstName": "Tobi"
        }
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation customerUpdate($input: CustomerInput!) {
  customerUpdate(input: $input) {
    userErrors {
      field
      message
    }
    customer {
      id
      firstName
    }
  }
}' \
--variables \
'{
  "input": {
    "id": "gid://shopify/Customer/1",
    "firstName": "Tobi"
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation customerUpdate($input: CustomerInput!) {
        customerUpdate(input: $input) {
          userErrors {
            field
            message
          }
          customer {
            id
            firstName
          }
        }
      }
    `,
    variables: {
        "input": {
            "id": "gid://shopify/Customer/1",
            "firstName": "Tobi"
        }
    },
  }),
});

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

Response

{
  "customerUpdate": {
    "userErrors": [
      {
        "field": [
          "id"
        ],
        "message": "Customer does not exist"
      }
    ],
    "customer": null
  }
}

Updates a customer's first and last name

Description

Update a customer's first and last name

Query

mutation customerUpdate($input: CustomerInput!) {
  customerUpdate(input: $input) {
    userErrors {
      field
      message
    }
    customer {
      id
      firstName
      lastName
    }
  }
}

Variables

{
  "input": {
    "id": "gid://shopify/Customer/1018520244",
    "firstName": "Tobi",
    "lastName": "Lutke"
  }
}

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 customerUpdate($input: CustomerInput!) { customerUpdate(input: $input) { userErrors { field message } customer { id firstName lastName } } }",
 "variables": {
    "input": {
      "id": "gid://shopify/Customer/1018520244",
      "firstName": "Tobi",
      "lastName": "Lutke"
    }
  }
}'

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 customerUpdate($input: CustomerInput!) {
    customerUpdate(input: $input) {
      userErrors {
        field
        message
      }
      customer {
        id
        firstName
        lastName
      }
    }
  }`,
  {
    variables: {
        "input": {
            "id": "gid://shopify/Customer/1018520244",
            "firstName": "Tobi",
            "lastName": "Lutke"
        }
    },
  },
  );
  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 customerUpdate($input: CustomerInput!) {
    customerUpdate(input: $input) {
      userErrors {
        field
        message
      }
      customer {
        id
        firstName
        lastName
      }
    }
  }
QUERY

variables = {
  "input": {
    "id": "gid://shopify/Customer/1018520244",
    "firstName": "Tobi",
    "lastName": "Lutke"
  }
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation customerUpdate($input: CustomerInput!) {
      customerUpdate(input: $input) {
        userErrors {
          field
          message
        }
        customer {
          id
          firstName
          lastName
        }
      }
    }`,
    "variables": {
        "input": {
            "id": "gid://shopify/Customer/1018520244",
            "firstName": "Tobi",
            "lastName": "Lutke"
        }
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation customerUpdate($input: CustomerInput!) {
  customerUpdate(input: $input) {
    userErrors {
      field
      message
    }
    customer {
      id
      firstName
      lastName
    }
  }
}' \
--variables \
'{
  "input": {
    "id": "gid://shopify/Customer/1018520244",
    "firstName": "Tobi",
    "lastName": "Lutke"
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation customerUpdate($input: CustomerInput!) {
        customerUpdate(input: $input) {
          userErrors {
            field
            message
          }
          customer {
            id
            firstName
            lastName
          }
        }
      }
    `,
    variables: {
        "input": {
            "id": "gid://shopify/Customer/1018520244",
            "firstName": "Tobi",
            "lastName": "Lutke"
        }
    },
  }),
});

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

Response

{
  "customerUpdate": {
    "userErrors": [],
    "customer": {
      "id": "gid://shopify/Customer/1018520244",
      "firstName": "Tobi",
      "lastName": "Lutke"
    }
  }
}

Updates an existing customer address

Query

mutation CustomerAddressUpdate($customerId: ID!, $addresses: [MailingAddressInput!]) {
  customerUpdate(input: {id: $customerId, addresses: $addresses}) {
    customer {
      id
      addressesV2(first: 10) {
        edges {
          node {
            id
            address1
            city
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Variables

{
  "customerId": "gid://shopify/Customer/1018520244",
  "addresses": [
    {
      "address1": "123 New Street",
      "city": "New City"
    }
  ]
}

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 CustomerAddressUpdate($customerId: ID!, $addresses: [MailingAddressInput!]) { customerUpdate(input: {id: $customerId, addresses: $addresses}) { customer { id addressesV2(first: 10) { edges { node { id address1 city } } } } userErrors { field message } } }",
 "variables": {
    "customerId": "gid://shopify/Customer/1018520244",
    "addresses": [
      {
        "address1": "123 New Street",
        "city": "New City"
      }
    ]
  }
}'

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 CustomerAddressUpdate($customerId: ID!, $addresses: [MailingAddressInput!]) {
    customerUpdate(input: {id: $customerId, addresses: $addresses}) {
      customer {
        id
        addressesV2(first: 10) {
          edges {
            node {
              id
              address1
              city
            }
          }
        }
      }
      userErrors {
        field
        message
      }
    }
  }`,
  {
    variables: {
        "customerId": "gid://shopify/Customer/1018520244",
        "addresses": [
            {
                "address1": "123 New Street",
                "city": "New City"
            }
        ]
    },
  },
  );
  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 CustomerAddressUpdate($customerId: ID!, $addresses: [MailingAddressInput!]) {
    customerUpdate(input: {id: $customerId, addresses: $addresses}) {
      customer {
        id
        addressesV2(first: 10) {
          edges {
            node {
              id
              address1
              city
            }
          }
        }
      }
      userErrors {
        field
        message
      }
    }
  }
QUERY

variables = {
  "customerId": "gid://shopify/Customer/1018520244",
  "addresses": [
    {
      "address1": "123 New Street",
      "city": "New City"
    }
  ]
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `mutation CustomerAddressUpdate($customerId: ID!, $addresses: [MailingAddressInput!]) {
      customerUpdate(input: {id: $customerId, addresses: $addresses}) {
        customer {
          id
          addressesV2(first: 10) {
            edges {
              node {
                id
                address1
                city
              }
            }
          }
        }
        userErrors {
          field
          message
        }
      }
    }`,
    "variables": {
        "customerId": "gid://shopify/Customer/1018520244",
        "addresses": [
            {
                "address1": "123 New Street",
                "city": "New City"
            }
        ]
    },
  },
});

Shopify CLI

shopify app execute \
--query \
'mutation CustomerAddressUpdate($customerId: ID!, $addresses: [MailingAddressInput!]) {
  customerUpdate(input: {id: $customerId, addresses: $addresses}) {
    customer {
      id
      addressesV2(first: 10) {
        edges {
          node {
            id
            address1
            city
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}' \
--variables \
'{
  "customerId": "gid://shopify/Customer/1018520244",
  "addresses": [
    {
      "address1": "123 New Street",
      "city": "New City"
    }
  ]
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation CustomerAddressUpdate($customerId: ID!, $addresses: [MailingAddressInput!]) {
        customerUpdate(input: {id: $customerId, addresses: $addresses}) {
          customer {
            id
            addressesV2(first: 10) {
              edges {
                node {
                  id
                  address1
                  city
                }
              }
            }
          }
          userErrors {
            field
            message
          }
        }
      }
    `,
    variables: {
        "customerId": "gid://shopify/Customer/1018520244",
        "addresses": [
            {
                "address1": "123 New Street",
                "city": "New City"
            }
        ]
    },
  }),
});

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

Response

{
  "customerUpdate": {
    "customer": {
      "id": "gid://shopify/Customer/1018520244",
      "addressesV2": {
        "edges": [
          {
            "node": {
              "id": "gid://shopify/MailingAddress/1053318595?model_name=CustomerAddress",
              "address1": "123 New Street",
              "city": "New City"
            }
          }
        ]
      }
    },
    "userErrors": []
  }
}

customerUpdate 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 updateCustomerMetafields($input: CustomerInput!) {

customerUpdate(input: $input) {

customer {

metafields(first: 3) {

edges {

node {

namespace

key

value

}

userErrors {

message

field

}

}`,

{

variables: {

"input": {

"metafields": [

{

"namespace": "my_field",

"key": "nickname",

"type": "single_line_text_field",

"value": "rob"

{

"id": "gid://shopify/Metafield/1069230189",

"value": "they/them"

}

"id": "gid://shopify/Customer/1018520244"

}

);

const json = await response.json();

return json.data;

}

GQL

mutation updateCustomerMetafields($input: CustomerInput!) {
  customerUpdate(input: $input) {
    customer {
      id
      metafields(first: 3) {
        edges {
          node {
            id
            namespace
            key
            value
          }
        }
      }
    }
    userErrors {
      message
      field
    }
  }
}

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 updateCustomerMetafields($input: CustomerInput!) { customerUpdate(input: $input) { customer { id metafields(first: 3) { edges { node { id namespace key value } } } } userErrors { message field } } }",
 "variables": {
    "input": {
      "metafields": [
        {
          "namespace": "my_field",
          "key": "nickname",
          "type": "single_line_text_field",
          "value": "rob"
        },
        {
          "id": "gid://shopify/Metafield/1069230189",
          "value": "they/them"
        }
      ],
      "id": "gid://shopify/Customer/1018520244"
    }
  }
}'

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 updateCustomerMetafields($input: CustomerInput!) {
    customerUpdate(input: $input) {
      customer {
        id
        metafields(first: 3) {
          edges {
            node {
              id
              namespace
              key
              value
            }
          }
        }
      }
      userErrors {
        message
        field
      }
    }
  }`,
  {
    variables: {
        "input": {
            "metafields": [
                {
                    "namespace": "my_field",
                    "key": "nickname",
                    "type": "single_line_text_field",
                    "value": "rob"
                },
                {
                    "id": "gid://shopify/Metafield/1069230189",
                    "value": "they/them"
                }
            ],
            "id": "gid://shopify/Customer/1018520244"
        }
    },
  },
  );
  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 updateCustomerMetafields($input: CustomerInput!) {
      customerUpdate(input: $input) {
        customer {
          id
          metafields(first: 3) {
            edges {
              node {
                id
                namespace
                key
                value
              }
            }
          }
        }
        userErrors {
          message
          field
        }
      }
    }`,
    "variables": {
        "input": {
            "metafields": [
                {
                    "namespace": "my_field",
                    "key": "nickname",
                    "type": "single_line_text_field",
                    "value": "rob"
                },
                {
                    "id": "gid://shopify/Metafield/1069230189",
                    "value": "they/them"
                }
            ],
            "id": "gid://shopify/Customer/1018520244"
        }
    },
  },
});

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 updateCustomerMetafields($input: CustomerInput!) {
    customerUpdate(input: $input) {
      customer {
        id
        metafields(first: 3) {
          edges {
            node {
              id
              namespace
              key
              value
            }
          }
        }
      }
      userErrors {
        message
        field
      }
    }
  }
QUERY

variables = {
  "input": {
    "metafields": [
      {
        "namespace": "my_field",
        "key": "nickname",
        "type": "single_line_text_field",
        "value": "rob"
      },
      {
        "id": "gid://shopify/Metafield/1069230189",
        "value": "they/them"
      }
    ],
    "id": "gid://shopify/Customer/1018520244"
  }
}

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

Shopify CLI

shopify app execute \
--query \
'mutation updateCustomerMetafields($input: CustomerInput!) {
  customerUpdate(input: $input) {
    customer {
      id
      metafields(first: 3) {
        edges {
          node {
            id
            namespace
            key
            value
          }
        }
      }
    }
    userErrors {
      message
      field
    }
  }
}' \
--variables \
'{
  "input": {
    "metafields": [
      {
        "namespace": "my_field",
        "key": "nickname",
        "type": "single_line_text_field",
        "value": "rob"
      },
      {
        "id": "gid://shopify/Metafield/1069230189",
        "value": "they/them"
      }
    ],
    "id": "gid://shopify/Customer/1018520244"
  }
}'

Direct API Access

const response = await fetch('shopify:admin/api/2026-04/graphql.json', {
  method: 'POST',
  body: JSON.stringify({
    query: `
      mutation updateCustomerMetafields($input: CustomerInput!) {
        customerUpdate(input: $input) {
          customer {
            id
            metafields(first: 3) {
              edges {
                node {
                  id
                  namespace
                  key
                  value
                }
              }
            }
          }
          userErrors {
            message
            field
          }
        }
      }
    `,
    variables: {
        "input": {
            "metafields": [
                {
                    "namespace": "my_field",
                    "key": "nickname",
                    "type": "single_line_text_field",
                    "value": "rob"
                },
                {
                    "id": "gid://shopify/Metafield/1069230189",
                    "value": "they/them"
                }
            ],
            "id": "gid://shopify/Customer/1018520244"
        }
    },
  }),
});

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

Input variables

JSON

{

"input": {

"metafields": [

{

"namespace": "my_field",

"key": "nickname",

"type": "single_line_text_field",

"value": "rob"

{

"id": "gid://shopify/Metafield/1069230189",

"value": "they/them"

}

"id": "gid://shopify/Customer/1018520244"

}

Response

JSON

{

"customerUpdate": {

"customer": {

"id": "gid://shopify/Customer/1018520244",

"metafields": {

"edges": [

{

"node": {

"id": "gid://shopify/Metafield/1069230189",

"namespace": "my_field",

"key": "pronouns",

"value": "they/them"

}

{

"node": {

"id": "gid://shopify/Metafield/1069230190",

"namespace": "my_field",

"key": "nickname",

"value": "rob"

}

]

}

"userErrors": []

}