This is a beta release of documentation for Magento 2.4, published for previewing soon-to-be-released functionality. Content in this version is subject to change. Links to the v2.4 code base may not properly resolve until the code is officially released.

customer query

Edit on GitHub
Log an Issue

The customer query returns information about the logged-in customer, store credit history and customer’s wishlist.

To return or modify information about a customer, Magento recommends you use customer tokens in the header of your GraphQL calls. However, you also can use session authentication.

Syntax

{customer: {Customer}}

Example usage

Retrieving the logged-in customer

The following call returns information about the logged-in customer. Provide the customer’s token in the header section of the query.

Request:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
  customer {
    firstname
    lastname
    suffix
    email
    addresses {
      firstname
      lastname
      street
      city
      region {
        region_code
        region
      }
      postcode
      country_code
      telephone
    }
  }
}

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

{
  "data": {
    "customer": {
      "firstname": "John",
      "lastname": "Doe",
      "suffix": null,
      "email": "jdoe@example.com",
      "addresses": [
       {
         "firstname": "John",
         "lastname": "Doe",
         "street": [
           "123 Elm Street"
         ],
         "city": "Anytown",
         "region": {
           "region_code": "MI",
           "region": "Michigan"
         }
         "postcode": "78758",
         "country_code": "US",
         "telephone": "512 555-1212"
        }
      ]
    }
  }
}

Retrieving the store credit history

The following example returns the store credit history for the logged-in user.

Request:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

query {
  customer {
    firstname
    lastname
    store_credit {
      enabled
      balance_history(pageSize: 10) {
        items {
          action
          actual_balance {
            currency
            value
          }
          balance_change {
            currency
            value
          }
          date_time_changed
        }
        page_info {
          page_size
          current_page
          total_pages
        }
        total_count
      }
      current_balance {
        currency
        value
      }
    }
  }
}

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

{
  "data": {
    "customer": {
      "firstname": "John",
      "lastname": "Doe",
      "store_credit": {
        "enabled": true,
        "balance_history": {
          "items": [
            {
              "action": "Updated",
              "actual_balance": {
                "currency": "USD",
                "value": 10
              },
              "balance_change": {
                "currency": "USD",
                "value": -100
              },
              "date_time_changed": "2019-07-15 21:47:59"
            },
            {
              "action": "Updated",
              "actual_balance": {
                "currency": "USD",
                "value": 110
              },
              "balance_change": {
                "currency": "USD",
                "value": 10
              },
              "date_time_changed": "2019-07-15 21:47:18"
            },
            {
              "action": "Created",
              "actual_balance": {
                "currency": "USD",
                "value": 100
              },
              "balance_change": {
                "currency": "USD",
                "value": 100
              },
              "date_time_changed": "2019-07-15 16:31:05"
            }
          ],
          "page_info": {
            "page_size": 10,
            "current_page": 1,
            "total_pages": 1
          },
          "total_count": 3
        },
        "current_balance": {
          "currency": "USD",
          "value": 10
        }
      }
    }
  }
}

Retrieve the customer’s wish list

The following query returns the customer’s wish list:

Request:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  customer {
    wishlist {
      items {
        id
        description
        qty
        product {
          sku
          name
          price_range {
            maximum_price {
              regular_price {
                value
              }
            }
          }
        }
      }
    }
  }
}

Response:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

{
  "data": {
    "customer": {
      "wishlist": {
        "items": [
          {
            "id": 1,
            "description": "I need this",
            "qty": 1,
            "product": {
              "sku": "24-WG080",
              "name": "Sprite Yoga Companion Kit",
              "price_range": {
                "maximum_price": {
                  "regular_price": {
                    "value": 77
                  }
                }
              }
            }
          },
          {
            "id": 2,
            "description": null,
            "qty": 1,
            "product": {
              "sku": "24-UG04",
              "name": "Zing Jump Rope",
              "price_range": {
                "maximum_price": {
                  "regular_price": {
                    "value": 12
                  }
                }
              }
            }
          }
        ]
      }
    }
  }
}

Output attributes

Customer attributes

The customer object can contain the following attributes:

Attribute Data Type Description
addresses CustomerAddress An array containing the customer’s shipping and billing addresses
created_at String Timestamp indicating when the account was created
date_of_birth String The customer’s date of birth
default_billing String The ID assigned to the billing address
default_shipping String The ID assigned to the shipping address
dob String Deprecated. Use date_of_birth instead. The customer’s date of birth
email String The customer’s email address
firstname String The customer’s first name
gender Int The customer’s gender (Male - 1, Female - 2)
group_id Int Deprecated. This attribute is not applicable for GraphQL. The group assigned to the user. Default values are 0 (Not logged in), 1 (General), 2 (Wholesale), and 3 (Retailer)
id Int Deprecated. This attribute is not applicable for GraphQL.The ID assigned to the customer
is_subscribed Boolean Indicates whether the customer is subscribed to the company’s newsletter
lastname String The customer’s family name
middlename String The customer’s middle name
prefix String An honorific, such as Dr., Mr., or Mrs.
suffix String A value such as Sr., Jr., or III
taxvat String The customer’s Tax/VAT number (for corporate customers)
wishlist Wishlist! Contains the contents of the customer’s wish lists

CustomerAddress attributes

The values assigned to attributes such as firstname and lastname in this object may be different from those defined in the Customer object.

The CustomerAddress output returns the following attributes:

Attribute Data Type Description
city String The city or town
company String The customer’s company
country_code CountryCodeEnum The customer’s country
country_id String Deprecated. Use country_code instead. The customer’s country
custom_attributes CustomerAddressAttribute Deprecated. Not applicable for GraphQL
customer_id Int Deprecated. This attribute is not applicable for GraphQL. The ID assigned to the customer
default_billing Boolean Indicates whether the address is the default billing address
default_shipping Boolean Indicates whether the address is the default shipping address
extension_attributes CustomerAddressAttribute Address extension attributes
fax String The fax number
firstname String The first name of the person associated with the shipping/billing address
id Int The ID assigned to the address object
lastname String The family name of the person associated with the shipping/billing address
middlename String The middle name of the person associated with the shipping/billing address
postcode String The customer’s ZIP or postal code
prefix String An honorific, such as Dr., Mr., or Mrs.
region CustomerAddressRegion An object that defines the customer’s state or province
region_id Int The unique ID for a pre-defined region
street [String] An array of strings that define the street number and name
suffix String A value such as Sr., Jr., or III
telephone String The telephone number
vat_id String The customer’s Tax/VAT number (for corporate customers)

CustomerAddressAttribute attributes

The CustomerAddressAttribute output data type has been deprecated because the contents are not applicable for GraphQL. It can contain the following attributes:

Attribute Data Type Description
attribute_code String Attribute code
value String Attribute value

CustomerAddressRegion attributes

The customerAddressRegion output returns the following attributes:

Attribute Data Type Description
region String The state or province name
region_code String The address region code
region_id Int The unique ID for a pre-defined region

Wishlist attributes

Attribute Data type Description
items [WishlistItem] An array of items in the customer’s wish list
items_count Int The number of items in the wish list
id ID The unique identifier of the wish list
sharing_code String An encrypted code that Magento uses to link to the wish list
updated_at String The time of the last modification to the wish list

WishlistItem attributes

Attribute Data type Description
added_at String The time when the customer added the item to the wish list
description String The customer’s comment about this item
id Int The wish list item ID
product ProductInterface The ProductInterface contains attributes that are common to all types of products. Note that descriptions may not be available for custom and EAV attributes
qty Float The quantity of this wish list item

Store credit attributes

In Magento Commerce, the merchant can assign store credit to customers. Magento maintains the history of all changes to the balance of store credit available to the customer. The customer must be logged in to access the store credit history and balance.

Store credits must be enabled to return store credit attributes. If store credits are disabled after previously being enabled, the query returns the customer’s current balance as null.

Attribute Data Type Description
store_credit CustomerStoreCredit Contains the store credit information for the logged-in customer

CustomerStoreCredit attributes

The store_credit object contains store credit information, including the balance and history.

Attribute Data Type Description
balance_history CustomerStoreCreditHistory Lists changes to the amount of store credit available to the customer. If the history or store credit feature is disabled, then a null value will be returned.

You can specify the following optional parameters to control paging in the output.

pageSize - An integer that specifies the maximum number of results to return at once. The default value is 20.

currentPage - An integer that specifies which page of the results to return. The default value is 1
current_balance Money The current store credit balance
enabled Boolean Indicates whether store credits are enabled. If the feature is disabled, then the balance will not be returned

CustomerStoreCreditHistory attributes

The CustomerStoreCreditHistory object contains an array of store credit items and paging information. If the store credit or store credit history feature is disabled, then a null value will be returned.

Attribute Data Type Description
items [CustomerStoreCreditHistoryItem] An array of products that match the specified search criteria
page_info SearchResultPageInfo An object that includes the page_size and current_page values specified in the query
total_count Int The number of items returned

CustomerStoreCreditHistoryItem attributes

The CustomerStoreCreditHistoryItem object contains information about a specific change to the customer’s store credit.

Attribute Data Type Description
action String The action taken on the customer’s store credit
actual_balance Money The store credit available to the customer as a result of this action
balance_change Money The amount added to or subtracted from the store credit as a result of this action
date_time_changed String Date and time when the store credit change was made
© 2020 Magento. All rights reserved.