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

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, 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.