Choose a version:

customer

query

Returns a Customer resource by ID.

Anchor to Arguments

Arguments

Anchor to idid •ID! required: The ID of the Customer to return.

Was this section helpful?

Anchor to Possible returnsPossible returns

Anchor to CustomerCustomer •Customer: Information about a customer of the shop, such as the customer's contact details, purchase history, and marketing preferences.

Tracks the customer's total spending through the amountSpent field and provides access to associated data such as payment methods and subscription contracts.

Caution
Only use this data if it's required for your app's functionality. Shopify will restrict access to scopes for apps that don't have a legitimate use for the associated data.

Was this section helpful?

Examples

Get a customer by ID

Description

The following query retrieves the customer with the associated ID. It returns the customer fields specified in the query.

Query

query {
  customer(id: "gid://shopify/Customer/544365967") {
    id
    firstName
    lastName
    email
    phone
    numberOfOrders
    amountSpent {
      amount
      currencyCode
    }
    createdAt
    updatedAt
    note
    verifiedEmail
    validEmailAddress
    tags
    lifetimeDuration
    defaultAddress {
      formattedArea
      address1
    }
    addresses {
      address1
    }
    image {
      src
    }
    canDelete
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query { customer(id: \"gid://shopify/Customer/544365967\") { id firstName lastName email phone numberOfOrders amountSpent { amount currencyCode } createdAt updatedAt note verifiedEmail validEmailAddress tags lifetimeDuration defaultAddress { formattedArea address1 } addresses { address1 } image { src } canDelete } }"
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query {
    customer(id: "gid://shopify/Customer/544365967") {
      id
      firstName
      lastName
      email
      phone
      numberOfOrders
      amountSpent {
        amount
        currencyCode
      }
      createdAt
      updatedAt
      note
      verifiedEmail
      validEmailAddress
      tags
      lifetimeDuration
      defaultAddress {
        formattedArea
        address1
      }
      addresses {
        address1
      }
      image {
        src
      }
      canDelete
    }
  }`,
  );
  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
  query {
    customer(id: "gid://shopify/Customer/544365967") {
      id
      firstName
      lastName
      email
      phone
      numberOfOrders
      amountSpent {
        amount
        currencyCode
      }
      createdAt
      updatedAt
      note
      verifiedEmail
      validEmailAddress
      tags
      lifetimeDuration
      defaultAddress {
        formattedArea
        address1
      }
      addresses {
        address1
      }
      image {
        src
      }
      canDelete
    }
  }
QUERY

response = client.query(query: query)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query {
    customer(id: "gid://shopify/Customer/544365967") {
      id
      firstName
      lastName
      email
      phone
      numberOfOrders
      amountSpent {
        amount
        currencyCode
      }
      createdAt
      updatedAt
      note
      verifiedEmail
      validEmailAddress
      tags
      lifetimeDuration
      defaultAddress {
        formattedArea
        address1
      }
      addresses {
        address1
      }
      image {
        src
      }
      canDelete
    }
  }`,
});

Response

{
  "customer": {
    "id": "gid://shopify/Customer/544365967",
    "firstName": "Bob",
    "lastName": "Bobsen",
    "email": "bob@example.com",
    "phone": "+13125551212",
    "numberOfOrders": "25",
    "amountSpent": {
      "amount": "8305.6",
      "currencyCode": "USD"
    },
    "createdAt": "2005-06-15T15:57:11Z",
    "updatedAt": "2005-06-16T15:57:11Z",
    "note": null,
    "verifiedEmail": true,
    "validEmailAddress": true,
    "tags": [
      "Bob",
      "Canadian",
      "Léon",
      "Noël"
    ],
    "lifetimeDuration": "almost 20 years",
    "defaultAddress": {
      "formattedArea": "Ottawa ON, Canada",
      "address1": "123 Amoebobacterieae St"
    },
    "addresses": [
      {
        "address1": "123 Amoebobacterieae St"
      }
    ],
    "image": {
      "src": "https://cdn.shopify.com/proxy/d02a582792c73c48b4b62a95f42bcbf6eff91c5d232efb2057ca4c41005e4728/www.gravatar.com/avatar/4b9bb80620f03eb3719e0a061c14283d.jpg?s=2048&d=https%3A%2F%2Fcdn.shopify.com%2Fshopifycloud%2Fshopify%2Fassets%2Fadmin%2Fcustomers%2Fpolaris%2Favatar-2-a0ee6e3fb3ae515b66b68388b265e5bd1e90646c4c72d59170518f45351e668b.png"
    },
    "canDelete": false
  }
}

Get a customer's name, email, and default address

Description

The following query retrieves the customer with the associated ID. It returns the customer's name, email and default address specified by the fields in the query.

Query

query {
  customer(id: "gid://shopify/Customer/544365967") {
    email
    firstName
    lastName
    defaultAddress {
      address1
      city
      province
      zip
      country
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query { customer(id: \"gid://shopify/Customer/544365967\") { email firstName lastName defaultAddress { address1 city province zip country } } }"
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query {
    customer(id: "gid://shopify/Customer/544365967") {
      email
      firstName
      lastName
      defaultAddress {
        address1
        city
        province
        zip
        country
      }
    }
  }`,
  );
  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
  query {
    customer(id: "gid://shopify/Customer/544365967") {
      email
      firstName
      lastName
      defaultAddress {
        address1
        city
        province
        zip
        country
      }
    }
  }
QUERY

response = client.query(query: query)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query {
    customer(id: "gid://shopify/Customer/544365967") {
      email
      firstName
      lastName
      defaultAddress {
        address1
        city
        province
        zip
        country
      }
    }
  }`,
});

Response

{
  "customer": {
    "email": "bob@example.com",
    "firstName": "Bob",
    "lastName": "Bobsen",
    "defaultAddress": {
      "address1": "123 Amoebobacterieae St",
      "city": "Ottawa",
      "province": "Ontario",
      "zip": "K2P0V6",
      "country": "Canada"
    }
  }
}

Get all a customer's fields and connections

Description

The following query retrieves the customer with the associated ID. It returns all of the available fields and connections specified in the query.

Query

query {
  customer(id: "gid://shopify/Customer/544365967") {
    addresses(first: 5) {
      address1
    }
    canDelete
    createdAt
    defaultAddress {
      address1
    }
    displayName
    email
    events(first: 5) {
      edges {
        node {
          message
        }
      }
    }
    firstName
    id
    image {
      id
    }
    lastName
    legacyResourceId
    lifetimeDuration
    mergeable {
      isMergeable
      reason
    }
    metafield(key: "app_key", namespace: "affiliates") {
      description
    }
    metafields(first: 5) {
      edges {
        node {
          id
        }
      }
    }
    note
    orders(first: 5) {
      edges {
        node {
          id
        }
      }
    }
    numberOfOrders
    phone
    state
    tags
    taxExempt
    amountSpent {
      amount
    }
    updatedAt
    validEmailAddress
    verifiedEmail
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query { customer(id: \"gid://shopify/Customer/544365967\") { addresses(first: 5) { address1 } canDelete createdAt defaultAddress { address1 } displayName email events(first: 5) { edges { node { message } } } firstName id image { id } lastName legacyResourceId lifetimeDuration mergeable { isMergeable reason } metafield(key: \"app_key\", namespace: \"affiliates\") { description } metafields(first: 5) { edges { node { id } } } note orders(first: 5) { edges { node { id } } } numberOfOrders phone state tags taxExempt amountSpent { amount } updatedAt validEmailAddress verifiedEmail } }"
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query {
    customer(id: "gid://shopify/Customer/544365967") {
      addresses(first: 5) {
        address1
      }
      canDelete
      createdAt
      defaultAddress {
        address1
      }
      displayName
      email
      events(first: 5) {
        edges {
          node {
            message
          }
        }
      }
      firstName
      id
      image {
        id
      }
      lastName
      legacyResourceId
      lifetimeDuration
      mergeable {
        isMergeable
        reason
      }
      metafield(key: "app_key", namespace: "affiliates") {
        description
      }
      metafields(first: 5) {
        edges {
          node {
            id
          }
        }
      }
      note
      orders(first: 5) {
        edges {
          node {
            id
          }
        }
      }
      numberOfOrders
      phone
      state
      tags
      taxExempt
      amountSpent {
        amount
      }
      updatedAt
      validEmailAddress
      verifiedEmail
    }
  }`,
  );
  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
  query {
    customer(id: "gid://shopify/Customer/544365967") {
      addresses(first: 5) {
        address1
      }
      canDelete
      createdAt
      defaultAddress {
        address1
      }
      displayName
      email
      events(first: 5) {
        edges {
          node {
            message
          }
        }
      }
      firstName
      id
      image {
        id
      }
      lastName
      legacyResourceId
      lifetimeDuration
      mergeable {
        isMergeable
        reason
      }
      metafield(key: "app_key", namespace: "affiliates") {
        description
      }
      metafields(first: 5) {
        edges {
          node {
            id
          }
        }
      }
      note
      orders(first: 5) {
        edges {
          node {
            id
          }
        }
      }
      numberOfOrders
      phone
      state
      tags
      taxExempt
      amountSpent {
        amount
      }
      updatedAt
      validEmailAddress
      verifiedEmail
    }
  }
QUERY

response = client.query(query: query)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query {
    customer(id: "gid://shopify/Customer/544365967") {
      addresses(first: 5) {
        address1
      }
      canDelete
      createdAt
      defaultAddress {
        address1
      }
      displayName
      email
      events(first: 5) {
        edges {
          node {
            message
          }
        }
      }
      firstName
      id
      image {
        id
      }
      lastName
      legacyResourceId
      lifetimeDuration
      mergeable {
        isMergeable
        reason
      }
      metafield(key: "app_key", namespace: "affiliates") {
        description
      }
      metafields(first: 5) {
        edges {
          node {
            id
          }
        }
      }
      note
      orders(first: 5) {
        edges {
          node {
            id
          }
        }
      }
      numberOfOrders
      phone
      state
      tags
      taxExempt
      amountSpent {
        amount
      }
      updatedAt
      validEmailAddress
      verifiedEmail
    }
  }`,
});

Response

{
  "customer": {
    "addresses": [
      {
        "address1": "123 Amoebobacterieae St"
      }
    ],
    "canDelete": false,
    "createdAt": "2005-06-15T15:57:11Z",
    "defaultAddress": {
      "address1": "123 Amoebobacterieae St"
    },
    "displayName": "Bob Bobsen",
    "email": "bob@example.com",
    "events": {
      "edges": []
    },
    "firstName": "Bob",
    "id": "gid://shopify/Customer/544365967",
    "image": {
      "id": null
    },
    "lastName": "Bobsen",
    "legacyResourceId": "544365967",
    "lifetimeDuration": "almost 20 years",
    "mergeable": {
      "isMergeable": false,
      "reason": "Bob Bobsen is scheduled for redaction or has been redacted and can’t be merged."
    },
    "metafield": null,
    "metafields": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/Metafield/749520593"
          }
        }
      ]
    },
    "note": null,
    "orders": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/Order/116757651"
          }
        },
        {
          "node": {
            "id": "gid://shopify/Order/126216516"
          }
        },
        {
          "node": {
            "id": "gid://shopify/Order/148977776"
          }
        },
        {
          "node": {
            "id": "gid://shopify/Order/215577410"
          }
        },
        {
          "node": {
            "id": "gid://shopify/Order/235240302"
          }
        }
      ]
    },
    "numberOfOrders": "25",
    "phone": "+13125551212",
    "state": "ENABLED",
    "tags": [
      "Bob",
      "Canadian",
      "Léon",
      "Noël"
    ],
    "taxExempt": false,
    "amountSpent": {
      "amount": "8305.6"
    },
    "updatedAt": "2005-06-16T15:57:11Z",
    "validEmailAddress": true,
    "verifiedEmail": true
  }
}

Get metafields attached to a customer

Description

Get a page of metafields attached to a specific customer.

Query

query CustomerMetafields($ownerId: ID!) {
  customer(id: $ownerId) {
    metafields(first: 3) {
      edges {
        node {
          namespace
          key
          value
        }
      }
    }
  }
}

Variables

{
  "ownerId": "gid://shopify/Customer/544365967"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query CustomerMetafields($ownerId: ID!) { customer(id: $ownerId) { metafields(first: 3) { edges { node { namespace key value } } } } }",
 "variables": {
    "ownerId": "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
  query CustomerMetafields($ownerId: ID!) {
    customer(id: $ownerId) {
      metafields(first: 3) {
        edges {
          node {
            namespace
            key
            value
          }
        }
      }
    }
  }`,
  {
    variables: {
        "ownerId": "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
  query CustomerMetafields($ownerId: ID!) {
    customer(id: $ownerId) {
      metafields(first: 3) {
        edges {
          node {
            namespace
            key
            value
          }
        }
      }
    }
  }
QUERY

variables = {
  "ownerId": "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": `query CustomerMetafields($ownerId: ID!) {
      customer(id: $ownerId) {
        metafields(first: 3) {
          edges {
            node {
              namespace
              key
              value
            }
          }
        }
      }
    }`,
    "variables": {
        "ownerId": "gid://shopify/Customer/544365967"
    },
  },
});

Response

{
  "customer": {
    "metafields": {
      "edges": [
        {
          "node": {
            "namespace": "my_fields",
            "key": "nickname",
            "value": "rob"
          }
        }
      ]
    }
  }
}

Get the email, name, and account creation date of three customers using a fragment

Description

The following query retrieves three specific customers with the associated IDs, which are aliased to the names provided. It returns the customer fields specified in the fragment.

Query

query {
  Bob: customer(id: "gid://shopify/Customer/544365967") {
    ...customerProfile
  }
  Jane: customer(id: "gid://shopify/Customer/567375318") {
    ...customerProfile
  }
  Jenny: customer(id: "gid://shopify/Customer/56501169") {
    ...customerProfile
  }
}

fragment customerProfile on Customer {
  firstName
  lastName
  email
  createdAt
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query { Bob: customer(id: \"gid://shopify/Customer/544365967\") { ...customerProfile } Jane: customer(id: \"gid://shopify/Customer/567375318\") { ...customerProfile } Jenny: customer(id: \"gid://shopify/Customer/56501169\") { ...customerProfile } } fragment customerProfile on Customer { firstName lastName email createdAt }"
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query {
    Bob: customer(id: "gid://shopify/Customer/544365967") {
      ...customerProfile
    }
    Jane: customer(id: "gid://shopify/Customer/567375318") {
      ...customerProfile
    }
    Jenny: customer(id: "gid://shopify/Customer/56501169") {
      ...customerProfile
    }
  }
  
  fragment customerProfile on Customer {
    firstName
    lastName
    email
    createdAt
  }`,
  );
  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
  query {
    Bob: customer(id: "gid://shopify/Customer/544365967") {
      ...customerProfile
    }
    Jane: customer(id: "gid://shopify/Customer/567375318") {
      ...customerProfile
    }
    Jenny: customer(id: "gid://shopify/Customer/56501169") {
      ...customerProfile
    }
  }
  
  fragment customerProfile on Customer {
    firstName
    lastName
    email
    createdAt
  }
QUERY

response = client.query(query: query)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query {
    Bob: customer(id: "gid://shopify/Customer/544365967") {
      ...customerProfile
    }
    Jane: customer(id: "gid://shopify/Customer/567375318") {
      ...customerProfile
    }
    Jenny: customer(id: "gid://shopify/Customer/56501169") {
      ...customerProfile
    }
  }
  
  fragment customerProfile on Customer {
    firstName
    lastName
    email
    createdAt
  }`,
});

Response

{
  "Bob": {
    "firstName": "Bob",
    "lastName": "Bobsen",
    "email": "bob@example.com",
    "createdAt": "2005-06-15T15:57:11Z"
  },
  "Jane": {
    "firstName": "Jane",
    "lastName": "Smith",
    "email": "janesmith@b2b.example.com",
    "createdAt": "2025-05-12T20:21:18Z"
  },
  "Jenny": {
    "firstName": "Jenny",
    "lastName": "Test",
    "email": "jennytest@b2b.example.com",
    "createdAt": "2025-05-12T20:21:18Z"
  }
}

Get the first five line items of the customer's last order

Description

The following query retrieves the customer with the associated ID. It returns details about the last 5 line items associated with the customer's most recent order.

Query

query {
  customer(id: "gid://shopify/Customer/624407574") {
    lastOrder {
      lineItems(first: 5) {
        edges {
          node {
            name
            quantity
          }
        }
      }
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query { customer(id: \"gid://shopify/Customer/624407574\") { lastOrder { lineItems(first: 5) { edges { node { name quantity } } } } } }"
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query {
    customer(id: "gid://shopify/Customer/624407574") {
      lastOrder {
        lineItems(first: 5) {
          edges {
            node {
              name
              quantity
            }
          }
        }
      }
    }
  }`,
  );
  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
  query {
    customer(id: "gid://shopify/Customer/624407574") {
      lastOrder {
        lineItems(first: 5) {
          edges {
            node {
              name
              quantity
            }
          }
        }
      }
    }
  }
QUERY

response = client.query(query: query)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query {
    customer(id: "gid://shopify/Customer/624407574") {
      lastOrder {
        lineItems(first: 5) {
          edges {
            node {
              name
              quantity
            }
          }
        }
      }
    }
  }`,
});

Response

{
  "customer": {
    "lastOrder": {
      "lineItems": {
        "edges": [
          {
            "node": {
              "name": "Draft - 151cm",
              "quantity": 1
            }
          }
        ]
      }
    }
  }
}

Get the merge status of a customer

Description

Retrieve the merge status of a customer.

Query

query {
  customer(id: "gid://shopify/Customer/105906728") {
    mergeable {
      isMergeable
      reason
      errorFields
      mergeInProgress {
        jobId
        status
        resultingCustomerId
        customerMergeErrors {
          errorFields
          message
        }
      }
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query { customer(id: \"gid://shopify/Customer/105906728\") { mergeable { isMergeable reason errorFields mergeInProgress { jobId status resultingCustomerId customerMergeErrors { errorFields message } } } } }"
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query {
    customer(id: "gid://shopify/Customer/105906728") {
      mergeable {
        isMergeable
        reason
        errorFields
        mergeInProgress {
          jobId
          status
          resultingCustomerId
          customerMergeErrors {
            errorFields
            message
          }
        }
      }
    }
  }`,
  );
  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
  query {
    customer(id: "gid://shopify/Customer/105906728") {
      mergeable {
        isMergeable
        reason
        errorFields
        mergeInProgress {
          jobId
          status
          resultingCustomerId
          customerMergeErrors {
            errorFields
            message
          }
        }
      }
    }
  }
QUERY

response = client.query(query: query)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query {
    customer(id: "gid://shopify/Customer/105906728") {
      mergeable {
        isMergeable
        reason
        errorFields
        mergeInProgress {
          jobId
          status
          resultingCustomerId
          customerMergeErrors {
            errorFields
            message
          }
        }
      }
    }
  }`,
});

Response

{
  "customer": {
    "mergeable": {
      "isMergeable": false,
      "reason": "John Smith is scheduled for redaction or has been redacted and can’t be merged.",
      "errorFields": [
        "REDACTED_AT"
      ],
      "mergeInProgress": null
    }
  }
}

Get two specific customers by their ID using aliases

Description

The following query retrieves two specific customers with the associated IDs. It returns the customer fields specified in the query, aliased to the names provided.

Query

query {
  bob: customer(id: "gid://shopify/Customer/544365967") {
    firstName
    lastName
    email
  }
  john: customer(id: "gid://shopify/Customer/105906728") {
    firstName
    lastName
    email
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query { bob: customer(id: \"gid://shopify/Customer/544365967\") { firstName lastName email } john: customer(id: \"gid://shopify/Customer/105906728\") { firstName lastName email } }"
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query {
    bob: customer(id: "gid://shopify/Customer/544365967") {
      firstName
      lastName
      email
    }
    john: customer(id: "gid://shopify/Customer/105906728") {
      firstName
      lastName
      email
    }
  }`,
  );
  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
  query {
    bob: customer(id: "gid://shopify/Customer/544365967") {
      firstName
      lastName
      email
    }
    john: customer(id: "gid://shopify/Customer/105906728") {
      firstName
      lastName
      email
    }
  }
QUERY

response = client.query(query: query)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query {
    bob: customer(id: "gid://shopify/Customer/544365967") {
      firstName
      lastName
      email
    }
    john: customer(id: "gid://shopify/Customer/105906728") {
      firstName
      lastName
      email
    }
  }`,
});

Response

{
  "bob": {
    "firstName": "Bob",
    "lastName": "Bobsen",
    "email": "bob@example.com"
  },
  "john": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "johnsmith@example.com"
  }
}

Retrieve a metafield associated with a customer

Description

Get the metafield value identified by `my_fields.nickname` on a specific customer.

Query

query CustomerMetafield($namespace: String!, $key: String!, $ownerId: ID!) {
  customer(id: $ownerId) {
    nickname: metafield(namespace: $namespace, key: $key) {
      value
    }
  }
}

Variables

{
  "namespace": "my_fields",
  "key": "nickname",
  "ownerId": "gid://shopify/Customer/544365967"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query CustomerMetafield($namespace: String!, $key: String!, $ownerId: ID!) { customer(id: $ownerId) { nickname: metafield(namespace: $namespace, key: $key) { value } } }",
 "variables": {
    "namespace": "my_fields",
    "key": "nickname",
    "ownerId": "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
  query CustomerMetafield($namespace: String!, $key: String!, $ownerId: ID!) {
    customer(id: $ownerId) {
      nickname: metafield(namespace: $namespace, key: $key) {
        value
      }
    }
  }`,
  {
    variables: {
        "namespace": "my_fields",
        "key": "nickname",
        "ownerId": "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
  query CustomerMetafield($namespace: String!, $key: String!, $ownerId: ID!) {
    customer(id: $ownerId) {
      nickname: metafield(namespace: $namespace, key: $key) {
        value
      }
    }
  }
QUERY

variables = {
  "namespace": "my_fields",
  "key": "nickname",
  "ownerId": "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": `query CustomerMetafield($namespace: String!, $key: String!, $ownerId: ID!) {
      customer(id: $ownerId) {
        nickname: metafield(namespace: $namespace, key: $key) {
          value
        }
      }
    }`,
    "variables": {
        "namespace": "my_fields",
        "key": "nickname",
        "ownerId": "gid://shopify/Customer/544365967"
    },
  },
});

Response

{
  "customer": {
    "nickname": {
      "value": "rob"
    }
  }
}

Retrieve details for all addresses associated with a customer

Description

This query retrieves a customer's ID, address, and city for the first 250 addresses associated with a [customer](https://shopify.dev/docs/api/admin-graphql/latest/objects/customer) using the `addressesV2` field. Use the `id` argument to specify the customer.

Query

query CustomerAddressShow($id: ID!) {
  customer(id: $id) {
    addressesV2(first: 250) {
      edges {
        node {
          id
          address1
          city
        }
      }
    }
  }
}

Variables

{
  "id": "gid://shopify/Customer/544365967"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query CustomerAddressShow($id: ID!) { customer(id: $id) { addressesV2(first: 250) { edges { node { id address1 city } } } } }",
 "variables": {
    "id": "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
  query CustomerAddressShow($id: ID!) {
    customer(id: $id) {
      addressesV2(first: 250) {
        edges {
          node {
            id
            address1
            city
          }
        }
      }
    }
  }`,
  {
    variables: {
        "id": "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
  query CustomerAddressShow($id: ID!) {
    customer(id: $id) {
      addressesV2(first: 250) {
        edges {
          node {
            id
            address1
            city
          }
        }
      }
    }
  }
QUERY

variables = {
  "id": "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": `query CustomerAddressShow($id: ID!) {
      customer(id: $id) {
        addressesV2(first: 250) {
          edges {
            node {
              id
              address1
              city
            }
          }
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Customer/544365967"
    },
  },
});

Response

{
  "customer": {
    "addressesV2": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/MailingAddress/544365967?model_name=CustomerAddress",
            "address1": "123 Amoebobacterieae St",
            "city": "Ottawa"
          }
        }
      ]
    }
  }
}

Retrieve pinned metafield definitions associated with a customer

Description

This query retrieves the first 10 [pinned metafield definitions](https://help.shopify.com/en/manual/custom-data/metafields/pinning-metafield-definitions) for a customer.It shows each definition's name, namespace, key, and data type, ordered by pinned position.

Query

query CustomerMetafieldDefinitions($ownerId: ID!, $first: Int, $pinnedStatus: MetafieldDefinitionPinnedStatus, $sortKey: MetafieldDefinitionSortKeys) {
  customer(id: $ownerId) {
    metafieldDefinitions(first: $first, pinnedStatus: $pinnedStatus, sortKey: $sortKey) {
      edges {
        node {
          name
          namespace
          key
          type {
            name
          }
        }
      }
    }
  }
}

Variables

{
  "pinnedStatus": "PINNED",
  "ownerId": "gid://shopify/Customer/544365967",
  "first": 10,
  "sortKey": "PINNED_POSITION"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query CustomerMetafieldDefinitions($ownerId: ID!, $first: Int, $pinnedStatus: MetafieldDefinitionPinnedStatus, $sortKey: MetafieldDefinitionSortKeys) { customer(id: $ownerId) { metafieldDefinitions(first: $first, pinnedStatus: $pinnedStatus, sortKey: $sortKey) { edges { node { name namespace key type { name } } } } } }",
 "variables": {
    "pinnedStatus": "PINNED",
    "ownerId": "gid://shopify/Customer/544365967",
    "first": 10,
    "sortKey": "PINNED_POSITION"
  }
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query CustomerMetafieldDefinitions($ownerId: ID!, $first: Int, $pinnedStatus: MetafieldDefinitionPinnedStatus, $sortKey: MetafieldDefinitionSortKeys) {
    customer(id: $ownerId) {
      metafieldDefinitions(first: $first, pinnedStatus: $pinnedStatus, sortKey: $sortKey) {
        edges {
          node {
            name
            namespace
            key
            type {
              name
            }
          }
        }
      }
    }
  }`,
  {
    variables: {
        "pinnedStatus": "PINNED",
        "ownerId": "gid://shopify/Customer/544365967",
        "first": 10,
        "sortKey": "PINNED_POSITION"
    },
  },
  );
  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
  query CustomerMetafieldDefinitions($ownerId: ID!, $first: Int, $pinnedStatus: MetafieldDefinitionPinnedStatus, $sortKey: MetafieldDefinitionSortKeys) {
    customer(id: $ownerId) {
      metafieldDefinitions(first: $first, pinnedStatus: $pinnedStatus, sortKey: $sortKey) {
        edges {
          node {
            name
            namespace
            key
            type {
              name
            }
          }
        }
      }
    }
  }
QUERY

variables = {
  "pinnedStatus": "PINNED",
  "ownerId": "gid://shopify/Customer/544365967",
  "first": 10,
  "sortKey": "PINNED_POSITION"
}

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

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query CustomerMetafieldDefinitions($ownerId: ID!, $first: Int, $pinnedStatus: MetafieldDefinitionPinnedStatus, $sortKey: MetafieldDefinitionSortKeys) {
      customer(id: $ownerId) {
        metafieldDefinitions(first: $first, pinnedStatus: $pinnedStatus, sortKey: $sortKey) {
          edges {
            node {
              name
              namespace
              key
              type {
                name
              }
            }
          }
        }
      }
    }`,
    "variables": {
        "pinnedStatus": "PINNED",
        "ownerId": "gid://shopify/Customer/544365967",
        "first": 10,
        "sortKey": "PINNED_POSITION"
    },
  },
});

Response

{
  "customer": {
    "metafieldDefinitions": {
      "edges": [
        {
          "node": {
            "name": "Pronouns",
            "namespace": "my_fields",
            "key": "pronouns",
            "type": {
              "name": "single_line_text_field"
            }
          }
        },
        {
          "node": {
            "name": "Nickname",
            "namespace": "my_fields",
            "key": "nickname",
            "type": {
              "name": "single_line_text_field"
            }
          }
        }
      ]
    }
  }
}

Retrieves a list of addresses for a customer

Description

This query retrieves the default address and the first 10 secondary addresses for a [customer](https://shopify.dev/docs/api/admin-graphql/latest/objects/customer) using the `addressesV2` field. Use the `id` argument to specify the customer.

Query

query CustomerAddressList($id: ID!) {
  customer(id: $id) {
    defaultAddress {
      address1
      city
    }
    addressesV2(first: 10) {
      edges {
        node {
          address1
          city
        }
      }
    }
  }
}

Variables

{
  "id": "gid://shopify/Customer/544365967"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query CustomerAddressList($id: ID!) { customer(id: $id) { defaultAddress { address1 city } addressesV2(first: 10) { edges { node { address1 city } } } } }",
 "variables": {
    "id": "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
  query CustomerAddressList($id: ID!) {
    customer(id: $id) {
      defaultAddress {
        address1
        city
      }
      addressesV2(first: 10) {
        edges {
          node {
            address1
            city
          }
        }
      }
    }
  }`,
  {
    variables: {
        "id": "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
  query CustomerAddressList($id: ID!) {
    customer(id: $id) {
      defaultAddress {
        address1
        city
      }
      addressesV2(first: 10) {
        edges {
          node {
            address1
            city
          }
        }
      }
    }
  }
QUERY

variables = {
  "id": "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": `query CustomerAddressList($id: ID!) {
      customer(id: $id) {
        defaultAddress {
          address1
          city
        }
        addressesV2(first: 10) {
          edges {
            node {
              address1
              city
            }
          }
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/Customer/544365967"
    },
  },
});

Response

{
  "customer": {
    "defaultAddress": {
      "address1": "123 Amoebobacterieae St",
      "city": "Ottawa"
    },
    "addressesV2": {
      "edges": [
        {
          "node": {
            "address1": "123 Amoebobacterieae St",
            "city": "Ottawa"
          }
        }
      ]
    }
  }
}

Examples

Open in GraphiQL

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

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

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

const response = await admin.graphql(

`#graphql

query {

customer(id: "gid://shopify/Customer/544365967") {

firstName

lastName

phone

numberOfOrders

amountSpent {

amount

currencyCode

}

createdAt

updatedAt

note

verifiedEmail

validEmailAddress

GQL

query {
  customer(id: "gid://shopify/Customer/544365967") {
    id
    firstName
    lastName
    email
    phone
    numberOfOrders
    amountSpent {
      amount
      currencyCode
    }
    createdAt
    updatedAt
    note
    verifiedEmail
    validEmailAddress
    tags
    lifetimeDuration
    defaultAddress {
      formattedArea
      address1
    }
    addresses {
      address1
    }
    image {
      src
    }
    canDelete
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query { customer(id: \"gid://shopify/Customer/544365967\") { id firstName lastName email phone numberOfOrders amountSpent { amount currencyCode } createdAt updatedAt note verifiedEmail validEmailAddress tags lifetimeDuration defaultAddress { formattedArea address1 } addresses { address1 } image { src } canDelete } }"
}'

React Router

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

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query {
    customer(id: "gid://shopify/Customer/544365967") {
      id
      firstName
      lastName
      email
      phone
      numberOfOrders
      amountSpent {
        amount
        currencyCode
      }
      createdAt
      updatedAt
      note
      verifiedEmail
      validEmailAddress
      tags
      lifetimeDuration
      defaultAddress {
        formattedArea
        address1
      }
      addresses {
        address1
      }
      image {
        src
      }
      canDelete
    }
  }`,
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query {
    customer(id: "gid://shopify/Customer/544365967") {
      id
      firstName
      lastName
      email
      phone
      numberOfOrders
      amountSpent {
        amount
        currencyCode
      }
      createdAt
      updatedAt
      note
      verifiedEmail
      validEmailAddress
      tags
      lifetimeDuration
      defaultAddress {
        formattedArea
        address1
      }
      addresses {
        address1
      }
      image {
        src
      }
      canDelete
    }
  }`,
});

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
  query {
    customer(id: "gid://shopify/Customer/544365967") {
      id
      firstName
      lastName
      email
      phone
      numberOfOrders
      amountSpent {
        amount
        currencyCode
      }
      createdAt
      updatedAt
      note
      verifiedEmail
      validEmailAddress
      tags
      lifetimeDuration
      defaultAddress {
        formattedArea
        address1
      }
      addresses {
        address1
      }
      image {
        src
      }
      canDelete
    }
  }
QUERY

response = client.query(query: query)

Response

JSON

{

"customer": {

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

"firstName": "Bob",

"lastName": "Bobsen",

"email": "bob@example.com",

"phone": "+13125551212",

"numberOfOrders": "25",

"amountSpent": {

"amount": "8305.6",

"currencyCode": "USD"

"createdAt": "2005-06-15T15:57:11Z",

"updatedAt": "2005-06-16T15:57:11Z",

"note": null,

"verifiedEmail": true,

"validEmailAddress": true,

"tags": [

"Bob",

"Canadian",

"Léon",

"Noël"

"lifetimeDuration": "almost 20 years",

"defaultAddress": {

"formattedArea": "Ottawa ON, Canada",

"address1": "123 Amoebobacterieae St"

"addresses": [

{

"address1": "123 Amoebobacterieae St"

}

"image": {

"src": "https://cdn.shopify.com/proxy/d02a582792c73c48b4b62a95f42bcbf6eff91c5d232efb2057ca4c41005e4728/www.gravatar.com/avatar/4b9bb80620f03eb3719e0a061c14283d.jpg?s=2048&d=https%3A%2F%2Fcdn.shopify.com%2Fshopifycloud%2Fshopify%2Fassets%2Fadmin%2Fcustomers%2Fpolaris%2Favatar-2-a0ee6e3fb3ae515b66b68388b265e5bd1e90646c4c72d59170518f45351e668b.png"

"canDelete": false

}