--- title: Customer - GraphQL Admin description: |- Information about a customer of the shop, such as the customer's contact details, purchase history, and marketing preferences. Tracks the customer's total spending through the [`amountSpent`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer#field-amountSpent) field and provides access to associated data such as payment methods and subscription contracts. > Caution: > Only use this data if it's required for your app's functionality. Shopify will restrict [access to scopes](https://shopify.dev/api/usage/access-scopes) for apps that don't have a legitimate use for the associated data. api_version: 2025-10 api_name: admin type: object api_type: graphql source_url: html: https://shopify.dev/docs/api/admin-graphql/latest/objects/customer md: https://shopify.dev/docs/api/admin-graphql/latest/objects/customer.md --- # Customer object Requires `read_customers` access scope. Information about a customer of the shop, such as the customer's contact details, purchase history, and marketing preferences. Tracks the customer's total spending through the [`amountSpent`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer#field-amountSpent) field and provides access to associated data such as payment methods and subscription contracts. *** Caution Only use this data if it's required for your app's functionality. Shopify will restrict [access to scopes](https://shopify.dev/api/usage/access-scopes) for apps that don't have a legitimate use for the associated data. *** ## Fields * addresses [\[Mailing​Address!\]!](https://shopify.dev/docs/api/admin-graphql/latest/objects/MailingAddress) non-null A list of addresses associated with the customer. * addresses​V2 [Mailing​Address​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/MailingAddressConnection) non-null The addresses associated with the customer. * amount​Spent [Money​V2!](https://shopify.dev/docs/api/admin-graphql/latest/objects/MoneyV2) non-null The total amount that the customer has spent on orders in their lifetime. * can​Delete [Boolean!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) non-null Whether the merchant can delete the customer from their store. A customer can be deleted from a store only if they haven't yet made an order. After a customer makes an order, they can't be deleted from a store. * company​Contact​Profiles [\[Company​Contact!\]!](https://shopify.dev/docs/api/admin-graphql/latest/objects/CompanyContact) non-null A list of the customer's company contact profiles. * created​At [Date​Time!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/DateTime) non-null The date and time when the customer was added to the store. * data​Sale​Opt​Out [Boolean!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) non-null Whether the customer has opted out of having their data sold. * default​Address [Mailing​Address](https://shopify.dev/docs/api/admin-graphql/latest/objects/MailingAddress) The default address associated with the customer. * default​Email​Address [Customer​Email​Address](https://shopify.dev/docs/api/admin-graphql/latest/objects/CustomerEmailAddress) The customer's default email address. * default​Phone​Number [Customer​Phone​Number](https://shopify.dev/docs/api/admin-graphql/latest/objects/CustomerPhoneNumber) The customer's default phone number. * display​Name [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) non-null 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. * events [Event​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/EventConnection) non-null A list of events associated with the customer. * first​Name [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The customer's first name. * id [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID) non-null A globally-unique ID. * image [Image!](https://shopify.dev/docs/api/admin-graphql/latest/objects/Image) non-null The image associated with the customer. * last​Name [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The customer's last name. * last​Order [Order](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order) The customer's last order. * legacy​Resource​Id [Unsigned​Int64!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/UnsignedInt64) non-null The ID of the corresponding resource in the REST Admin API. * lifetime​Duration [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) non-null The amount of time since the customer was first added to the store. Example: 'about 12 years'. * locale [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) non-null The customer's locale. * mergeable [Customer​Mergeable!](https://shopify.dev/docs/api/admin-graphql/latest/objects/CustomerMergeable) non-null Whether the customer can be merged with another customer. * metafield [Metafield](https://shopify.dev/docs/api/admin-graphql/latest/objects/Metafield) A [custom field](https://shopify.dev/docs/apps/build/custom-data), including its `namespace` and `key`, that's associated with a Shopify resource for the purposes of adding and storing additional information. * metafields [Metafield​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/MetafieldConnection) non-null A list of [custom fields](https://shopify.dev/docs/apps/build/custom-data) that a merchant associates with a Shopify resource. * multipass​Identifier [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) A unique identifier for the customer that's used with Multipass login. * note [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) A note about the customer. * number​Of​Orders [Unsigned​Int64!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/UnsignedInt64) non-null The number of orders that the customer has made at the store in their lifetime. * orders [Order​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/OrderConnection) non-null A list of the customer's orders. * payment​Methods [Customer​Payment​Method​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/CustomerPaymentMethodConnection) non-null A list of the customer's payment methods. * product​Subscriber​Status [Customer​Product​Subscriber​Status!](https://shopify.dev/docs/api/admin-graphql/latest/enums/CustomerProductSubscriberStatus) non-null Possible subscriber states of a customer defined by their subscription contracts. * state [Customer​State!](https://shopify.dev/docs/api/admin-graphql/latest/enums/CustomerState) non-null The state of the customer's account with the shop. Please note that this only meaningful when Classic Customer Accounts is active. * statistics [Customer​Statistics!](https://shopify.dev/docs/api/admin-graphql/latest/objects/CustomerStatistics) non-null The statistics for a given customer. * store​Credit​Accounts [Store​Credit​Account​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/StoreCreditAccountConnection) non-null Returns a list of store credit accounts that belong to the owner resource. A store credit account owner can hold multiple accounts each with a different currency. * subscription​Contracts [Subscription​Contract​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/SubscriptionContractConnection) non-null A list of the customer's subscription contracts. * tags [\[String!\]!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) non-null A comma separated list of tags that have been added to the customer. * tax​Exempt [Boolean!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) non-null Whether the customer is exempt from being charged taxes on their orders. * tax​Exemptions [\[Tax​Exemption!\]!](https://shopify.dev/docs/api/admin-graphql/latest/enums/TaxExemption) non-null The list of tax exemptions applied to the customer. * updated​At [Date​Time!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/DateTime) non-null The date and time when the customer was last updated. * verified​Email [Boolean!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) non-null Whether the customer has verified their email address. Defaults to `true` if the customer is created through the Shopify admin or API. ### Deprecated fields * email [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) Deprecated * email​Marketing​Consent [Customer​Email​Marketing​Consent​State](https://shopify.dev/docs/api/admin-graphql/latest/objects/CustomerEmailMarketingConsentState) Deprecated * has​Timeline​Comment [Boolean!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) non-nullDeprecated * market [Market](https://shopify.dev/docs/api/admin-graphql/latest/objects/Market) Deprecated * metafield​Definitions [Metafield​Definition​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/MetafieldDefinitionConnection) non-nullDeprecated * phone [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) Deprecated * sms​Marketing​Consent [Customer​Sms​Marketing​Consent​State](https://shopify.dev/docs/api/admin-graphql/latest/objects/CustomerSmsMarketingConsentState) Deprecated * unsubscribe​Url [URL!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/URL) non-nullDeprecated * valid​Email​Address [Boolean!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) non-nullDeprecated *** ## Map ### Fields and connections with this object * {}[AbandonedCheckout.customer](https://shopify.dev/docs/api/admin-graphql/latest/objects/AbandonedCheckout#field-AbandonedCheckout.fields.customer) * {}[Abandonment.customer](https://shopify.dev/docs/api/admin-graphql/latest/objects/Abandonment#field-Abandonment.fields.customer) * {}[CalculatedDraftOrder.customer](https://shopify.dev/docs/api/admin-graphql/latest/objects/CalculatedDraftOrder#field-CalculatedDraftOrder.fields.customer) * {}[CompanyContact.customer](https://shopify.dev/docs/api/admin-graphql/latest/objects/CompanyContact#field-CompanyContact.fields.customer) * <->[CustomerConnection.nodes](https://shopify.dev/docs/api/admin-graphql/latest/connections/CustomerConnection#returns-nodes) * {}[CustomerEdge.node](https://shopify.dev/docs/api/admin-graphql/latest/objects/CustomerEdge#field-CustomerEdge.fields.node) * {}[CustomerPaymentMethod.customer](https://shopify.dev/docs/api/admin-graphql/latest/objects/CustomerPaymentMethod#field-CustomerPaymentMethod.fields.customer) * {}[DiscountCustomers.customers](https://shopify.dev/docs/api/admin-graphql/latest/objects/DiscountCustomers#field-DiscountCustomers.fields.customers) * {}[DraftOrder.customer](https://shopify.dev/docs/api/admin-graphql/latest/objects/DraftOrder#field-DraftOrder.fields.customer) * {}[GiftCard.customer](https://shopify.dev/docs/api/admin-graphql/latest/objects/GiftCard#field-GiftCard.fields.customer) * {}[GiftCardRecipient.recipient](https://shopify.dev/docs/api/admin-graphql/latest/objects/GiftCardRecipient#field-GiftCardRecipient.fields.recipient) * {}[Order.customer](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order#field-Order.fields.customer) * {}[PriceRuleCustomerSelection.customers](https://shopify.dev/docs/api/admin-graphql/latest/objects/PriceRuleCustomerSelection#field-PriceRuleCustomerSelection.fields.customers) * {}[SubscriptionBillingCycleEditedContract.customer](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionBillingCycleEditedContract#field-SubscriptionBillingCycleEditedContract.fields.customer) * {}[SubscriptionContract.customer](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionContract#field-SubscriptionContract.fields.customer) * ||-[SubscriptionContractBase.customer](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/SubscriptionContractBase#fields-customer) * {}[SubscriptionDraft.customer](https://shopify.dev/docs/api/admin-graphql/latest/objects/SubscriptionDraft#field-SubscriptionDraft.fields.customer) ### Possible type in * [Comment​Event​Embed](https://shopify.dev/docs/api/admin-graphql/latest/unions/CommentEventEmbed) * [Metafield​Reference](https://shopify.dev/docs/api/admin-graphql/latest/unions/MetafieldReference) * [Metafield​Referencer](https://shopify.dev/docs/api/admin-graphql/latest/unions/MetafieldReferencer) * [Purchasing​Entity](https://shopify.dev/docs/api/admin-graphql/latest/unions/PurchasingEntity) *** ## Queries * [customer](https://shopify.dev/docs/api/admin-graphql/latest/queries/customer) query Returns a `Customer` resource by ID. * [customer​By​Identifier](https://shopify.dev/docs/api/admin-graphql/latest/queries/customerByIdentifier) query Return a customer by an identifier. * [customers](https://shopify.dev/docs/api/admin-graphql/latest/queries/customers) query Returns a list of [customers](https://shopify.dev/api/admin-graphql/latest/objects/Customer) in your Shopify store, including key information such as name, email, location, and purchase history. Use this query to segment your audience, personalize marketing campaigns, or analyze customer behavior by applying filters based on location, order history, marketing preferences and tags. The `customers` query supports [pagination](https://shopify.dev/api/usage/pagination-graphql) and [sorting](https://shopify.dev/api/admin-graphql/latest/enums/CustomerSortKeys). *** ## \Customer Queries ### Queried by * \[customer](https://shopify.dev/docs/api/admin-graphql/latest/queries/customer) * \[customer​By​Identifier](https://shopify.dev/docs/api/admin-graphql/latest/queries/customerByIdentifier) * \[customers](https://shopify.dev/docs/api/admin-graphql/latest/queries/customers) *** ## Mutations * [customer​Add​Tax​Exemptions](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerAddTaxExemptions) mutation Add tax exemptions for the customer. * [customer​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerCreate) mutation Creates a new [`Customer`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer) in the store. Accepts customer details including contact information, marketing consent preferences, and tax exemptions through the [`CustomerInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/CustomerInput) input object. You can also associate [`metafields`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/MetafieldInput) and tags to organize and extend customer data. Apps using protected customer data must meet Shopify's [protected customer data requirements](https://shopify.dev/docs/apps/launch/protected-customer-data#requirements). * [customer​Email​Marketing​Consent​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerEmailMarketingConsentUpdate) mutation Updates a [`Customer`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer)'s email marketing consent information. The customer must have an email address to update their consent. Records the [marketing state](https://shopify.dev/docs/api/admin-graphql/latest/objects/CustomerEmailAddress#field-marketingState) (such as subscribed, pending, unsubscribed), [opt-in level](https://shopify.dev/docs/api/admin-graphql/latest/objects/CustomerEmailAddress#field-marketingOptInLevel), and when and where the customer gave or withdrew consent. * [customer​Payment​Method​Send​Update​Email](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerPaymentMethodSendUpdateEmail) mutation Sends a link to the customer so they can update a specific payment method. * [customer​Remove​Tax​Exemptions](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerRemoveTaxExemptions) mutation Remove tax exemptions from a customer. * [customer​Replace​Tax​Exemptions](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerReplaceTaxExemptions) mutation Replace tax exemptions for a customer. * [customer​Send​Account​Invite​Email](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerSendAccountInviteEmail) mutation Sends an email invitation for a customer to create a legacy customer account. The invitation lets customers set up their password and activate their account in the online store. You can optionally customize the email content including the subject, sender, recipients, and message body. If you don't provide email customization, the store uses its default account invitation template. *** Note The invite only works when legacy customer accounts are enabled on the shop. *** * [customer​Set](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerSet) mutation Creates or updates a customer in a single mutation. Use this mutation when syncing information from an external data source into Shopify. This mutation can be used to create a new customer, update an existing customer by id, or upsert a customer by a unique key (email or phone). To create a new customer omit the `identifier` argument. To update an existing customer, include the `identifier` with the id of the customer to update. To perform an 'upsert' by unique key (email or phone) use the `identifier` argument to upsert a customer by a unique key (email or phone). If a customer with the specified unique key exists, it will be updated. If not, a new customer will be created with that unique key. As of API version 2022-10, apps using protected customer data must meet the protected customer data [requirements](https://shopify.dev/apps/store/data-protection/protected-customer-data) Any list field (e.g. [addresses](https://shopify.dev/api/admin-graphql/unstable/input-objects/MailingAddressInput), will be updated so that all included entries are either created or updated, and all existing entries not included will be deleted. All other fields will be updated to the value passed. Omitted fields will not be updated. * [customer​Sms​Marketing​Consent​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerSmsMarketingConsentUpdate) mutation Updates a [customer](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer)'s SMS marketing consent information. The customer must have a phone number on their account to receive SMS marketing. You can set whether the customer subscribes or unsubscribes to SMS marketing and specify the [opt-in level](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerSmsMarketingConsentUpdate#arguments-input.fields.smsMarketingConsent.marketingOptInLevel). Optionally include when the consent was collected and which [location](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerSmsMarketingConsentUpdate#arguments-input.fields.smsMarketingConsent.sourceLocationId) collected it. * [customer​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerUpdate) mutation Updates a [`Customer`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer)'s attributes including personal information and [`tax exemptions`](https://shopify.dev/docs/api/admin-graphql/latest/enums/TaxExemption). Apps using protected customer data must meet Shopify's [protected customer data requirements](https://shopify.dev/docs/apps/launch/protected-customer-data#requirements). * [customer​Update​Default​Address](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerUpdateDefaultAddress) mutation Updates a customer's default address. *** ## <\~> Customer Mutations ### Mutated by * <\~>[customer​Add​Tax​Exemptions](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerAddTaxExemptions) * <\~>[customer​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerCreate) * <\~>[customer​Email​Marketing​Consent​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerEmailMarketingConsentUpdate) * <\~>[customer​Payment​Method​Send​Update​Email](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerPaymentMethodSendUpdateEmail) * <\~>[customer​Remove​Tax​Exemptions](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerRemoveTaxExemptions) * <\~>[customer​Replace​Tax​Exemptions](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerReplaceTaxExemptions) * <\~>[customer​Send​Account​Invite​Email](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerSendAccountInviteEmail) * <\~>[customer​Set](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerSet) * <\~>[customer​Sms​Marketing​Consent​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerSmsMarketingConsentUpdate) * <\~>[customer​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerUpdate) * <\~>[customer​Update​Default​Address](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerUpdateDefaultAddress) *** ## Interfaces * * [Comment​Event​Subject](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/CommentEventSubject) interface * [Has​Events](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/HasEvents) interface * [Has​Metafield​Definitions](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/HasMetafieldDefinitions) interface * [Has​Metafields](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/HasMetafields) interface * [Has​Store​Credit​Accounts](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/HasStoreCreditAccounts) interface * [Legacy​Interoperability](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/LegacyInteroperability) interface * [Node](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/Node) interface *** ## ||-Customer Implements ### Implements * ||-[Comment​Event​Subject](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/CommentEventSubject) * ||-[Has​Events](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/HasEvents) * ||-[Has​Metafield​Definitions](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/HasMetafieldDefinitions) * ||-[Has​Metafields](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/HasMetafields) * ||-[Has​Store​Credit​Accounts](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/HasStoreCreditAccounts) * ||-[Legacy​Interoperability](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/LegacyInteroperability) * ||-[Node](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/Node)