customers

Returns a list of customers in your Shopify store, including key information such as name, email, location, and purchase history.

Use it in a workflow

Add a step and choose the Shopify connector.
Pick the customers action (under Customers).
Fill in the fields below, then reference the result from later steps as {{customers.response.data}}.

Query

This is the query the action sends by default. Edit it in the step's Query field to change which fields come back.

graphql

query Customers($first: Int, $after: String, $last: Int, $before: String, $reverse: Boolean, $sortKey: CustomerSortKeys, $query: String) {
  customers(
    first: $first
    after: $after
    last: $last
    before: $before
    reverse: $reverse
    sortKey: $sortKey
    query: $query
  ) {
    edges {
      cursor
      node {
        amountSpent
        canDelete
        companyContactProfiles
        createdAt
        dataSaleOptOut
        defaultAddress
        defaultEmailAddress
        defaultPhoneNumber
        displayName
        email
        emailMarketingConsent
        firstName
        hasTimelineComment
        id
        identityProviderSubjects
        lastName
        lastOrder
        legacyResourceId
        lifetimeDuration
        locale
        market
        mergeable
        multipassIdentifier
        note
        numberOfOrders
        phone
        productSubscriberStatus
        smsMarketingConsent
        state
        statistics
        tags
        taxExempt
        taxExemptions
        taxSettings
        unsubscribeUrl
        updatedAt
        validEmailAddress
        verifiedEmail
      }
    }
    nodes {
      amountSpent {
        amount
        currencyCode
      }
      canDelete
      companyContactProfiles {
        company
        createdAt
        customer
        id
        isMainContact
        lifetimeDuration
        locale
        title
        updatedAt
      }
      createdAt
      dataSaleOptOut
      defaultAddress {
        address1
        address2
        city
        company
        coordinatesValidated
        country
        countryCode
        countryCodeV2
        firstName
        formattedArea
        id
        lastName
        latitude
        longitude
        name
        phone
        province
        provinceCode
        timeZone
        validationResultSummary
        zip
      }
      defaultEmailAddress {
        emailAddress
        marketingOptInLevel
        marketingState
        marketingUnsubscribeUrl
        marketingUpdatedAt
        openTrackingLevel
        openTrackingUrl
        sourceLocation
        validFormat
      }
      defaultPhoneNumber {
        marketingCollectedFrom
        marketingOptInLevel
        marketingState
        marketingUpdatedAt
        phoneNumber
        sourceLocation
        whatsAppMarketingConsent
      }
      displayName
      email
      emailMarketingConsent {
        consentUpdatedAt
        marketingOptInLevel
        marketingState
        sourceLocation
      }
      firstName
      hasTimelineComment
      id
      identityProviderSubjects {
        createdAt
        id
        providerName
        subject
        updatedAt
      }
      lastName
      lastOrder {
        additionalFees
        alerts
        app
        attribution
        billingAddress
        billingAddressMatchesShippingAddress
        canMarkAsPaid
        canNotifyCustomer
        cancelReason
        cancellation
        cancelledAt
        capturable
        cartDiscountAmount
        cartDiscountAmountSet
        cartToken
        channel
        channelInformation
        checkoutToken
        clientIp
        closed
        closedAt
        confirmationNumber
        confirmed
        createdAt
        currencyCode
        currentCartDiscountAmountSet
        currentShippingPriceSet
        currentSubtotalLineItemsQuantity
        currentSubtotalPriceSet
        currentTaxLines
        currentTotalAdditionalFeesSet
        currentTotalDiscountsSet
        currentTotalDutiesSet
        currentTotalPriceSet
        currentTotalTaxSet
        currentTotalWeight
        customAttributes
        customer
        customerAcceptsMarketing
        customerJourney
        customerJourneySummary
        customerLocale
        discountCode
        discountCodes
        displayAddress
        displayFinancialStatus
        displayFulfillmentStatus
        disputes
        dutiesIncluded
        edited
        email
        estimatedTaxes
        fulfillable
        fulfillmentsCount
        fullyPaid
        hasTimelineComment
        id
        landingPageDisplayText
        landingPageUrl
        legacyResourceId
        merchantBusinessEntity
        merchantEditable
        merchantEditableErrors
        merchantOfRecordApp
        name
        netPayment
        netPaymentSet
        note
        number
        originalTotalAdditionalFeesSet
        originalTotalDutiesSet
        originalTotalPriceSet
        paymentCollectionDetails
        paymentGatewayNames
        paymentTerms
        phone
        physicalLocation
        poNumber
        presentmentCurrencyCode
        processedAt
        productNetwork
        publication
        purchasingEntity
        referralCode
        referrerDisplayText
        referrerUrl
        refundDiscrepancySet
        refundable
        registeredSourceUrl
        requiresShipping
        restockable
        retailLocation
        returnStatus
        risk
        riskLevel
        shippingAddress
        shippingLine
        shopifyProtect
        sourceIdentifier
        sourceName
        staffMember
        subtotalLineItemsQuantity
        subtotalPrice
        subtotalPriceSet
        tags
        taxExempt
        taxLines
        taxesIncluded
        test
        totalCapturable
        totalCapturableSet
        totalCashRoundingAdjustment
        totalDiscounts
        totalDiscountsSet
        totalOutstandingSet
        totalPrice
        totalPriceSet
        totalReceived
        totalReceivedSet
        totalRefunded
        totalRefundedSet
        totalRefundedShippingSet
        totalShippingPrice
        totalShippingPriceSet
        totalTax
        totalTaxSet
        totalTipReceived
        totalTipReceivedSet
        totalWeight
        transactionsCount
        unpaid
        updatedAt
      }
      legacyResourceId
      lifetimeDuration
      locale
      market {
        catalogsCount
        conditions
        currencySettings
        delivery
        discountsCount
        enabled
        handle
        id
        name
        priceInclusions
        priceList
        primary
        status
        type
        webPresence
      }
      mergeable {
        errorFields
        isMergeable
        mergeInProgress
        reason
      }
      multipassIdentifier
      note
      numberOfOrders
      phone
      productSubscriberStatus
      smsMarketingConsent {
        consentCollectedFrom
        consentUpdatedAt
        marketingOptInLevel
        marketingState
        sourceLocation
      }
      state
      statistics {
        predictedSpendTier
        rfmGroup
      }
      tags
      taxExempt
      taxExemptions
      taxSettings {
        taxId
      }
      unsubscribeUrl
      updatedAt
      validEmailAddress
      verifiedEmail
    }
    pageInfo {
      endCursor
      hasNextPage
      hasPreviousPage
      startCursor
    }
  }
}

Variables

Pass these as a JSON object in the step's Variables field.

firstnumber

The first `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql).

afterstring

The elements that come after the specified [cursor](https://shopify.dev/api/usage/pagination-graphql).

lastnumber

The last `n` elements from the [paginated list](https://shopify.dev/api/usage/pagination-graphql).

beforestring

The elements that come before the specified [cursor](https://shopify.dev/api/usage/pagination-graphql).

reverseboolean

Reverse the order of the underlying list.

sortKeystring

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](https://shopify.dev/api/usage/pagination-graphql#search-performance-considerations).

One ofCREATED_ATIDLOCATIONNAMERELEVANCEUPDATED_AT

querystring

A filter made up of terms, connectives, modifiers, and comparators. | name | type | description | acceptable_values | default_value | example_use | | ---- | ---- | ---- | ---- | ---- | ---- | | default | string | Filter by a case-insensitive search of multiple fields in a document. | | | - `query=Bob Norman` - `query=title:green hoodie` | | accepts_marketing | boolean | Filter by whether a customer has consented to receive marketing material. | | | - `accepts_marketing:true` | | 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` | | customer_date | time | 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. | | | - `customer_date:'2024-03-15T14:30:00Z'` - `customer_date: >='2024-01-01'` | | 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. 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). | | | - `email:gmail.com` - `email:"bo.wang@example.com"` - `email:*` | | first_name | string | Filter by the customer's first name. | | | - `first_name:Jane` | | id | id | Filter by `id` range. | | | - `id:1234` - `id:>=1234` - `id:<=1234` | | 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'` | | last_name | string | Filter by the customer's last name. | | | - `last_name:Reeves` | | 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'` | | orders_count | integer | Filter by the total number of orders a customer has placed. | | | - `orders_count:5` | | 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:*` | | state | string | 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. | | | - `state:ENABLED` - `state:INVITED` - `state:DISABLED` - `state:DECLINED` | | 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'` | | 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'` | | 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` | | 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` | You can apply one or more filters to a query. Learn more about [Shopify API search syntax](https://shopify.dev/api/usage/search-syntax).

json

{
  "first": 0,
  "after": "string",
  "last": 0,
  "before": "string",
  "reverse": false,
  "sortKey": "CREATED_AT",
  "query": "string"
}

Response

Read the result with {{customers.response.data.data.customers}}. If the API returns errors, the step fails and they are at {{customers.response.data.errors}}.

edgesarray<object>

cursorobject

nodeobject

nodesarray<object>

amountSpentobject

canDeleteobject

companyContactProfilesobject

createdAtobject

dataSaleOptOutobject

defaultAddressobject

defaultEmailAddressobject

defaultPhoneNumberobject

displayNameobject

emailobject

emailMarketingConsentobject

firstNameobject

hasTimelineCommentobject

idobject

identityProviderSubjectsobject

lastNameobject

lastOrderobject

legacyResourceIdobject

lifetimeDurationobject

localeobject

marketobject

mergeableobject

multipassIdentifierobject

noteobject

numberOfOrdersobject

phoneobject

productSubscriberStatusobject

smsMarketingConsentobject

stateobject

statisticsobject

tagsobject

taxExemptobject

taxExemptionsobject

taxSettingsobject

unsubscribeUrlobject

updatedAtobject

validEmailAddressobject

verifiedEmailobject

pageInfoobject

endCursorstring

hasNextPageboolean

hasPreviousPageboolean

startCursorstring

Need more? See the Shopify guide for connection setup and behaviour shared by every action.

Was this page helpful?