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

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:

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
91

{
  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
          eligible_for_return
        }
        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
88

{
  "data": {
    "customer": {
      "orders": {
        "total_count": 1,
        "items": [
          {
            "id": "MQ==",
            "number": "000000001",
            "order_date": "2020-11-14 22:25:48",
            "status": "Processing",
            "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,
                "eligible_for_return": true
              }
            ],
            "carrier": "Flat Rate",
            "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 lists. Magento Commerce allows customers to have multiple wish lists.

Request:

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

{
  customer {
    wishlists {
      id
      name
      items_count
      items_v2 {
        items {
          id
          product {
            uid
            name
            sku
          }
        }
      }
    }
  }
}

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
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

{
  "data": {
    "customer": {
      "wishlists": [
        {
          "id": "1",
          "name": "Vacation Wants",
          "items_count": 10,
          "items_v2": {
            "items": [
              {
                "id": "1",
                "product": {
                  "uid": "MTM=",
                  "name": "Overnight Duffle",
                  "sku": "24-WB07"
                }
              },
              {
                "id": "2",
                "product": {
                  "uid": "MTA=",
                  "name": "Savvy Shoulder Tote",
                  "sku": "24-WB05"
                }
              },
              {
                "id": "3",
                "product": {
                  "uid": "MTE=",
                  "name": "Endeavor Daytrip Backpack",
                  "sku": "24-WB06"
                }
              },
              {
                "id": "4",
                "product": {
                  "uid": "MTA5OA==",
                  "name": "Miko Pullover Hoodie",
                  "sku": "WH04"
                }
              },
              {
                "id": "5",
                "product": {
                  "uid": "MTIyNg==",
                  "name": "Stellar Solar Jacket",
                  "sku": "WJ01"
                }
              },
              {
                "id": "6",
                "product": {
                  "uid": "MTcyMg==",
                  "name": "Nora Practice Tank",
                  "sku": "WT03"
                }
              },
              {
                "id": "7",
                "product": {
                  "uid": "MTY5MA==",
                  "name": "Bella Tank",
                  "sku": "WT01"
                }
              },
              {
                "id": "17",
                "product": {
                  "uid": "MTg=",
                  "name": "Pursuit Lumaflex™ Tone Band",
                  "sku": "24-UG02"
                }
              },
              {
                "id": "18",
                "product": {
                  "uid": "MQ==",
                  "name": "Joust Duffle Bag",
                  "sku": "24-MB01"
                }
              },
              {
                "id": "20",
                "product": {
                  "uid": "NTI=",
                  "name": "Sprite Yoga Companion Kit",
                  "sku": "24-WG080"
                }
              }
            ]
          }
        },
        {
          "id": "2",
          "name": "Lose the Muffintop",
          "items_count": 5,
          "items_v2": {
            "items": [
              {
                "id": "8",
                "product": {
                  "uid": "NDk=",
                  "name": "Advanced Pilates & Yoga (Strength)",
                  "sku": "240-LV08"
                }
              },
              {
                "id": "10",
                "product": {
                  "uid": "MTQ1MA==",
                  "name": "Layla Tee",
                  "sku": "WS04"
                }
              },
              {
                "id": "11",
                "product": {
                  "uid": "MTU2Mg==",
                  "name": "Radiant Tee",
                  "sku": "WS12"
                }
              },
              {
                "id": "12",
                "product": {
                  "uid": "MTYxMA==",
                  "name": "Electra Bra Top",
                  "sku": "WB01"
                }
              },
              {
                "id": "13",
                "product": {
                  "uid": "MTY0Mg==",
                  "name": "Celeste Sports Bra",
                  "sku": "WB03"
                }
              }
            ]
          }
        }
      ]
    }
  }
}

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
allow_remote_shopping_assistance Boolean! Indicates whether the customer has enabled remote shopping assistance
compare_list CompareList The contents of the customer’s comparison list
created_at String Timestamp indicating when the account was created
date_of_birth String The customer’s date of birth. In keeping with current security and privacy best practices, be sure you are aware of any potential legal and security risks associated with the storage of customers’ full date of birth (month, day, year) along with other personal identifiers, such as full name, before collecting or processing such data.
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
orders(filter CustomerOrdersFilterInput, currentPage = 1 Int, pageSize = 20 Int) CustomerOrders A list of the customer’s placed orders. See orders input attributes for details
prefix String An honorific, such as Dr., Mr., or Mrs.
return(uid: ID!) Return Gets details about the specified return request
returns(pageSize: Int = 20 currentPage: Int = 1) Returns Information about the customer’s return requests
reviews(pageSize: Int = 20 currentPage: Int = 1) ProductReviews! The list of reviews of the product
reward_points RewardPoints Details about the customer’s reward points
suffix String A value such as Sr., Jr., or III
taxvat String The customer’s Tax/VAT number (for corporate customers)
wishlist Wishlist! Deprecated. Use wishlist_v2 instead. Contains the contents of the customer’s wish lists
wishlist_v2(id ID!) Wishlist! Retrieve the specified wish list identified by the unique ID for a Wishlist object

For B2B, company administrators and users can have the following attributes.

Attribute Data Type Description
job_title String The job title for a B2B company user
requisition_lists (pageSize = 20 Int, currentPage = 1 Int, filter RequisitionListFilterInput) RequisitionLists Contains the customer’s requisition lists
role CompanyRole The role name and permissions assigned to the company user
status CompanyUserStatusEnum Indicates whether the company user is ACTIVE or INACTIVE
team CompanyTeam The team the company user is assigned to
telephone String The phone number of the company user

CompareList attributes

The CompareList object can contain the following attributes:

Attribute Data Type Description
attributes [ComparableAttribute] An array of attributes that can be used for comparing products
item_count Int! The number of items in the comparison lists
items [ComparableItem] An array of products to compare
uid ID! The unique ID of a CompareList object

ComparableAttribute attributes

The ComparableAttribute object lists the attributes that are available for comparisons:

Attribute Data Type Description
code String! An attribute code that is enabled for product comparisons
label String! The label of the attribute code

ComparableItem attributes

The ComparableItem object lists items that have been added to the comparison list:

Attribute Data Type Description
attributes [ProductAttribute]! An array of product attributes that can be used to compare products
product ProductInterface! Contains details about a product in a comparison list
uid ID! The unique ID of a ComparableItem object

ProductAttribute object

The ProductAttribute object outputs item data from the corresponding attribute:

Attribute Data Type Description
code String! The unique identifier for a product attribute code
label String! The display value of the attribute

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

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:

Attribute Data type Description
filter CustomerOrdersFilterInput Defines the criteria to search for. If no filter is specified, the query returns and paginates all of the customer’s orders
currentPage Int Specifies which page of results to return. The default value is 1
pageSize Int Specifies the maximum number of results to return at once. The default value is 20

The customers query returns a CustomerOrders object.

CustomerOrdersFilterInput attributes

Attribute Data type Description
number FilterStringTypeInput Filter orders by order number

FilterStringTypeInput attributes

The FilterStringTypeInput object defines a filter for an input string.

Attribute Data type Description
eq String Filters items that are exactly the same as the specified string. For example, to filter on a specific order number, specify a value like 5
in [String] Filters items that are exactly the same as entries specified in an array of strings. For example, to filter on order number 4, 5, and 6, specify a value of ["4", "5", "6"]
match String Defines a filter that performs a fuzzy search on the specified string. For example, if you specify a value of 20, the query returns all order IDs that contain the string 20

orders output attributes (CustomerOrders)

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

Attribute Data type Description
items [CustomerOrder]! An array of items in an order
page_info SearchResultPageInfo An object that includes the current_page, page_info, and page_size values specified in the query
total_count Int The total count of customer orders

CustomerOrder attributes

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

Attribute Data type Description
billing_address OrderAddress The billing address for the order
carrier String The shipping carrier for the order delivery
comments [SalesCommentItem] Comments on the order
created_at String Deprecated. Use the order_date attribute instead
credit_memos [CreditMemo] Contains a list of credit memos for the order
gift_message GiftMessage The entered gift message for the order
gift_receipt_included Boolean! Indicates if the customer requested a gift receipt for the order
gift_wrapping GiftWrapping The selected gift wrapping for the order
grand_total Float Deprecated. Use the totals.grand_total attribute instead
id ID! Unique identifier for the order
increment_id String Deprecated. Use the id attribute instead
invoices [Invoice]! Contains a list of invoices for the order
items [OrderItemInterface] An array containing the items purchased in this order
items_eligible_for_return [OrderItemInterface] A list of order items eligible to be in a return request
number String! The order number
order_date String! The date the order was placed
order_number String! Deprecated. Use the number attribute instead
payment_methods [PaymentMethod] Payment details for the order
printed_card_included Boolean! Indicates if the customer requested a printed card for the order
returns (pageSize = 20 Int, currentPage = 1 Int) Returns Return requests associated with this order
shipments [OrderShipment] Shipment list for the order
shipping_address OrderAddress Shipping address for the order
shipping_method String Shipping method for the order
status String! The current status of the order
total OrderTotal Contains details about the calculated totals for this order

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.

Attribute Data type Description
comments [SalesCommentItem] Comments on the credit memo
id ID! The unique ID of the CreditMemo object
items [CreditMemoItemInterface] An array containing details about refunded items
number String! The sequential credit memo number
total CreditMemoTotal Contains details about the total refunded amount

CreditMemoItemInterface attributes

CreditMemoItemInterface defines the following attributes.

Attribute Data type Description
discounts [Discount] Contains information about the final discount amount for the base product, including discounts on options
id ID! The unique ID of the credit memo item
order_item OrderItemInterface The order item the credit memo is applied to
product_name String The name of the base product
product_sale_price Money! The sale price for the base product, including selected options
product_sku String! The SKU of the base product
quantity_refunded Float The number of refunded items

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.

Attribute Data type Description
adjustment Money! An adjustment manually applied to the order
base_grand_total Money! The final base grand total amount in the base currency
discounts [Discount] The applied discounts to the order
grand_total Money! The final total amount, including shipping, discounts, and taxes
shipping_handling ShippingHandling Contains details about the shipping and handling costs for the credit memo
subtotal Money! The subtotal of the order, excluding shipping, discounts, and taxes
taxes [TaxItem]! An array containing information about taxes on individual orders
total_shipping Money! The shipping amount for the credit memo
total_tax Money! The amount of tax applied to all orders

Discount attributes

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

Attribute Data type Description
amount Money! The amount of the discount
label String! A description of the discount

GiftMessage attributes

The GiftMessage object can contain the following attributes.

Attribute Data Type Description
from String! The name of the gift sender
message String! The text of the gift message
to String! The name of the gift recipient

GiftWrapping attributes

The GiftWrapping object can contain the following attributes.

Attribute Data Type Description
design String! The name of the gift wrapping design
id ID! Deprecated. Use uid instead. The unique identifier for the gift wrapping option
image GiftWrappingImage The preview image for the gift wrapping option
price Money! The price of the gift wrapping option
uid ID! The unique identifier for the GiftWrapping object

GiftWrappingImage object

The GiftWrappingImage object must contain the following attributes.

Attribute Data Type Description
label String! The label of the gift wrapping preview image
url String! The URL of the gift wrapping preview image

Invoice attributes

The Invoice object provides details about a customer invoice.

Attribute Data type Description
comments [SalesCommentItem] Comments on the invoice
id ID! The internal ID of the Invoice object
items [InvoiceItemInterface]! Contains details about invoiced products
number String! The sequential number of the invoice
total InvoiceTotal! Invoice total amount details

InvoiceItemInterface

InvoiceItemInterface defines the following attributes.

Attribute Data type Description
discounts [Discount] Contains information about the final discount amount for the base product, including discounts on options
id ID! The unique ID of the invoice item
order_item OrderItemInterface Contains details about an individual order item
product_name String The name of the base product
product_sale_price Money! The sale price for the base product including selected options
product_sku String! The SKU of the base product
quantity_invoiced Float The number of invoiced items

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.

Attribute Data type Description
base_grand_total Money! The final base grand total amount in the base currency
discounts [Discount] The applied discounts to the invoice
grand_total Money! The final total amount, including shipping, discounts, and taxes
shipping_handling ShippingHandling Contains details about the shipping and handling costs for the invoice
subtotal Money! The subtotal of the invoice, excluding shipping, discounts, and taxes
taxes [TaxItem] An array containing information about taxes on individual invoices
total_shipping Money! The shipping amount for the invoice
total_tax Money! The amount of tax applied to all invoices

ItemSelectedBundleOption attributes

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

Attribute Data type Description
id ID! The unique identifier of the ItemSelectedBundleOption object
label String! The label of the option
values [ItemSelectedBundleOptionValue!]! A list of products that represent the values of the parent option

ItemSelectedBundleOptionValue attributes

Attribute Data type Description
id ID! The unique identifier of the ItemSelectedBundleOptionValue object
price Money! The price of the child bundle product
product_name String! The name of the child bundle product
product_sku String! The SKU of the child bundle product
quantity Float! Indicates how many of this bundle product were ordered

KeyValue attributes

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

Attribute Data type Description
name String The name part of the name/value pair
value String The value part of the name/value pair

OrderAddress attributes

The OrderAddress object can contain 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
fax String The fax number
firstname String! The first name of the person associated with the shipping/billing address
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 String The state or province name
region_id ID 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)

OrderItemInterface

OrderItemInterface defines the following attributes.

Attribute Data Type Description
discounts [Discount] Final discount information for the product
entered_options [OrderItemOption] The entered option for the base product, such as a logo or image
id ID! The unique identifier for the order item
product_name String The name of the base product
product_sale_price Money! The sale price of the base product, including selected options
product_sku String! SKU of the base product
product_type String The type of product, such as simple or configurable
product_url_key String URL key of the base product
quantity_canceled Float The number of canceled items
quantity_invoiced Float The number of invoiced items
quantity_ordered Float The number of units ordered for this item
quantity_refunded Float The number of refunded items
quantity_returned Float The number of returned items
quantity_shipped Float The number of shipped items
selected_options [OrderItemOption] The selected options for the base product, such as color or size
status String The status of the order item

OrderItemOption attributes

Attribute Data type Description
label String! The name of the option
value String! The value of the option

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

OrderItemOption attributes

Attribute Data type Description
label String! The name of the option
value String! The value of the option

OrderShipment attributes

Attribute Data type Description
comments [SalesCommentItem] Comments added to the shipment
id ID! The unique ID of the OrderShipment object
items [ShipmentItemInterface] Contains items included in the shipment
number String! The sequential credit shipment number
tracking [ShipmentTracking] Contains shipment tracking detail

OrderTotal attributes

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

Attribute Data type Description
base_grand_total Money! The final base grand total amount in the base currency
discounts [Discount] The applied discounts to the order
grand_total Money! The final total amount, including shipping, discounts, and taxes
shipping_handling ShippingHandling The shipping and handling costs for the order
subtotal Money! The subtotal of the order, excluding shipping, discounts, and taxes
taxes [TaxItem]! An array containing information about taxes on individual orders
total_shipping Money! The shipping costs for the order
total_tax Money! The amount of tax applied to the order

PaymentMethod attributes

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

Attribute Data type Description
additional_data [KeyValue] Additional data per payment method type
name String! The label that describes the payment method
type String! The payment method code that indicates how the order was paid for

RewardPoints attributes

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

Attribute Data type Description
balance RewardPointsAmount The current balance of reward points
balance_history [RewardPointsBalanceHistoryItem] The balance history of reward points. If the ability for customers to view the balance history has been disabled in the Admin, this field will be set to null
exchange_rates RewardPointsExchangeRates The current exchange rates for reward points
subscription_status RewardPointsSubscriptionStatus The subscription status of emails related to reward points

RewardPointsAmount attributes

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

Attribute Data type Description
money Money! The amount of reward points, expressed in the currency of the store
points Float! The amount of reward points, expressed in points

RewardPointsBalanceHistoryItem

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

Attribute Data type Description
balance RewardPointsAmount Reward points balance after the completion of the transaction
change_reason String! The reason the balance changed
date String! Transaction date
points_change Float! The number of points added or deducted in the transaction

RewardPointsExchangeRates attributes

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

Attribute Data type Description
earning RewardPointsRate The number of points earned for the amount spent
redemption RewardPointsRate The number points must be redeemed to get a currency discount at checkout

RewardPointsRate attributes

The RewardPointsRate object contains details about reward points exchange rates.

Attribute Data type Description
currency_amount Float! The monetary value of the exchange rate. For earnings, this is amount spent to earn the specified points. For redemptions, this is the amount of money the number of points represents
points Float! The number of points for the exchange rate. For earnings, this is the number of points earned. For redemptions, this is the number of points needed for to redeem points

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.

Attribute Data type Description
balance_updates RewardPointsSubscriptionStatusesEnum! Customer subscription status to ‘Reward points balance updates’ emails
points_expiration_notifications RewardPointsSubscriptionStatusesEnum! Customer subscription status to ‘Reward points expiration notifications’ emails

SalesCommentItem attributes

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

Attribute Data type Description
message String! The text of the message
timestamp String! The timestamp of the comment

SalesItemOption attributes

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

Attribute Data type Description
id String! The name of the option
value String! The value of the option

SearchResultPageInfo attributes

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

Attribute Data type Description
current_page Int Specifies which page of results to return
page_size Int Specifies the maximum number of items to return
total_pages Int Total pages

ShipmentItemInterface attributes

ShipmentItemInterface defines the following attributes.

Attribute Data type Description
id ID! The unique ID of the shipment item
order_item OrderItemInterface The shipped order item
product_name String The name of the base product
product_sale_price Money! The sale price for the base product
product_sku String! The SKU of the base product
quantity_shipped Float! The number of shipped items

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.

Attribute Data type Description
carrier String! The shipping carrier for the order delivery
number String The tracking number of the order shipment
title String! The shipment tracking title

ShippingDiscount attributes

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

Attribute Data type Description
amount Money! The amount of the discount

ShippingHandling attributes

The ShippingHandling object provides details about shipping and handling charges.

Attribute Data type Description
amount_excluding_tax Money The shipping amount, excluding tax
amount_including_tax Money The shipping amount, including tax
discounts [ShippingDiscount] The applied discounts to the shipping
taxes [TaxItem] Contains details about taxes applied for shipping
total_amount Money! The total amount for shipping

TaxItem attributes

Attribute Data type Description
amount Money! The amount of tax applied to an order
rate Float The tax rate applied to an order
title String! A label that describes the tax

ProductReview object

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

Attribute Data Type Description
average_rating Float! The average rating for product review
created_at String! Date indicating when the review was created
nickname String! The customer’s nickname. Defaults to the customer name, if logged in
product ProductInterface! Contains details about the reviewed product
ratings_breakdown [ProductReviewRating!]! An array of ratings by rating category, such as quality, price, and value
summary String! The summary (title) of the review
text String! The review text

ProductReviewRating attributes

The ProductReviewRating object contains the following attributes.

Attribute Data Type Description
name String! The label assigned to an aspect of a product that is being rated, such as quality or price
value String! The rating value given by customer. By default, possible values range from 1 to 5

ProductReviews object

ProductReviews contains an array of reviews written about the product.

Attribute Data Type Description
items [ProductReview]! An array of product reviews
page_info SearchResultPageInfo! Metadata for pagination rendering

Return attributes

The Return object can contain the following attributes:

Attribute Data Type Description
available_shipping_carriers [ReturnShippingCarrier] A list of shipping carriers available for returns
comments [ReturnComment] A list of comments posted for the return request
created_at String! The date the return was requested
customer_email String! Email of the person who created the return request
customer ReturnCustomer The name of the person who requested the return
items [ReturnItem] A list of items being returned
number String! Human-readable return number
order CustomerOrder The order associated with the return
shipping ReturnShipping Shipping information for the return
status ReturnStatus An enum indicating the status of the return request. Possible values are APPROVED, AUTHORIZED, CLOSED, DENIED, PARTIALLY_APPROVED, PARTIALLY_AUTHORIZED, PARTIALLY_RECEIVED, PARTIALLY_REJECTED, PENDING, PROCESSED_AND_CLOSED, RECEIVED, and REJECTED
uid ID! The unique ID of a Return object

ReturnComment attributes

The ReturnComment object provides details about an individual comment in a refund request. Comments can be added by a customer or the merchant.

Attribute Data Type Description
author_name String! The name or author who posted the comment
created_at String! The date and time the comment was posted
text String! The contents of the comment
uid ID! The unique ID of a ReturnComment object

ReturnCustomAttribute attributes

Attribute Data Type Description
label String! A description of the attribute
uid ID! The unique ID of a ReturnCustomAttribute attribute
value String! A JSON-encoded value of the attribute

ReturnCustomer attributes

The ReturnCustomer object contains information about the person requesting a return.

Attribute Data Type Description
email String! The email address of the refund requester
firstname String The first name of the refund requester
lastname String The last name of the refund requester

ReturnItem attributes

The ReturnItem object provides details about an individual item in a return request.

Attribute Data Type Description
custom_attributes [ReturnCustomAttribute] Return item custom attributes that are visible on the storefront
order_item OrderItemInterface! Provides access to the product being returned, including information about selected and entered options
quantity Float! The quantity of the item the merchant authorized to be returned
request_quantity Float! The quantity of the item requested to be returned
status ReturnItemStatus! An enum indicating the return status of the item. Possible values are APPROVED, AUTHORIZED, DENIED, PENDING, RECEIVED, and REJECTED
uid ID! The unique ID of an item of a Return object

ReturnShipping attributes

The ReturnShipping object can contain the merchant’s shipping address and tracking information.

Attribute Data Type Description
address ReturnShippingAddress The merchant-defined return shipping address
tracking(uid: ID) [ReturnShippingTracking] The unique ID for a ReturnShippingTracking object. If a single UID is specified, contains a single tracking record. Otherwise, contains all tracking information

ReturnShippingAddress attributes

The ReturnShippingAddress object defines the merchant address for receiving returned items.

Attribute Data Type Description
city String! The city for product returns
contact_name String The merchant’s contact person
country Country! An object that defines the country for product returns
postcode String! The postal code for product returns
region Region! An object that defines the state or province for product returns
street [String]! The street address for product returns
telephone String The telephone number for product returns

ReturnShippingCarrier attributes

The ReturnShippingCarrier object contains details about the shipping carrier used to return a product.

Attribute Data Type Description
label String! A description of the shipping carrier
uid ID! The unique ID of a ReturnShippingCarrier object

ReturnShippingTracking attributes

The ReturnShippingTracking object contains tracking information for an approved return.

Attribute Data Type Description
carrier ReturnShippingCarrier! Contains details of a shipping carrier
status ReturnShippingTrackingStatus Contains details about the status of a shipment
tracking_number String! A tracking number assigned by the carrier
uid ID! The unique ID assigned of a ReturnShippingTracking object

ReturnShippingTrackingStatus attributes

The ReturnShippingTrackingStatus object contains tracking status information for an approved return.

Attribute Data Type Description
text String! Text that describes the status
type ReturnShippingTrackingStatusType! An enum indicating whether the status type is INFORMATIONAL or an ERROR

Returns attributes

The Returns object contains an array of Return objects.

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

Wishlist attributes

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

Attribute Data type Description
id ID The unique ID of a Wishlist object
items [WishlistItem] Deprecated. Use items_v2 instead
items_v2 [WishlistItemInterface] An array of items in the customer’s wish list
items_count Int The number of items in the wish list
name String The wish list name. Applicable to Magento Commerce only
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
visibility WishlistVisibilityEnum! An enum indicating whether the wish list is PUBLIC or PRIVATE. Applicable to Magento Commerce only

WishlistItem attributes

The WishlistItem object can contain the following 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

B2B output attributes

If B2B is installed the Customer object can contain additional information.

RequisitionListFilterInput attributes

The RequisitionListFilterInput object defines filters that limit the number of requisition lists returned.

Attribute Data Type Description
name FilterMatchTypeInput Filter by the display name of the requisition list
uids FilterEqualTypeInput Filter requisition lists by one or more requisition list IDs

RequisitionList attributes

The RequisitionList object contains the following attributes.

Attribute Data Type Description
description String Optional text that describes the requisition list
items RequistionListItems An array of products added to the requisition list
items_count Int! The number of items in the list
name String! The requisition list name
uid ID! The unique requisition list ID
updated_at String The time of the last modification of the requisition list

RequistionListItems attributes

The RequistionListItems object contains the following attributes.

Attribute Data Type Description
items [RequisitionListItemInterface]! An array of items in the requisition list
page_info SearchResultPageInfo Contains pagination metadata
total_pages Int! The number of pages returned

RequisitionLists attributes

The RequisitionLists object contains an array of requisition lists.

Attribute Data Type Description
items [RequisitionList] An array of requisition lists
page_info SearchResultPageInfo Contains pagination metadata
total_count Int The number of returned requisition lists
© 2021 Magento. All rights reserved.