customers
Returns a list of customers in your Shopify store, including key information such as name, email, location, and purchase history.
Use this query to segment your audience, personalize marketing campaigns, or analyze customer behavior by applying filters based on location, order history, marketing preferences and tags.
The customers
query supports pagination and sorting.
CustomerConnection arguments
- Anchor to afterafter•
The elements that come after the specified cursor.
- Anchor to beforebefore•
The elements that come before the specified cursor.
- Anchor to firstfirst•
The first
n
elements from the paginated list.- Anchor to lastlast•
The last
n
elements from the paginated list.- Anchor to queryquery•
A filter made up of terms, connectives, modifiers, and comparators. You can apply one or more filters to a query. Learn more about Shopify API search syntax.
- Anchor to default•string
Filter by a case-insensitive search of multiple fields in a document.
query=Bob Norman
query=title:green hoodie
- Anchor to accepts_marketing•boolean
Filter by whether a customer has consented to receive marketing material.
accepts_marketing:true
- Anchor to country•string
Filter by the country associated with the customer's address. Use either the country name or the two-letter country code.
country:Canada
country:JP
- Anchor to customer_date•time
customer_date:'2024-03-15T14:30:00Z'
customer_date:'>=2024-01-01'
- Anchor to email•string
The customer's email address, used to communicate information about orders and for the purposes of email marketing campaigns. You can use a wildcard value to filter the query by customers who have an email address specified.
email:bo.wang@example.com
email:*
- Anchor to last_abandoned_order_date•time
Filter by the date and time of the customer's most recent abandoned checkout. An abandoned checkout occurs when a customer adds items to their cart, begins the checkout process, but leaves the site without completing their purchase.
last_abandoned_order_date:'2024-04-01T10:00:00Z'
last_abandoned_order_date:'>=2024-01-01'
- Anchor to order_date•time
Filter by the date and time that the order was placed by the customer. Use this query filter to check if a customer has placed at least one order within a specified date range.
order_date:'2024-02-20T00:00:00Z'
order_date:'>=2024-01-01'
order_date:'2024-01-01..2024-03-31'
- Anchor to orders_count•integer
Filter by the total number of orders a customer has placed.
orders_count:5
- Anchor to phone•string
The phone number of the customer, used to communicate information about orders and for the purposes of SMS marketing campaigns. You can use a wildcard value to filter the query by customers who have a phone number specified.
phone:+18005550100
phone:*
- Anchor to state•string
Filter by the state, province, or prefecture associated with the customer's address. Use either the name or the two-letter code.
state:Ontario
state:California
- Anchor to tag•string
Filter by the tags that are associated with the customer. This query parameter accepts multiple tags separated by commas.
tag:'VIP'
tag:'Wholesale,Repeat'
- Anchor to tag_not•string
Filter by the tags that aren't associated with the customer. This query parameter accepts multiple tags separated by commas.
tag_not:'Prospect'
tag_not:'Test,Internal'
- Anchor to total_spent•float
Filter by the total amount of money a customer has spent across all orders.
total_spent:100.50
total_spent:50.00
total_spent:>100.50
total_spent:>50.00
- Anchor to updated_at•time
The date and time, matching a whole day, when the customer's information was last updated.
updated_at:2024-01-01T00:00:00Z
updated_at:<now
updated_at:<=2024
Example:
Example:
Example:
Example:
Example:
Example:
Example:
Example:
Example:
Example:
Example:
Example:
Example:
Example:
- Anchor to reversereverse•BooleanDefault:false
Reverse the order of the underlying list.
- Anchor to sortKeysort•
Key CustomerSort Default:IDKeys Sort the underlying list using a key. If your query is slow or returns an error, then try specifying a sort key that matches the field used in the search.
Anchor to Possible returnsPossible returns
- Anchor to edgesedges•[Customer
Edge!]! non-null The connection between the node and its parent. Each edge contains a minimum of the edge's cursor and the node.
- Anchor to nodesnodes•[Customer!]!non-null
A list of nodes that are contained in CustomerEdge. You can fetch data about an individual node, or you can follow the edges to fetch data about a collection of related nodes. At each node, you specify the fields that you want to retrieve.
- Anchor to pageInfopage•
Info PageInfo! non-null An object that’s used to retrieve cursor information about the current page.
- Retrieve detailed information for a list of customers
- Retrieve the first 10 customers updated after December 1, 2019
- Retrieve the first 10 customers using pagination
- Retrieve the first 10 customers with an enabled customer account
- Retrieve the first five customers in Canada
Examples
query CustomerList {
customers(first: 50) {
nodes {
id
firstName
lastName
defaultEmailAddress {
emailAddress
marketingState
}
defaultPhoneNumber {
phoneNumber
marketingState
marketingCollectedFrom
}
createdAt
updatedAt
numberOfOrders
state
amountSpent {
amount
currencyCode
}
verifiedEmail
taxExempt
tags
addresses {
id
firstName
lastName
address1
city
province
country
zip
phone
name
provinceCode
countryCodeV2
}
defaultAddress {
id
address1
city
province
country
zip
phone
provinceCode
countryCodeV2
}
}
}
}
curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-04/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query CustomerList { customers(first: 50) { nodes { id firstName lastName defaultEmailAddress { emailAddress marketingState } defaultPhoneNumber { phoneNumber marketingState marketingCollectedFrom } createdAt updatedAt numberOfOrders state amountSpent { amount currencyCode } verifiedEmail taxExempt tags addresses { id firstName lastName address1 city province country zip phone name provinceCode countryCodeV2 } defaultAddress { id address1 city province country zip phone provinceCode countryCodeV2 } } } }"
}'
const { admin } = await authenticate.admin(request);
const response = await admin.graphql(
`#graphql
query CustomerList {
customers(first: 50) {
nodes {
id
firstName
lastName
defaultEmailAddress {
emailAddress
marketingState
}
defaultPhoneNumber {
phoneNumber
marketingState
marketingCollectedFrom
}
createdAt
updatedAt
numberOfOrders
state
amountSpent {
amount
currencyCode
}
verifiedEmail
taxExempt
tags
addresses {
id
firstName
lastName
address1
city
province
country
zip
phone
name
provinceCode
countryCodeV2
}
defaultAddress {
id
address1
city
province
country
zip
phone
provinceCode
countryCodeV2
}
}
}
}`,
);
const data = await response.json();
const client = new shopify.clients.Graphql({session});
const data = await client.query({
data: `query CustomerList {
customers(first: 50) {
nodes {
id
firstName
lastName
defaultEmailAddress {
emailAddress
marketingState
}
defaultPhoneNumber {
phoneNumber
marketingState
marketingCollectedFrom
}
createdAt
updatedAt
numberOfOrders
state
amountSpent {
amount
currencyCode
}
verifiedEmail
taxExempt
tags
addresses {
id
firstName
lastName
address1
city
province
country
zip
phone
name
provinceCode
countryCodeV2
}
defaultAddress {
id
address1
city
province
country
zip
phone
provinceCode
countryCodeV2
}
}
}
}`,
});
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 CustomerList {
customers(first: 50) {
nodes {
id
firstName
lastName
defaultEmailAddress {
emailAddress
marketingState
}
defaultPhoneNumber {
phoneNumber
marketingState
marketingCollectedFrom
}
createdAt
updatedAt
numberOfOrders
state
amountSpent {
amount
currencyCode
}
verifiedEmail
taxExempt
tags
addresses {
id
firstName
lastName
address1
city
province
country
zip
phone
name
provinceCode
countryCodeV2
}
defaultAddress {
id
address1
city
province
country
zip
phone
provinceCode
countryCodeV2
}
}
}
}
QUERY
response = client.query(query: query)