customer query

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

Retrieve basic information about 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"
        }
      ]
    }
  }
}

Retrieve a summary of the customer’s order history

The following example returns a summary of the logged-in customer’s previous orders.

Request:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
query {
  customer {
    orders(
      pageSize: 20
    ) {
      items {
        id
        order_date
        total {
          grand_total {
            value
            currency
          }
        }
        status
      }
    }
  }
}

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
62
63
64
65
{
  "data": {
    "customer": {
      "orders": {
        "items": [
          {
            "id": "MQ==",
            "order_date": "2020-03-18 17:25:20",
            "total": {
              "grand_total": {
                "value": 36.39,
                "currency": "USD"
              }
            },
            "status": "Complete"
          },
          {
            "id": "Mg==",
            "order_date": "2020-03-18 17:25:20",
            "total": {
              "grand_total": {
                "value": 39.64,
                "currency": "USD"
              }
            },
            "status": "Closed"
          },
          {
            "id": "Mw==",
            "order_date": "2020-03-21 22:41:38",
            "total": {
              "grand_total": {
                "value": 205.68,
                "currency": "USD"
              }
            },
            "status": "Pending"
          },
          {
            "id": "NA==",
            "order_date": "2020-08-03 02:35:35",
            "total": {
              "grand_total": {
                "value": 159.13,
                "currency": "USD"
              }
            },
            "status": "Complete"
          },
          {
            "id": "NQ==",
            "order_date": "2020-09-08 03:57:11",
            "total": {
              "grand_total": {
                "value": 132.57,
                "currency": "USD"
              }
            },
            "status": "Complete"
          }
        ]
      }
    }
  }
}

Retrieve detailed information about a specific order

The following example returns details about one of the customer’s previous orders.

These topics contain examples with fragments and provide even more details:

• CreditMemoItemInterface attributes and implementations
• InvoiceItemInterface attributes and implementations
• OrderItemInterface attributes and implementations
• ShipmentItemInterface attributes and implementations

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
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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
{
  customer {
    orders(filter: {number: {eq: "000000001"}}) {
      total_count
      items {
        id
        number
        order_date
        status
        items {
          product_name
          product_sku
          product_url_key
          product_sale_price {
            value
          }
          product_sale_price {
            value
            currency
          }
          quantity_ordered
          quantity_invoiced
          quantity_shipped
        }
        carrier
        shipments {
          id
          number
          items {
            product_name
            quantity_shipped
          }
        }
        total {
          base_grand_total {
            value
            currency
          }
          grand_total {
            value
            currency
          }
          total_tax {
            value
          }
          subtotal {
            value
            currency
          }
          taxes {
            amount {
              value
              currency
            }
            title
            rate
          }
          total_shipping {
            value
          }
          shipping_handling {
            amount_including_tax {
              value
            }
            amount_excluding_tax {
              value
            }
            total_amount {
              value
            }
            taxes {
              amount {
                value
              }
              title
              rate
            }
          }
          discounts {
            amount {
              value
              currency
            }
            label
          }
        }
      }
    }
  }
}

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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
{
  "data": {
    "customer": {
      "orders": {
        "total_count": 1,
        "items": [
          {
            "id": "MQ==",
            "carrier": "Flat Rate",
            "number": "000000001",
            "order_date": "2020-03-18 17:25:20",
            "status": "Complete",
            "items": [
              {
                "product_name": "Iris Workout Top",
                "product_sku": "WS03-XS-Red",
                "product_url_key": "iris-workout-top",
                "product_sale_price": {
                  "value": 29,
                  "currency": "USD"
                },
                "quantity_ordered": 1,
                "quantity_invoiced": 1,
                "quantity_shipped": 1
              }
            ],
            "shipments": [
              {
                "id": "MDAwMDAwMDAx",
                "number": "000000001",
                "items": [
                  {
                    "product_name": "Iris Workout Top",
                    "quantity_shipped": 1
                  }
                ]
              }
            ],
            "total": {
              "base_grand_total": {
                "value": 36.39,
                "currency": "USD"
              },
              "grand_total": {
                "value": 36.39,
                "currency": "USD"
              },
              "total_tax": {
                "value": 2.39
              },
              "subtotal": {
                "value": 29,
                "currency": "USD"
              },
              "taxes": [
                {
                  "amount": {
                    "value": 2.39,
                    "currency": "USD"
                  },
                  "title": "US-MI-*-Rate 1",
                  "rate": 8.25
                }
              ],
              "total_shipping": {
                "value": 5
              },
              "shipping_handling": {
                "amount_including_tax": {
                  "value": 5
                },
                "amount_excluding_tax": {
                  "value": 5
                },
                "total_amount": {
                  "value": 5
                },
                "taxes": []
              },
              "discounts": []
            }
          }
        ]
      }
    }
  }
}

Retrieve 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:

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:

CustomerAddressAttribute attributes

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

CustomerAddressRegion attributes

The customerAddressRegion output returns the following attributes:

orders input attributes

The orders attribute defines a filter that returns details about one or more of the logged-in customer’s previous orders. It takes the following attributes as input:

The customers query returns a CustomerOrders object.

CustomerOrdersFilterInput attributes

FilterStringTypeInput attributes

The FilterStringTypeInput object defines a filter for an input string.

orders output attributes (CustomerOrders)

The CustomerOrders object contains the results of the filter defined in the orders attribute.

CustomerOrder attributes

The CustomerOrder object contains details about each order returned by the orders attribute.

The deprecated attributes were previously defined in the CustomerOrder object in the customerOrders query, but have been deprecated for the customer query.

CreditMemo attributes

The CreditMemo object contains details about credit memos applied to an order.

CreditMemoItemInterface attributes

CreditMemoItemInterface defines the following attributes.

CreditMemoItemInterface attributes and implementations provides additional information about the implementations of this interface.

CreditMemoTotal attributes

The CreditMemoTotal object contains details about the totals of a credit memo.

Discount attributes

The Discount object contains a description of a discount and the amount.

GiftMessage attributes

The GiftMessage object can contain the following attributes.

GiftWrapping attributes

The GiftWrapping object can contain the following attributes.

GiftWrappingImage object

The GiftWrappingImage object must contain the following attributes.

Invoice attributes

The Invoice object provides details about a customer invoice.

InvoiceItemInterface

InvoiceItemInterface defines the following attributes.

InvoiceItemInterface attributes and implementations provides additional information about the implementations of this interface.

InvoiceItemInterface is implemented by the InvoiceItem and BundleInvoiceItem data types.

InvoiceTotal attributes

The InvoiceTotal object contains details about the totals of an invoice.

ItemSelectedBundleOption attributes

The ItemSelectedBundleOption object contains a list of bundle options that are assigned to the bundle product.

ItemSelectedBundleOptionValue attributes

KeyValue attributes

The KeyValue object defines key/attribute pairs that are passed to or from the payment processor.

OrderAddress attributes

The OrderAddress object can contain the following attributes:

OrderItemInterface

OrderItemInterface defines the following attributes.

OrderItemOption attributes

OrderItemInterface attributes and implementations provides additional information about the implementations of this interface.

OrderItemOption attributes

OrderShipment attributes

OrderTotal attributes

The OrderTotal object contains details about the sales total amounts used to calculate the final price.

PaymentMethod attributes

The PaymentMethod data type contains details about the payment method used to pay for the order.

RewardPoints attributes

The RewardPoints object provides details about the customer’s reward points balance, history, and related information.

RewardPointsAmount attributes

The RewardPointsAmount object lists the customer’s current reward points balance.

RewardPointsBalanceHistoryItem

The RewardPointsBalanceHistoryItem object contains details about individual events in which the customer earned or redeemed reward points.

RewardPointsExchangeRates attributes

The RewardPointsExchangeRates object contains information needed to exchange reward points into the store’s currency. Exchange rates depend on the customer group.

RewardPointsRate attributes

The RewardPointsRate object contains details about reward points exchange rates.

RewardPointsSubscriptionStatus attributes

The RewardPointsSubscriptionStatus object indicates whether the customer is subscribed to newsletters that provide reward points balances and expiration notifications. The possible values of these attribtutes are NOT SUBSCRIBED and SUBSCRIBED.

SalesCommentItem attributes

The SalesCommentItem object contains details about a comment applied to an order.

SalesItemOption attributes

The SalesItemOption data type contains the ID and value for the selected or entered options.

SearchResultPageInfo attributes

The SearchResultPageInfo data type provides pagination for the items returned by the orders filter.

ShipmentItemInterface attributes

ShipmentItemInterface defines the following attributes.

ShipmentItemInterface attributes and implementations provides additional information about the implementations of this interface.

ShipmentTracking attributes

The ShipmentTracking object contains the shipping carrier name and other tracking details.

ShippingDiscount attributes

The ShippingDiscount object defines an individual discount that can be applied to shipping.

ShippingHandling attributes

The ShippingHandling object provides details about shipping and handling charges.

TaxItem attributes

ProductReviews object

ProductReviews contains an array of reviews written about the product.

ProductReview object

The ProductReview object contains details about a product review. It contains the following attributes.

ProductReviewRating attributes

The ProductReviewRating object contains the following attributes.

Wishlist attributes

WishlistItem attributes

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.

CustomerStoreCredit attributes

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

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.

CustomerStoreCreditHistoryItem attributes

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

Wishlist attributes

The Wishlist object contains all the items in the customer’s wish list.

WishlistItem attributes

The WishlistItem object can contain the following attributes.

Related topics

• isEmailAvailable query
• generateCustomerToken mutation
• createCustomer mutation
• createCustomerAddress mutation