---
title: customer - Customer API
description: >-
  Returns the Customer resource. Apps using the Customer Account API must meet
  the protected customer data
  [requirements](https://shopify.dev/docs/apps/launch/protected-customer-data).
api_version: 2026-01
api_name: customer
type: query
api_type: graphql
source_url:
  html: 'https://shopify.dev/docs/api/customer/latest/queries/customer'
  md: 'https://shopify.dev/docs/api/customer/latest/queries/customer.md'
---

# customer

query

Returns the Customer resource. Apps using the Customer Account API must meet the protected customer data [requirements](https://shopify.dev/docs/apps/launch/protected-customer-data).

## Possible returns

* Customer

  [Customer!](https://shopify.dev/docs/api/customer/latest/objects/Customer)

  Represents the personal information of a customer. Apps using the Customer Account API must meet the protected customer data [requirements](https://shopify.dev/docs/apps/launch/protected-customer-data).

  * addresses

    [Customer​Address​Connection!](https://shopify.dev/docs/api/customer/latest/connections/CustomerAddressConnection)

    non-null

    The addresses associated with the customer.

    * skip​Default

      [Boolean](https://shopify.dev/docs/api/customer/latest/scalars/Boolean)

      Default:false

      ### Arguments

      A flag indicating whether the default address should be included.

    * first

      [Int](https://shopify.dev/docs/api/customer/latest/scalars/Int)

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

    * after

      [String](https://shopify.dev/docs/api/customer/latest/scalars/String)

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

    * last

      [Int](https://shopify.dev/docs/api/customer/latest/scalars/Int)

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

    * before

      [String](https://shopify.dev/docs/api/customer/latest/scalars/String)

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

    * reverse

      [Boolean](https://shopify.dev/docs/api/customer/latest/scalars/Boolean)

      Default:false

      Reverse the order of the underlying list.

    ***

  * company​Contacts

    [Company​Contact​Connection!](https://shopify.dev/docs/api/customer/latest/connections/CompanyContactConnection)

    non-null

    The list of contacts the customer is associated with.

    * first

      [Int](https://shopify.dev/docs/api/customer/latest/scalars/Int)

      ### Arguments

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

    * after

      [String](https://shopify.dev/docs/api/customer/latest/scalars/String)

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

    * last

      [Int](https://shopify.dev/docs/api/customer/latest/scalars/Int)

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

    * before

      [String](https://shopify.dev/docs/api/customer/latest/scalars/String)

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

    * reverse

      [Boolean](https://shopify.dev/docs/api/customer/latest/scalars/Boolean)

      Default:false

      Reverse the order of the underlying list.

    ***

  * creation​Date

    [Date​Time!](https://shopify.dev/docs/api/customer/latest/scalars/DateTime)

    non-null

    The date and time when the customer was created.

  * default​Address

    [Customer​Address](https://shopify.dev/docs/api/customer/latest/objects/CustomerAddress)

    The default address of the customer.

  * display​Name

    [String!](https://shopify.dev/docs/api/customer/latest/scalars/String)

    non-null

    The full name of the customer, based on the first\_name and last\_name values. If these aren't available, it falls back to the customer's email address, and if that isn't available, the customer's phone number.

  * draft​Orders

    [Draft​Order​Connection!](https://shopify.dev/docs/api/customer/latest/connections/DraftOrderConnection)

    non-null

    The Draft Orders associated with the customer.

    * first

      [Int](https://shopify.dev/docs/api/customer/latest/scalars/Int)

      ### Arguments

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

    * after

      [String](https://shopify.dev/docs/api/customer/latest/scalars/String)

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

    * last

      [Int](https://shopify.dev/docs/api/customer/latest/scalars/Int)

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

    * before

      [String](https://shopify.dev/docs/api/customer/latest/scalars/String)

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

    * reverse

      [Boolean](https://shopify.dev/docs/api/customer/latest/scalars/Boolean)

      Default:false

      Reverse the order of the underlying list.

    * sort​Key

      [Draft​Order​Sort​Keys](https://shopify.dev/docs/api/customer/latest/enums/DraftOrderSortKeys)

      Default:ID

      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).

    * query

      [String](https://shopify.dev/docs/api/customer/latest/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

        * company\_contact\_id

          id

        - Filter by a case-insensitive search of multiple fields in a document.

        - Example:
          * `query=Bob Norman`
          * `query=title:green hoodie`

      * created\_at

        time

      * customer\_id

        id

      * * id

          id

        * name

          string

        - Filter by `id` range.

        - Example:
          * `id:1234`
          * `id:>=1234`
          * `id:<=1234`

      * purchasing\_entity

        string

      * source

        string

      * status

        string

      * tag

        string

      * updated\_at

        time

    ***

  * email​Address

    [Customer​Email​Address](https://shopify.dev/docs/api/customer/latest/objects/CustomerEmailAddress)

    [Pre-auth accessible](https://shopify.dev/docs/apps/build/customer-accounts/order-status-page#customer-account-api)

    The email address of the customer.

  * first​Name

    [String](https://shopify.dev/docs/api/customer/latest/scalars/String)

    The first name of the customer.

  * id

    [ID!](https://shopify.dev/docs/api/customer/latest/scalars/ID)

    non-null[Pre-auth accessible](https://shopify.dev/docs/apps/build/customer-accounts/order-status-page#customer-account-api)

    A globally-unique ID.

  * image​Url

    [URL!](https://shopify.dev/docs/api/customer/latest/scalars/URL)

    non-null

    The URL to the avatar image of the customer.

  * last​Incomplete​Checkout

    [Checkout](https://shopify.dev/docs/api/customer/latest/objects/Checkout)

    The customer's most recently updated, incomplete checkout.

  * last​Name

    [String](https://shopify.dev/docs/api/customer/latest/scalars/String)

    The last name of the customer.

  * metafield

    [Metafield](https://shopify.dev/docs/api/customer/latest/objects/Metafield)

    [Pre-auth accessible](https://shopify.dev/docs/apps/build/customer-accounts/order-status-page#customer-account-api)

    A metafield found by namespace and key.

    * namespace

      [String!](https://shopify.dev/docs/api/customer/latest/scalars/String)

      required

      ### Arguments

      A container for a set of metafields.

    * key

      [String!](https://shopify.dev/docs/api/customer/latest/scalars/String)

      required

      The identifier for the metafield.

    ***

  * metafields

    [\[Metafield\]!](https://shopify.dev/docs/api/customer/latest/objects/Metafield)

    non-null[Pre-auth accessible](https://shopify.dev/docs/apps/build/customer-accounts/order-status-page#customer-account-api)

    The metafields associated with the resource matching the supplied list of namespaces and keys.

    * identifiers

      [\[Has​Metafields​Identifier!\]!](https://shopify.dev/docs/api/customer/latest/input-objects/HasMetafieldsIdentifier)

      required

      ### Arguments

      The list of metafields to retrieve by namespace and key.

    ***

  * orders

    [Order​Connection!](https://shopify.dev/docs/api/customer/latest/connections/OrderConnection)

    non-null

    The orders associated with the customer.

    * first

      [Int](https://shopify.dev/docs/api/customer/latest/scalars/Int)

      ### Arguments

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

    * after

      [String](https://shopify.dev/docs/api/customer/latest/scalars/String)

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

    * last

      [Int](https://shopify.dev/docs/api/customer/latest/scalars/Int)

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

    * before

      [String](https://shopify.dev/docs/api/customer/latest/scalars/String)

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

    * reverse

      [Boolean](https://shopify.dev/docs/api/customer/latest/scalars/Boolean)

      Default:false

      Reverse the order of the underlying list.

    * sort​Key

      [Order​Sort​Keys](https://shopify.dev/docs/api/customer/latest/enums/OrderSortKeys)

      Default:ID

      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).

    * query

      [String](https://shopify.dev/docs/api/customer/latest/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

        * confirmation\_number

          string

        - Filter by a case-insensitive search of multiple fields in a document.

        - Example:
          * `query=Bob Norman`
          * `query=title:green hoodie`

      * created\_at

        time

      * * id

          id

        * name

          string

        - Filter by `id` range.

        - Example:
          * `id:1234`
          * `id:>=1234`
          * `id:<=1234`

      * order\_number

        string

      * processed\_at

        time

      * purchasing\_company\_contact\_id

        id

      * purchasing\_company\_id

        id

      * purchasing\_company\_location\_id

        id

      * purchasing\_entity

        string

      * shipment\_status

        string

      * updated\_at

        time

    ***

  * phone​Number

    [Customer​Phone​Number](https://shopify.dev/docs/api/customer/latest/objects/CustomerPhoneNumber)

    [Pre-auth accessible](https://shopify.dev/docs/apps/build/customer-accounts/order-status-page#customer-account-api)

    The phone number of the customer.

  * store​Credit​Accounts

    [Store​Credit​Account​Connection!](https://shopify.dev/docs/api/customer/latest/connections/StoreCreditAccountConnection)

    non-null[Pre-auth accessible](https://shopify.dev/docs/apps/build/customer-accounts/order-status-page#customer-account-api)

    A list of the owner resource's store credit accounts. Store credit accounts are not shown for shops with store credit disabled at checkout.

    * first

      [Int](https://shopify.dev/docs/api/customer/latest/scalars/Int)

      ### Arguments

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

    * after

      [String](https://shopify.dev/docs/api/customer/latest/scalars/String)

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

    * last

      [Int](https://shopify.dev/docs/api/customer/latest/scalars/Int)

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

    * before

      [String](https://shopify.dev/docs/api/customer/latest/scalars/String)

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

    * query

      [String](https://shopify.dev/docs/api/customer/latest/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).

      * currency\_code

        string

      * id

        id

        Filter by `id` range.

        Example:

        * `id:1234`
        * `id:>=1234`
        * `id:<=1234`

    ***

  * subscription​Contract

    [Subscription​Contract](https://shopify.dev/docs/api/customer/latest/objects/SubscriptionContract)

    Returns a `SubscriptionContract` resource by ID.

    * id

      [ID!](https://shopify.dev/docs/api/customer/latest/scalars/ID)

      required

      ### Arguments

      The ID of the `SubscriptionContract` to return.

    ***

  * subscription​Contracts

    [Subscription​Contract​Connection!](https://shopify.dev/docs/api/customer/latest/connections/SubscriptionContractConnection)

    non-null

    The Subscription Contracts associated with the customer.

    * first

      [Int](https://shopify.dev/docs/api/customer/latest/scalars/Int)

      ### Arguments

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

    * after

      [String](https://shopify.dev/docs/api/customer/latest/scalars/String)

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

    * last

      [Int](https://shopify.dev/docs/api/customer/latest/scalars/Int)

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

    * before

      [String](https://shopify.dev/docs/api/customer/latest/scalars/String)

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

    * reverse

      [Boolean](https://shopify.dev/docs/api/customer/latest/scalars/Boolean)

      Default:false

      Reverse the order of the underlying list.

    * sort​Key

      [Subscription​Contracts​Sort​Keys](https://shopify.dev/docs/api/customer/latest/enums/SubscriptionContractsSortKeys)

      Default:CREATED\_AT

      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).

    * query

      [String](https://shopify.dev/docs/api/customer/latest/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).

      * created\_at

        time

      * * id

          id

        * last\_billing\_attempt\_error\_type

          string

        - Filter by `id` range.

        - Example:
          * `id:1234`
          * `id:>=1234`
          * `id:<=1234`

      * status

        string

      * updated\_at

        time

    ***

  * tags

    [\[String!\]!](https://shopify.dev/docs/api/customer/latest/scalars/String)

    non-null

    A comma-separated list of tags that have been added to the customer.

***

## Examples

* ### With access to all personal data

  #### Description

  Retrieve basic customer information including their first name, last name, and email address. This query returns essential customer details that are commonly needed in customer account interfaces.

  #### Query

  ```graphql
  query {
    customer {
      firstName
      lastName
      emailAddress {
        emailAddress
      }
    }
  }
  ```

  #### cURL

  ```bash
  curl -X POST \
  https://your-development-store.myshopify.com/customer/api/2026-01/graphql \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {access_token}' \
  -d '{
  "query": "query { customer { firstName lastName emailAddress { emailAddress } } }"
  }'
  ```

  #### Response

  ```json
  {
    "customer": {
      "firstName": "Sally",
      "lastName": "Testopherson",
      "emailAddress": {
        "emailAddress": "testacustomer@example.com"
      }
    }
  }
  ```

* ### Without access to all personal data

  #### Description

  Demonstrates how GraphQL handles access to restricted fields like phoneNumber. When an app doesn't have permission to access certain customer data, the API returns an error with details about the required permissions.

  #### Query

  ```graphql
  query {
    customer {
      firstName
      lastName
      phoneNumber {
        phoneNumber
      }
    }
  }
  ```

  #### cURL

  ```bash
  curl -X POST \
  https://your-development-store.myshopify.com/customer/api/2026-01/graphql \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {access_token}' \
  -d '{
  "query": "query { customer { firstName lastName phoneNumber { phoneNumber } } }"
  }'
  ```

  #### Response

  ```json
  {
    "data": {
      "customer": {
        "firstName": "Sally",
        "lastName": "Testopherson",
        "phoneNumber": {
          "phoneNumber": null
        }
      }
    },
    "errors": [
      {
        "message": "This app is not approved to use the phoneNumber field. See https://partners.shopify.com/123/apps/456/customer_data for more details.",
        "locations": [],
        "path": [
          "customer",
          "phoneNumber",
          "phoneNumber"
        ]
      }
    ]
  }
  ```