Skip to Content

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

FieldTypeNullableDescriptionRelationship
idIntYesUnique identifier for the customer.
customerNumberStringYesThe customer number assigned to this customer.
nameStringYesThe full name of the customer.
addressAddressYesThe customer’s address information.Links to Address type
tags[String]YesThe tags associated with the customer.
hasAccessBooleanYesIndicates if the customer has access rights to the store.
usernameStringYesThe username of the customer.
firstNameStringYesThe first name of the customer.
lastNameStringYesThe last name of the customer.
languageLocaleYesThe customer’s language/locale information.Links to Locale type
currencyCurrencyYesThe customer’s preferred currency.Links to Currency type
acceptsMarketingBooleanYesIndicates if the customer has accepted marketing communications.
orderCountIntYesThe total number of orders placed by the customer.
orderTotalFloatYesThe total amount spent by the customer on orders.
refundCountIntYesThe total number of refunds issued to the customer.
refundTotalFloatYesThe total amount refunded to the customer.
firstOrderDateStringYesThe date and time of the customer’s first order, in RFC 2822 format.
lastOrderDateStringYesThe date and time of the customer’s most recent order, in RFC 2822 format.
audiences[String]YesThe names of the audiences or segments the customer belongs to.
loyaltyDiscountProgressLoyaltyDiscountProgressYesReturns 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.

  • 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, and currency 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, and refundTotal for customer analytics and segmentation.
  • Leverage Loyalty Data: Use loyaltyDiscountProgress to personalize marketing and reward programs.

Notes

  • All date fields such as firstOrderDate and lastOrderDate 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.

Last updated on