Admin-API/ext/customer.graphql

# Represents information about a customer of the shop, such as the customer's contact details, their order
# history, and whether they've agreed to receive marketing material by email.
#
# Caution: Only use this data if it's required for your app's functionality.
# Shopify will restrict access to scopes for apps that don't have a legitimate use for the associated data.
type Customer implements CommentEventSubject&HasEvents&HasMetafieldDefinitions&HasMetafields&LegacyInteroperability&Node{
    # A list of addresses associated with the customer.
    addresses(first: Int): [MailingAddress!]!

    # The total amount that the customer has spent on orders in their lifetime.
    amountSpent: MoneyV2!

    # The average amount that the customer spent per order.
    averageOrderAmountV2: MoneyV2

    # Whether the merchant can delete the customer from their store.
    #
    # A customer can be deleted from a store only if they have not yet made an order. After a customer makes an
    # order, they can't be deleted from a store.
    canDelete: Boolean!

    # A list of the customer's company contact profiles.
    companyContactProfiles: [CompanyContact!]!

    # The date and time when the customer was added to the store.
    createdAt: DateTime!

    # The default address associated with the customer.
    defaultAddress: MailingAddress

    # The full name of the customer, based on the values for first_name and last_name. If the first_name and
    # last_name are not available, then this falls back to the customer's email address, and if that is not available, the customer's phone number.
    displayName: String!

    # The customer's email address.
    email: String

    # The current email marketing state for the customer.
    # If the customer doesn't have an email address, then this property is `null`.
    emailMarketingConsent: CustomerEmailMarketingConsentState

    # A list of events associated with the customer.
    events(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
        sortKey: EventSortKeys = ID
        query: String
    ): EventConnection!

    # The customer's first name.
    firstName: String

    # Whether the timeline subject has a timeline comment. If true, then a timeline comment exists.
    hasTimelineComment: Boolean!

    # A globally-unique identifier.
    id: ID!

    # The image associated with the customer.
    image: Image!

    # The customer's last name.
    lastName: String

    # The customer's last order.
    lastOrder: Order

    # The ID of the corresponding resource in the REST Admin API.
    legacyResourceId: UnsignedInt64!

    # The amount of time since the customer was first added to the store.
    #
    # Example: 'about 12 years'.
    lifetimeDuration: String!

    # The customer's locale.
    locale: String!

    # The market that includes the customer’s default address.
    market: Market

    # Returns a metafield by namespace and key that belongs to the resource.
    metafield(namespace: String!key: String!): Metafield

    # List of metafield definitions.
    metafieldDefinitions(
        namespace: String
        pinnedStatus: MetafieldDefinitionPinnedStatus = ANY
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
        sortKey: MetafieldDefinitionSortKeys = ID
        query: String
    ): MetafieldDefinitionConnection!

    # List of metafields that belong to the resource.
    metafields(
        namespace: String
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): MetafieldConnection!

    # A unique identifier for the customer that's used with Multipass login.
    multipassIdentifier: String

    # A note about the customer.
    note: String

    # The number of orders that the customer has made at the store in their lifetime.
    numberOfOrders: UnsignedInt64!

    # A list of the customer's orders.
    orders(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
        sortKey: OrderSortKeys = ID
        query: String
    ): OrderConnection!

    # A list of the customer's payment methods.
    paymentMethods(
        showRevoked: Boolean = false
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): CustomerPaymentMethodConnection!

    # The customer's phone number.
    phone: String

    # Returns a private metafield by namespace and key that belongs to the resource.
    privateMetafield(namespace: String!key: String!): PrivateMetafield

    # List of private metafields that belong to the resource.
    privateMetafields(
        namespace: String
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): PrivateMetafieldConnection!

    # Possible subscriber states of a customer defined by their subscription contracts.
    productSubscriberStatus: CustomerProductSubscriberStatus!

    # The current SMS marketing state for the customer's phone number.
    #
    # If the customer does not have a phone number, then this property is null.
    smsMarketingConsent: CustomerSmsMarketingConsentState

    # The state of the customer's account with the shop.
    state: CustomerState!

    # The statistics for a given customer.
    statistics: CustomerStatistics!

    # A list of the customer's subscription contracts.
    subscriptionContracts(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): SubscriptionContractConnection!

    # A comma separated list of tags that have been added to the customer.
    tags: [String!]!

    # Whether the customer is exempt from being charged taxes on their orders.
    taxExempt: Boolean!

    # The list of tax exemptions applied to the customer.
    taxExemptions: [TaxExemption!]!

    # The URL to unsubscribe the customer from the mailing list.
    unsubscribeUrl: URL!

    # The date and time when the customer was last updated.
    updatedAt: DateTime!

    # Whether the email address is formatted correctly.
    # Returns true when the email is formatted correctly and
    # belongs to an existing domain. This doesn't guarantee that
    # the email address actually exists.
    validEmailAddress: Boolean!

    # Whether the customer has verified their email address. Defaults to true if the customer is created through the Shopify admin or API.
    verifiedEmail: Boolean!
}

# Represents the data about a staff member's Shopify account.
# Merchants can use staff member data to get more information about the staff members in their store.
type StaffMember implements Node {
    # Whether the staff member is active.
    active: Boolean!

    # The image used as the staff member's avatar in the Shopify admin.
    avatar(fallback: StaffMemberDefaultImage = DEFAULT): Image!

    # The staff member's email address.
    email: String!

    # Whether the staff member's account exists.
    exists: Boolean!

    # The staff member's first name.
    firstName: String

    # A globally-unique identifier.
    id: ID!

    # The staff member's initials, if available.
    initials: [String!]

    # Whether the staff member is the shop owner.
    isShopOwner: Boolean!

    # The staff member's last name.
    lastName: String

    # The staff member's preferred locale. Locale values use the format language or language-COUNTRY, where language is a two-letter language code, and COUNTRY is a two-letter country code. For example: en or en-US
    locale: String!

    # The staff member's full name.
    name: String!

    # The staff member's phone number.
    phone: String

    # The data used to customize the Shopify admin experience for the staff member.
    privateData: StaffMemberPrivateData!
}

# Represents the data used to customize the Shopify admin experience for a logged-in staff member.
type StaffMemberPrivateData {
    # The URL to the staff member's account settings page.
    accountSettingsUrl: URL!

    # The date and time when the staff member was created.
    createdAt: DateTime!
}

# The record of when a customer consented to receive marketing material by email.
type CustomerEmailMarketingConsentState {
    # The date and time at which the customer consented to receive marketing material by email.
    # The customer's consent state reflects the consent record with the most recent consent_updated_at date.
    # If no date is provided, then the date and time at which the consent information was sent is used.
    consentUpdatedAt: DateTime

    # The marketing subscription opt-in level, as described by the M3AAWG best practices guidelines,
    # that the customer gave when they consented to receive marketing material by email.
    marketingOptInLevel: CustomerMarketingOptInLevel

    # The current email marketing state for the customer.
    marketingState: CustomerEmailMarketingState!
}

# The record of when a customer consented to receive marketing material by SMS.
#
# The customer's consent state reflects the record with the most recent date when consent was updated.
type CustomerSmsMarketingConsentState {
    # The source from which the SMS marketing information for the customer was collected.
    consentCollectedFrom: CustomerConsentCollectedFrom

    # The date and time when the customer consented to receive marketing material by SMS.
    # If no date is provided, then the date and time when the consent information was sent is used.
    consentUpdatedAt: DateTime

    # The marketing subscription opt-in level that was set when the customer consented to receive marketing information.
    marketingOptInLevel: CustomerMarketingOptInLevel!

    # The current SMS marketing state for the customer.
    marketingState: CustomerSmsMarketingState!
}

# A customer's computed statistics.
type CustomerStatistics {
    # The predicted spend tier of a customer with a shop.
    predictedSpendTier: CustomerPredictedSpendTier
}

# Represents a customer's session visiting a shop's online store,
# including information about the marketing activity attributed to starting the session.
type CustomerVisit implements CustomerMoment&Node {
    # A globally-unique identifier.
    id: ID!

    # URL of the first page the customer landed on for the session.
    landingPage: URL

    # Landing page information with URL linked in HTML.
    # For example, the first page the customer visited was store.myshopify.com/products/1.
    landingPageHtml: HTML

    # Represent actions taken by an app, on behalf of a merchant,
    # to market Shopify resources such as products, collections, and discounts.
    marketingEvent: MarketingEvent

    # The date and time when the customer's session occurred.
    occurredAt: DateTime!

    # Marketing referral code from the link that the customer clicked to visit the store.
    # Supports the following URL attributes: ref, source, or r.
    # For example, if the URL is myshopifystore.com/products/slide?ref=j2tj1tn2, then this value is j2tj1tn2.
    referralCode: String

    # Referral information with URLs linked in HTML.
    referralInfoHtml: FormattedString!

    # Webpage where the customer clicked a link that sent them to the online store.
    # For example, https://randomblog.com/page1 or android-app://com.google.android.gm.
    referrerUrl: URL

    # Source from which the customer visited the store, such as a platform (Facebook, Google), email, direct,
    # a website domain, QR code, or unknown.
    source: String!

    # Describes the source explicitly for first or last session.
    sourceDescription: String

    # Type of marketing tactic.
    sourceType: MarketingTactic

    # A set of UTM parameters gathered from the URL parameters of the referrer.
    utmParameters: UTMParameters
}

# Represents actions that market a merchant's store or products.
type MarketingEvent implements LegacyInteroperability&Node {
    # The app that the marketing event is attributed to.
    app: App!

    # The marketing channel used by the marketing event.
    channel: MarketingChannel

    # A human-readable description of the marketing event.
    description: String

    # The date and time when the marketing event ended.
    endedAt: DateTime

    # A globally-unique identifier.
    id: ID!

    # The ID of the corresponding resource in the REST Admin API.
    legacyResourceId: UnsignedInt64!

    # The URL where the marketing event can be managed.
    manageUrl: URL

    # The URL where the marketing event can be previewed.
    previewUrl: URL

    # An optional ID that helps Shopify validate engagement data.
    remoteId: String

    # The date and time when the marketing event is scheduled to end.
    scheduledToEndAt: DateTime

    # Where the MarketingEvent occurred and what kind of content was used.
    # Because utmSource and utmMedium are often used interchangeably, this is
    # based on a combination of marketingChannel, referringDomain, and type to
    # provide a consistent representation for any given piece of marketing
    # regardless of the app that created it.
    sourceAndMedium: String!

    # The date and time when the marketing event started.
    startedAt: DateTime!

    # The marketing event type.
    type: MarketingTactic!

    # The name of the marketing campaign.
    utmCampaign: String

    # The medium that the marketing campaign is using. Example values: cpc, banner.
    utmMedium: String

    # The referrer of the marketing event. Example values: google, newsletter.
    utmSource: String
}

# A customer's payment method.
type CustomerPaymentMethod implements Node {
    # The customer to whom the payment method belongs.
    customer: Customer

    # The ID of this payment method.
    id: ID!

    # The instrument for this payment method.
    instrument: CustomerPaymentInstrument

    # The time that the payment method was revoked.
    revokedAt: DateTime

    # The revocation reason for this payment method.
    revokedReason: CustomerPaymentMethodRevocationReason

    # List Subscription Contracts.
    subscriptionContracts(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): SubscriptionContractConnection!
}

# Represents a customer's visiting activities on a shop's online store.
type CustomerJourneySummary {
    customerOrderIndex: Int
    # The position of the current order within the customer's order history. Test orders aren't included.

    # The number of days between the first session and the order creation date.
    # The first session represents the first session since the last order, or the first session within the 30 day attribution window, if more than 30 days have passed since the last order.
    daysToConversion: Int

    # The customer's first session going into the shop.
    firstVisit: CustomerVisit

    # The last session before an order is made.
    lastVisit: CustomerVisit

    # The events preceding a customer's order, such as shop sessions.
    moments(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): CustomerMomentConnection

    # The total number of customer moments associated with this order. Returns null if the order is still in the process of being attributed.
    momentsCount: Int

    # Whether the attributed sessions for the order have been created yet.
    ready: Boolean!
}

# Represents a card instrument for customer payment method.
type CustomerCreditCard {
    # The billing address of the card.
    billingAddress: CustomerCreditCardBillingAddress

    # The brand of the card.
    brand: String!

    # Whether the card is about to expire.
    expiresSoon: Boolean!

    # The expiry month of the card.
    expiryMonth: Int!

    # The expiry year of the card.
    expiryYear: Int!

    # The card's BIN number.
    firstDigits: String

    # The payment method can be revoked if there are no active subscription contracts.
    isRevocable: Boolean!

    # The last 4 digits of the card.
    lastDigits: String!

    # The masked card number with only the last 4 digits displayed.
    maskedNumber: String!

    # The name of the card holder.
    name: String!

    # The source of the card if coming from a wallet such as Apple Pay.
    source: String

    # The last 4 digits of the Device Account Number.
    virtualLastDigits: String
}

# The billing address of a credit card payment instrument.
type CustomerCreditCardBillingAddress {
    # The first line of the address. Typically the street address or PO Box number.
    address1: String

    # The name of the city, district, village, or town.
    city: String

    # The name of the country.
    country: String

    # The two-letter code for the country of the address.
    # For example, US.
    countryCode: CountryCode

    # The region of the address, such as the province, state, or district.
    province: String

    # The two-letter code for the region.
    # For example, ON.
    provinceCode: String

    # The zip or postal code of the address.
    zip: String
}

# Represents a PayPal instrument for customer payment method.
type CustomerPaypalBillingAgreement {
    # The billing address of this payment method.
    billingAddress: CustomerPaymentInstrumentBillingAddress

    # Whether the PayPal billing agreement is inactive.
    inactive: Boolean!

    # Whether the payment method can be revoked.The payment method can be revoked if there are no active subscription contracts.
    isRevocable: Boolean!

    # The customers's PayPal account email address.
    paypalAccountEmail: String
}

# The billing address of a payment instrument.
type CustomerPaymentInstrumentBillingAddress {
    # The first line of the address. Typically the street address or PO Box number.
    address1: String

    # The name of the city, district, village, or town.
    city: String

    # The name of the country.
    country: String

    # The two-letter code for the country of the address.
    # For example, US.
    countryCode: CountryCode

    # The name of the buyer of the address.
    name: String

    # The region of the address, such as the province, state, or district.
    province: String

    # The two-letter code for the region.
    # For example, ON.
    provinceCode: String

    # The zip or postal code of the address.
    zip: String
}

# Represents a Shop Pay card instrument for customer payment method.
type CustomerShopPayAgreement {
    # Whether the card is about to expire.
    expiresSoon: Boolean!

    # The expiry month of the card.
    expiryMonth: Int!

    # The expiry year of the card.
    expiryYear: Int!

    # Whether the Shop Pay billing agreement is inactive.
    inactive: Boolean!

    # The payment method can be revoked if there are no active subscription contracts.
    isRevocable: Boolean!

    # The last 4 digits of the card.
    lastDigits: String!

    # The masked card number with only the last 4 digits displayed.
    maskedNumber: String!

    # The name of the card holder.
    name: String!
}