--- title: customers - GraphQL Admin description: |- Returns a list of [customers](https://shopify.dev/api/admin-graphql/latest/objects/Customer) 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](https://shopify.dev/api/usage/pagination-graphql) and [sorting](https://shopify.dev/api/admin-graphql/latest/enums/CustomerSortKeys). api_version: 2025-01 api_name: admin type: query api_type: graphql source_url: html: https://shopify.dev/docs/api/admin-graphql/2025-01/queries/customers md: https://shopify.dev/docs/api/admin-graphql/2025-01/queries/customers.md --- # customers query Returns a list of [customers](https://shopify.dev/api/admin-graphql/latest/objects/Customer) 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](https://shopify.dev/api/usage/pagination-graphql) and [sorting](https://shopify.dev/api/admin-graphql/latest/enums/CustomerSortKeys). ## CustomerConnection arguments [CustomerConnection!](https://shopify.dev/docs/api/admin-graphql/2025-01/connections/CustomerConnection) * after [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * before [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql). * first [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * last [Int](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/Int) The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql). * query [String](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) 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](https://shopify.dev/api/usage/search-syntax). * * default string * accepts\_marketing boolean * country string * customer\_date time * email string * first\_name string * id id * last\_abandoned\_order\_date time * last\_name string * order\_date time * orders\_count integer * phone string * state string * tag string * tag\_not string * total\_spent float * updated\_at time - Filter by a case-insensitive search of multiple fields in a document. - Example: * `query=Bob Norman` * `query=title:green hoodie` Filter by whether a customer has consented to receive marketing material. - Example: * `accepts_marketing:true` Filter by the country associated with the customer's address. Use either the country name or the two-letter country code. - Example: * `country:Canada` * `country:JP` Filter by the date and time when the customer record was created. This query parameter filters by the [`createdAt`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer#field-createdAt) field. - Example: * `customer_date:'2024-03-15T14:30:00Z'` * `customer_date: >='2024-01-01'` 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. Please note that *email* is a tokenized field: To retrieve exact matches, quote the email address (*phrase query*) as described in [Shopify API search syntax](https://shopify.dev/docs/api/usage/search-syntax). - Example: * `email:gmail.com` * `email:"bo.wang@example.com"` * `email:*` Filter by the customer's first name. - Example: * `first_name:Jane` Filter by `id` range. - Example: * `id:1234` * `id:>=1234` * `id:<=1234` 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. - Example: * `last_abandoned_order_date:'2024-04-01T10:00:00Z'` * `last_abandoned_order_date: >='2024-01-01'` Filter by the customer's last name. - Example: * `last_name:Reeves` 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. - Example: * `order_date:'2024-02-20T00:00:00Z'` * `order_date: >='2024-01-01'` * `order_date:'2024-01-01..2024-03-31'` Filter by the total number of orders a customer has placed. - Example: * `orders_count:5` 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. - Example: * `phone:+18005550100` * `phone:*` Filter by the [state](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer#field-state) of the customer's account with the shop. This filter is only valid when [Classic Customer Accounts](https://shopify.dev/docs/api/admin-graphql/latest/objects/CustomerAccountsV2#field-customerAccountsVersion) is active. - Example: * `state:ENABLED` * `state:INVITED` * `state:DISABLED` * `state:DECLINED` Filter by the tags that are associated with the customer. This query parameter accepts multiple tags separated by commas. - Example: * `tag:'VIP'` * `tag:'Wholesale,Repeat'` Filter by the tags that aren't associated with the customer. This query parameter accepts multiple tags separated by commas. - Example: * `tag_not:'Prospect'` * `tag_not:'Test,Internal'` Filter by the total amount of money a customer has spent across all orders. - Example: * `total_spent:100.50` * `total_spent:50.00` * `total_spent:>100.50` * `total_spent:>50.00` The date and time, matching a whole day, when the customer's information was last updated. Example: * `updated_at:2024-01-01T00:00:00Z` * `updated_at:2019-12-01") { edges { node { id firstName lastName updatedAt } } } } ``` #### cURL ```bash curl -X POST \ https://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \ -H 'Content-Type: application/json' \ -H 'X-Shopify-Access-Token: {access_token}' \ -d '{ "query": "query { customers(first: 10, query: \"updated_at:>2019-12-01\") { edges { node { id firstName lastName updatedAt } } } }" }' ``` #### React Router ```javascript import { authenticate } from "../shopify.server"; export const loader = async ({request}) => { const { admin } = await authenticate.admin(request); const response = await admin.graphql( `#graphql query { customers(first: 10, query: "updated_at:>2019-12-01") { edges { node { id firstName lastName updatedAt } } } }`, ); const json = await response.json(); return json.data; } ``` #### Ruby ```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 { customers(first: 10, query: "updated_at:>2019-12-01") { edges { node { id firstName lastName updatedAt } } } } QUERY response = client.query(query: query) ``` #### Node.js ```javascript const client = new shopify.clients.Graphql({session}); const data = await client.query({ data: `query { customers(first: 10, query: "updated_at:>2019-12-01") { edges { node { id firstName lastName updatedAt } } } }`, }); ``` #### Response ```json { "customers": { "edges": [ { "node": { "id": "gid://shopify/Customer/56501169", "firstName": "Jenny", "lastName": "Test", "updatedAt": "2025-04-15T19:26:33Z" } }, { "node": { "id": "gid://shopify/Customer/105906728", "firstName": "John", "lastName": "Smith", "updatedAt": "2025-04-15T19:26:33Z" } }, { "node": { "id": "gid://shopify/Customer/305367469", "firstName": "Test", "lastName": "Customer", "updatedAt": "2025-04-15T19:26:33Z" } }, { "node": { "id": "gid://shopify/Customer/317070273", "firstName": "Bob", "lastName": "Norman", "updatedAt": "2025-04-15T19:26:33Z" } }, { "node": { "id": "gid://shopify/Customer/324586928", "firstName": "B2B", "lastName": "Customer", "updatedAt": "2025-04-15T19:26:33Z" } }, { "node": { "id": "gid://shopify/Customer/352184960", "firstName": "Jenny", "lastName": "Doe", "updatedAt": "2025-04-15T19:26:33Z" } }, { "node": { "id": "gid://shopify/Customer/408913340", "firstName": "John", "lastName": "Doe", "updatedAt": "2025-04-15T19:26:33Z" } }, { "node": { "id": "gid://shopify/Customer/529223679", "firstName": "Bob", "lastName": "Marketing", "updatedAt": "2025-04-15T19:26:33Z" } }, { "node": { "id": "gid://shopify/Customer/554456816", "firstName": "test", "lastName": "test", "updatedAt": "2025-04-15T19:26:33Z" } }, { "node": { "id": "gid://shopify/Customer/567375318", "firstName": "Jane", "lastName": "Smith", "updatedAt": "2025-04-15T19:26:33Z" } } ] } } ``` * ### Retrieve the first five customers in Canada #### Description This query retrieves basic information, such as first name and last name for the first five \[customer]\(https\://shopify.dev/docs/api/admin-graphql/latest/objects/customer) records located in Canada. Use the \[\`country\`]\(https\://shopify.dev/docs/api/admin-graphql/latest/queries/customers#argument-query-filter-country) filter to specify the country. #### Query ```graphql query { customers(first: 5, query: "country:canada") { edges { node { id firstName lastName } } } } ``` #### cURL ```bash curl -X POST \ https://your-development-store.myshopify.com/admin/api/2025-01/graphql.json \ -H 'Content-Type: application/json' \ -H 'X-Shopify-Access-Token: {access_token}' \ -d '{ "query": "query { customers(first: 5, query: \"country:canada\") { edges { node { id firstName lastName } } } }" }' ``` #### React Router ```javascript import { authenticate } from "../shopify.server"; export const loader = async ({request}) => { const { admin } = await authenticate.admin(request); const response = await admin.graphql( `#graphql query { customers(first: 5, query: "country:canada") { edges { node { id firstName lastName } } } }`, ); const json = await response.json(); return json.data; } ``` #### Ruby ```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 { customers(first: 5, query: "country:canada") { edges { node { id firstName lastName } } } } QUERY response = client.query(query: query) ``` #### Node.js ```javascript const client = new shopify.clients.Graphql({session}); const data = await client.query({ data: `query { customers(first: 5, query: "country:canada") { edges { node { id firstName lastName } } } }`, }); ``` #### Response ```json { "customers": { "edges": [ { "node": { "id": "gid://shopify/Customer/105906728", "firstName": "John", "lastName": "Smith" } }, { "node": { "id": "gid://shopify/Customer/408913340", "firstName": "John", "lastName": "Doe" } }, { "node": { "id": "gid://shopify/Customer/544365967", "firstName": "Bob", "lastName": "Bobsen" } }, { "node": { "id": "gid://shopify/Customer/554456816", "firstName": "test", "lastName": "test" } }, { "node": { "id": "gid://shopify/Customer/624407574", "firstName": "Bob", "lastName": "Bobsen Jr." } } ] } } ``` [Open in GraphiQL](http://localhost:3457/graphiql?query=query%20%7B%0A%20%20customers\(first%3A%2010%2C%20query%3A%20%22updated_at%3A%3E2019-12-01%22\)%20%7B%0A%20%20%20%20edges%20%7B%0A%20%20%20%20%20%20node%20%7B%0A%20%20%20%20%20%20%20%20id%0A%20%20%20%20%20%20%20%20firstName%0A%20%20%20%20%20%20%20%20lastName%0A%20%20%20%20%20%20%20%20updatedAt%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D) ```javascript import { authenticate } from "../shopify.server"; export const loader = async ({request}) => { const { admin } = await authenticate.admin(request); const response = await admin.graphql( `#graphql query { customers(first: 10, query: "updated_at:>2019-12-01") { edges { node { id firstName lastName updatedAt } } } }`, ); const json = await response.json(); return json.data; } ``` ## Response JSON ```json { "customers": { "edges": [ { "node": { "id": "gid://shopify/Customer/56501169", "firstName": "Jenny", "lastName": "Test", "updatedAt": "2025-04-15T19:26:33Z" } }, { "node": { "id": "gid://shopify/Customer/105906728", "firstName": "John", "lastName": "Smith", "updatedAt": "2025-04-15T19:26:33Z" } }, { "node": { "id": "gid://shopify/Customer/305367469", "firstName": "Test", "lastName": "Customer", "updatedAt": "2025-04-15T19:26:33Z" } }, { "node": { "id": "gid://shopify/Customer/317070273", "firstName": "Bob", "lastName": "Norman", "updatedAt": "2025-04-15T19:26:33Z" } }, { "node": { "id": "gid://shopify/Customer/324586928", "firstName": "B2B", "lastName": "Customer", "updatedAt": "2025-04-15T19:26:33Z" } }, { "node": { "id": "gid://shopify/Customer/352184960", "firstName": "Jenny", "lastName": "Doe", "updatedAt": "2025-04-15T19:26:33Z" } }, { "node": { "id": "gid://shopify/Customer/408913340", "firstName": "John", "lastName": "Doe", "updatedAt": "2025-04-15T19:26:33Z" } }, { "node": { "id": "gid://shopify/Customer/529223679", "firstName": "Bob", "lastName": "Marketing", "updatedAt": "2025-04-15T19:26:33Z" } }, { "node": { "id": "gid://shopify/Customer/554456816", "firstName": "test", "lastName": "test", "updatedAt": "2025-04-15T19:26:33Z" } }, { "node": { "id": "gid://shopify/Customer/567375318", "firstName": "Jane", "lastName": "Smith", "updatedAt": "2025-04-15T19:26:33Z" } } ] } } ```