Customer
Represents a customer, providing access to their personal, account, and order information.
Type Definition
type Customer {
id: Int
customerNumber: String
name: String
address: Address
tags: [String]
hasAccess: Boolean
username: String
firstName: String
lastName: String
language: Locale
currency: Currency
acceptsMarketing: Boolean
orderCount: Int
orderTotal: Float
refundCount: Int
refundTotal: Float
firstOrderDate: String
lastOrderDate: String
audiences: [String]
loyaltyDiscountProgress: LoyaltyDiscountProgress
}
Fields
Field | Type | Nullable | Description | Relationship |
---|---|---|---|---|
id | Int | Yes | Unique identifier for the customer. | — |
customerNumber | String | Yes | The customer number assigned to this customer. | — |
name | String | Yes | The full name of the customer. | — |
address | Address | Yes | The customer’s address information. | Links to Address type |
tags | [String] | Yes | The tags associated with the customer. | — |
hasAccess | Boolean | Yes | Indicates if the customer has access rights to the store. | — |
username | String | Yes | The username of the customer. | — |
firstName | String | Yes | The first name of the customer. | — |
lastName | String | Yes | The last name of the customer. | — |
language | Locale | Yes | The customer’s language/locale information. | Links to Locale type |
currency | Currency | Yes | The customer’s preferred currency. | Links to Currency type |
acceptsMarketing | Boolean | Yes | Indicates if the customer has accepted marketing communications. | — |
orderCount | Int | Yes | The total number of orders placed by the customer. | — |
orderTotal | Float | Yes | The total amount spent by the customer on orders. | — |
refundCount | Int | Yes | The total number of refunds issued to the customer. | — |
refundTotal | Float | Yes | The total amount refunded to the customer. | — |
firstOrderDate | String | Yes | The date and time of the customer’s first order, in RFC 2822 format. | — |
lastOrderDate | String | Yes | The date and time of the customer’s most recent order, in RFC 2822 format. | — |
audiences | [String] | Yes | The names of the audiences or segments the customer belongs to. | — |
loyaltyDiscountProgress | LoyaltyDiscountProgress | Yes | Returns the progress of the customer towards the next loyalty discount in a GraphQL compatible format. | Links to LoyaltyDiscountProgress type |
Relationships
- address: Connects the customer to their
Address
object, which contains detailed address information. - language: Links to the
Locale
type, representing the customer’s language and locale preferences. - currency: Connects to the
Currency
type, indicating the customer’s preferred currency for transactions. - loyaltyDiscountProgress: Provides access to the
LoyaltyDiscountProgress
object, showing the customer’s progress toward loyalty discounts.
These relationships enable nested queries to retrieve comprehensive customer-related data efficiently.
Usage Examples
Basic Query
{
customer(id: 12345) {
id
customerNumber
name
email
}
}
Note: The email
field is not defined on the Customer type and thus is excluded from this API.
Field Selection
{
customer(id: 12345) {
id
firstName
lastName
username
acceptsMarketing
orderCount
orderTotal
}
}
Nested Queries
{
customer(id: 12345) {
id
name
address {
street
city
postalCode
country
}
language {
code
name
}
currency {
code
symbol
}
loyaltyDiscountProgress {
currentPoints
pointsNeeded
discountPercentage
}
}
}
Filtering and Sorting
Note: The Customer
type itself does not define filtering or sorting fields directly. These operations are typically applied at the query level when retrieving lists of customers.
Example of filtering customers by tag and sorting by lastOrderDate
might look like this in a query that supports it:
{
customers(filter: { tags_contains: "vip" }, sort: LAST_ORDER_DATE_DESC, first: 10) {
edges {
node {
id
name
lastOrderDate
}
}
}
}
This example assumes the existence of a customers
connection field with filtering and sorting capabilities.
Implements
The Customer
type does not explicitly implement any interfaces in the provided schema.
Connections
The Customer
type is referenced by the following objects:
Cart.customer
— The customer associated with a shopping cart.Comment.customer
— The customer who made a comment.Review.customer
— The customer who wrote a review.
These connections allow traversal from these objects back to detailed customer information.
Related Types
- Address: Represents the customer’s address details.
- Locale: Represents language and locale information.
- Currency: Represents currency preferences.
- LoyaltyDiscountProgress: Represents the customer’s progress toward loyalty discounts.
- [String]: Used for tags and audiences fields.
Best Practices
- Selective Field Queries: Query only the fields you need to optimize response size and performance.
- Use Nested Queries: Leverage nested queries to fetch related objects like
address
,language
, andcurrency
in a single request. - Handle Optional Fields: All fields are optional; always check for
null
values in your client code. - Pagination and Filtering: When querying lists of customers (outside this type), use filtering and pagination to efficiently manage large datasets.
- Monitor Order and Refund Fields: Use
orderCount
,orderTotal
,refundCount
, andrefundTotal
for customer analytics and segmentation. - Leverage Loyalty Data: Use
loyaltyDiscountProgress
to personalize marketing and reward programs.
Notes
- All date fields such as
firstOrderDate
andlastOrderDate
are returned in RFC 2822 format. Ensure your client parses these correctly. - The
loyaltyDiscountProgress
field returns a GraphQL-compatible object representing computed progress toward loyalty discounts; this is a derived field. - The API currently requires no authentication, but this may change in future versions. Plan your integration accordingly.
- Because all fields are optional, expect some fields to be
null
depending on the customer’s data completeness. - Avoid over-fetching nested objects if not needed to reduce response payload and improve performance.
- Use caching strategies on the client side when querying static or infrequently changing customer data to reduce load and latency.
This documentation is designed to help developers of all skill levels understand and work effectively with the Customer
GraphQL object type.