We're constantly trying to improve your support experience, and your feedback is extremely valuable to us.

Please take a moment to tell us about your experience today.
Sign up for future Help Center user research studies.

GraphQL examples for customers

Example GraphQL queries and mutations for working with customers.

Querying customers

For more information, see the customer object reference.

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

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

View response

{
  "data": {
    "customer": {
      "email": "testcustomer@email.com",
      "firstName": "test",
      "lastName": "testopherson",
      "defaultAddress": {
        "address1": "123 Fake st.",
        "city": "Springfield",
        "province": "Kentucky",
        "zip": "123abc",
        "country": "United States"
      }
    }
  }
}


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

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

View response

{
  "data": {
    "customer": {
      "lastOrder": {
        "lineItems": {
          "edges": [
            {
              "node": {
                "name": "Calracha Shoes - Basket Weave",
                "quantity": 1
              }
            }
          ]
        }
      }
    }
  }
}


Get two specific customers by their ID using aliases

{
  john: customer(id: "gid://shopify/Customer/98495135746") {
    firstName
    lastName
    email
  }
  sally: customer(id: "gid://shopify/Customer/958346526776") {
    firstName
    lastName
    email
  }
}

View response

{
  "data": {
    "john": {
      "firstName": "John",
      "lastName": "Smith",
      "email": "john@test.com"
    },
    "sally": {
      "firstName": "Sally",
      "lastName": "Testopherson",
      "email": "sally@test.com"
    }
  }
}


Get the display name and total spent of the first five customers with more than three orders

{
  customers(query:"orders_count:>3", first: 5) {
    edges {
      node {
        displayName
        totalSpent
      }
    }
  }
}

View response

{
  "data": {
    "customers": {
      "edges": [
        {
          "node": {
            "displayName": "Rahmil Curvington",
            "totalSpent": "668.00"
          }
        },
        {
          "node": {
            "displayName": "Sasha Splurman",
            "totalSpent": "1238.44"
          }
        },
        {
          "node": {
            "displayName": "John Smith",
            "totalSpent": "774.77"
          }
        },
        {
          "node": {
            "displayName": "Kimberly Jones",
            "totalSpent": "346.87"
          }
        },
        {
          "node": {
            "displayName": "Frederick Splorton",
            "totalSpent": "1254.08"
          }
        }
      ]
    }
  }
}


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

{
  John: customer(id: "gid://shopify/Customer/98495135746") {
    ...customerProfile
  }
  Sasha: customer(id: "gid://shopify/Customer/958346526776") {
    ...customerProfile
  }
  Rahmil: customer(id: "gid://shopify/Customer/6305714562") {
    ...customerProfile
  }
}

fragment customerProfile on Customer {
  firstName
  lastName
  email
  createdAt
}

View response

{
  "data": {
    "John": {
      "firstName": "John",
      "lastName": "Smith",
      "email": "john@test.com",
      "createdAt": "2017-11-07T21:02:17Z"
    },
    "Sasha": {
      "firstName": "Sally",
      "lastName": "Testopherson",
      "email": "sally@test.com",
      "createdAt": "2019-02-11T14:51:36Z"
    },
    "Rahmil": {
      "firstName": "Rahmil",
      "lastName": "Curvington",
      "email": "rahmil@test.com",
      "createdAt": "2017-08-24T19:34:09Z"
    }
  }
}


Get all customers in Canada

{
  customers(first:5, query:"country:canada"){
    edges{
      node{
        id
      }
    }
  }
}

View response

{
  "data": {
    "customers": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/Customer/6305714562"
          }
        },
        {
          "node": {
            "id": "gid://shopify/Customer/6305714626"
          }
        }
      ]
    }
  }
}


Get all a customer's fields and connections

{
  customer(id: "gid://shopify/Customer/957611081784") {
    acceptsMarketing
    addresses(first: 5) {
      address1
    }
    averageOrderAmountV2 {
      amount
    }
    canDelete
    createdAt
    defaultAddress {
      address1
    }
    displayName
    email
    events(first: 5) {
      edges {
        node {
          message
        }
      }
    }
    firstName
    hasNote
    hasTimelineComment
    id
    image {
      id
    }
    lastName
    legacyResourceId
    lifetimeDuration
    metafield(key: "app_key", namespace: "affiliates") {
      description
    }
    metafields(first: 5) {
      edges {
        node {
          id
        }
      }
    }
    note
    orders(first: 5) {
      edges {
        node {
          id
        }
      }
    }
    ordersCount
    phone
    state
    tags
    taxExempt
    totalSpent
    totalSpentV2 {
      amount
    }
    updatedAt
    validEmailAddress
    verifiedEmail
  }
}

View response

{
  "data": {
    "customer": {
      "acceptsMarketing": false,
      "addresses": [],
      "averageOrderAmountV2": null,
      "canDelete": true,
      "createdAt": "2019-02-05T14:36:10Z",
      "defaultAddress": null,
      "displayName": "test testopherson",
      "email": "testcustomer@email.com",
      "events": {
        "edges": [
          {
            "node": {
              "message": "Shopify GraphiQL App added the email testcustomer@email.com to this customer."
            }
          }
        ]
      },
      "firstName": "test",
      "hasNote": false,
      "hasTimelineComment": false,
      "id": "gid://shopify/Customer/957611081784",
      "image": {
        "id": null
      },
      "lastName": "testopherson",
      "legacyResourceId": "957611081784",
      "lifetimeDuration": "about 2 hours",
      "metafield": null,
      "metafields": {
        "edges": []
      },
      "note": null,
      "orders": {
        "edges": []
      },
      "ordersCount": "0",
      "phone": null,
      "state": "DISABLED",
      "tags": [],
      "taxExempt": false,
      "totalSpent": "0.00",
      "totalSpentV2": {
        "amount": "0.0"
      },
      "updatedAt": "2019-02-05T14:36:11Z",
      "validEmailAddress": true,
      "verifiedEmail": true
    }
  }
}

Creating customers

For more information, see the customerCreate mutation reference.

Create a customer and return their customer ID

mutation {
  customerCreate(input: { email: "testcustomer@email.com", firstName: "test", lastName: "testopherson" }) {
    customer {
      id
    }
  }
}

View response

{
  "data": {
    "customerCreate": {
      "customer": {
        "id": "gid://shopify/Customer/957611081784"
      }
    }
  }
}


Create a customer with a metafield

mutation($input: CustomerInput!) {
  customerCreate(input: $input) {
    customer {
      id
    }
  }
}

Variables

{
  "input": {
    "email": "jim@email.com",
    "firstName": "Jim",
    "lastName": "Testopoloy",
    "metafields": {
      "namespace": "customer_preferences",
      "key": "favorite_shirt",
      "value": "blue t-shirt",
      "valueType": "STRING"
    }
  }
}

View response

{
  "data": {
    "customerCreate": {
      "customer": {
        "id": "gid://shopify/Customer/958361468984"
      }
    }
  }
}

Updating customers

For more information, see the customerUpdate mutation reference.

Update a customer's first name and return their customer ID

mutation {
  customerUpdate(input: {id: "gid://shopify/Customer/491279155222", firstName: "Supersample GraphQL"}) {
    customer {
      id
    }
  }
}

View response

{
  "data": {
    "customerUpdate": {
      "customer": {
        "id": "gid://shopify/Customer/6305714626"
      }
    }
  }
}


Update a customer's tags

mutation {
  customerUpdate(input: {id: "gid://shopify/Customer/958361468984", tags: ["Test tag, New tag"]}) {
    customer {
      id
      tags
    }
  }
}

View response

{
  "data": {
    "customerUpdate": {
      "customer": {
        "id": "gid://shopify/Customer/958361468984",
        "tags": [
          "New tag",
          "Test tag"
        ]
      }
    }
  }
}

Deleting customers

For more information, see the customerDelete mutation reference.

Delete a customer and return their ID

mutation {
  customerDelete(input:{id: "gid://shopify/Customer/958361468984"})
  {
    deletedCustomerId
  }
}

View response

{
  "data": {
    "customerDelete": {
      "deletedCustomerId": "gid://shopify/Customer/958361468984"
    }
  }
}

Sign up for a Partner account to get started.

Sign up