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