--- title: Customer - GraphQL Admin description: >- 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](https://shopify.dev/api/usage/access-scopes) for apps that don't have a legitimate use for the associated data. api_version: 2025-04 api_name: admin type: object api_type: graphql source_url: html: 'https://shopify.dev/docs/api/admin-graphql/2025-04/objects/Customer' md: 'https://shopify.dev/docs/api/admin-graphql/2025-04/objects/Customer.md' --- # Customer object Requires `read_customers` access scope. 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](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/2025-04/objects/MailingAddress) non-null A list of addresses associated with the customer. * addresses​V2 [Mailing​Address​Connection!](https://shopify.dev/docs/api/admin-graphql/2025-04/connections/MailingAddressConnection) non-null The addresses associated with the customer. * amount​Spent [Money​V2!](https://shopify.dev/docs/api/admin-graphql/2025-04/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/2025-04/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/2025-04/objects/CompanyContact) non-null A list of the customer's company contact profiles. * created​At [Date​Time!](https://shopify.dev/docs/api/admin-graphql/2025-04/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/2025-04/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/2025-04/objects/MailingAddress) The default address associated with the customer. * default​Email​Address [Customer​Email​Address](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/CustomerEmailAddress) The customer's default email address. * default​Phone​Number [Customer​Phone​Number](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/CustomerPhoneNumber) The customer's default phone number. * display​Name [String!](https://shopify.dev/docs/api/admin-graphql/2025-04/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/2025-04/connections/EventConnection) non-null A list of events associated with the customer. * first​Name [String](https://shopify.dev/docs/api/admin-graphql/2025-04/scalars/String) The customer's first name. * id [ID!](https://shopify.dev/docs/api/admin-graphql/2025-04/scalars/ID) non-null A globally-unique ID. * image [Image!](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/Image) non-null The image associated with the customer. * last​Name [String](https://shopify.dev/docs/api/admin-graphql/2025-04/scalars/String) The customer's last name. * last​Order [Order](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/Order) The customer's last order. * legacy​Resource​Id [Unsigned​Int64!](https://shopify.dev/docs/api/admin-graphql/2025-04/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/2025-04/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/2025-04/scalars/String) non-null The customer's locale. * mergeable [Customer​Mergeable!](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/CustomerMergeable) non-null Whether the customer can be merged with another customer. * metafield [Metafield](https://shopify.dev/docs/api/admin-graphql/2025-04/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/2025-04/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/2025-04/scalars/String) A unique identifier for the customer that's used with Multipass login. * note [String](https://shopify.dev/docs/api/admin-graphql/2025-04/scalars/String) A note about the customer. * number​Of​Orders [Unsigned​Int64!](https://shopify.dev/docs/api/admin-graphql/2025-04/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/2025-04/connections/OrderConnection) non-null A list of the customer's orders. * payment​Methods [Customer​Payment​Method​Connection!](https://shopify.dev/docs/api/admin-graphql/2025-04/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/2025-04/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/2025-04/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/2025-04/objects/CustomerStatistics) non-null The statistics for a given customer. * store​Credit​Accounts [Store​Credit​Account​Connection!](https://shopify.dev/docs/api/admin-graphql/2025-04/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/2025-04/connections/SubscriptionContractConnection) non-null A list of the customer's subscription contracts. * tags [\[String!\]!](https://shopify.dev/docs/api/admin-graphql/2025-04/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/2025-04/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/2025-04/enums/TaxExemption) non-null The list of tax exemptions applied to the customer. * updated​At [Date​Time!](https://shopify.dev/docs/api/admin-graphql/2025-04/scalars/DateTime) non-null The date and time when the customer was last updated. * verified​Email [Boolean!](https://shopify.dev/docs/api/admin-graphql/2025-04/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/2025-04/scalars/String) Deprecated * email​Marketing​Consent [Customer​Email​Marketing​Consent​State](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/CustomerEmailMarketingConsentState) Deprecated * has​Timeline​Comment [Boolean!](https://shopify.dev/docs/api/admin-graphql/2025-04/scalars/Boolean) non-nullDeprecated * market [Market](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/Market) Deprecated * metafield​Definitions [Metafield​Definition​Connection!](https://shopify.dev/docs/api/admin-graphql/2025-04/connections/MetafieldDefinitionConnection) non-nullDeprecated * phone [String](https://shopify.dev/docs/api/admin-graphql/2025-04/scalars/String) Deprecated * sms​Marketing​Consent [Customer​Sms​Marketing​Consent​State](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/CustomerSmsMarketingConsentState) Deprecated * unsubscribe​Url [URL!](https://shopify.dev/docs/api/admin-graphql/2025-04/scalars/URL) non-nullDeprecated * valid​Email​Address [Boolean!](https://shopify.dev/docs/api/admin-graphql/2025-04/scalars/Boolean) non-nullDeprecated *** ## Map ### Fields and connections with this object * {}[AbandonedCheckout.customer](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/AbandonedCheckout#field-AbandonedCheckout.fields.customer) * {}[Abandonment.customer](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/Abandonment#field-Abandonment.fields.customer) * {}[CalculatedDraftOrder.customer](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/CalculatedDraftOrder#field-CalculatedDraftOrder.fields.customer) * {}[CompanyContact.customer](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/CompanyContact#field-CompanyContact.fields.customer) * <->[CustomerConnection.nodes](https://shopify.dev/docs/api/admin-graphql/2025-04/connections/CustomerConnection#returns-nodes) * {}[CustomerEdge.node](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/CustomerEdge#field-CustomerEdge.fields.node) * {}[CustomerPaymentMethod.customer](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/CustomerPaymentMethod#field-CustomerPaymentMethod.fields.customer) * {}[DiscountCustomers.customers](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/DiscountCustomers#field-DiscountCustomers.fields.customers) * {}[DraftOrder.customer](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/DraftOrder#field-DraftOrder.fields.customer) * {}[GiftCard.customer](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/GiftCard#field-GiftCard.fields.customer) * {}[GiftCardRecipient.recipient](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/GiftCardRecipient#field-GiftCardRecipient.fields.recipient) * {}[Order.customer](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/Order#field-Order.fields.customer) * {}[PriceRuleCustomerSelection.customers](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/PriceRuleCustomerSelection#field-PriceRuleCustomerSelection.fields.customers) * {}[SubscriptionBillingCycleEditedContract.customer](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/SubscriptionBillingCycleEditedContract#field-SubscriptionBillingCycleEditedContract.fields.customer) * {}[SubscriptionContract.customer](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/SubscriptionContract#field-SubscriptionContract.fields.customer) * ||-[SubscriptionContractBase.customer](https://shopify.dev/docs/api/admin-graphql/2025-04/interfaces/SubscriptionContractBase#fields-customer) * {}[SubscriptionDraft.customer](https://shopify.dev/docs/api/admin-graphql/2025-04/objects/SubscriptionDraft#field-SubscriptionDraft.fields.customer) ### Possible type in * [Comment​Event​Embed](https://shopify.dev/docs/api/admin-graphql/2025-04/unions/CommentEventEmbed) * [Metafield​Reference](https://shopify.dev/docs/api/admin-graphql/2025-04/unions/MetafieldReference) * [Metafield​Referencer](https://shopify.dev/docs/api/admin-graphql/2025-04/unions/MetafieldReferencer) * [Purchasing​Entity](https://shopify.dev/docs/api/admin-graphql/2025-04/unions/PurchasingEntity) *** ## Queries * [customer](https://shopify.dev/docs/api/admin-graphql/2025-04/queries/customer) query Returns a `Customer` resource by ID. * [customer​By​Identifier](https://shopify.dev/docs/api/admin-graphql/2025-04/queries/customerByIdentifier) query Return a customer by an identifier. * [customers](https://shopify.dev/docs/api/admin-graphql/2025-04/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/2025-04/queries/customer) * \[customer​By​Identifier](https://shopify.dev/docs/api/admin-graphql/2025-04/queries/customerByIdentifier) * \[customers](https://shopify.dev/docs/api/admin-graphql/2025-04/queries/customers) *** ## Mutations * [customer​Add​Tax​Exemptions](https://shopify.dev/docs/api/admin-graphql/2025-04/mutations/customerAddTaxExemptions) mutation Add tax exemptions for the customer. * [customer​Create](https://shopify.dev/docs/api/admin-graphql/2025-04/mutations/customerCreate) mutation Create a new customer. 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). * [customer​Email​Marketing​Consent​Update](https://shopify.dev/docs/api/admin-graphql/2025-04/mutations/customerEmailMarketingConsentUpdate) mutation Update a customer's email marketing information information. * [customer​Payment​Method​Send​Update​Email](https://shopify.dev/docs/api/admin-graphql/2025-04/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/2025-04/mutations/customerRemoveTaxExemptions) mutation Remove tax exemptions from a customer. * [customer​Replace​Tax​Exemptions](https://shopify.dev/docs/api/admin-graphql/2025-04/mutations/customerReplaceTaxExemptions) mutation Replace tax exemptions for a customer. * [customer​Send​Account​Invite​Email](https://shopify.dev/docs/api/admin-graphql/2025-04/mutations/customerSendAccountInviteEmail) mutation Sends the customer an account invite email. * [customer​Set](https://shopify.dev/docs/api/admin-graphql/2025-04/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/2025-04/mutations/customerSmsMarketingConsentUpdate) mutation Update a customer's SMS marketing consent information. * [customer​Update](https://shopify.dev/docs/api/admin-graphql/2025-04/mutations/customerUpdate) mutation Update a customer's attributes. 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). * [customer​Update​Default​Address](https://shopify.dev/docs/api/admin-graphql/2025-04/mutations/customerUpdateDefaultAddress) mutation Updates a customer's default address. *** ## <\~> Customer Mutations ### Mutated by * <\~>[customer​Add​Tax​Exemptions](https://shopify.dev/docs/api/admin-graphql/2025-04/mutations/customerAddTaxExemptions) * <\~>[customer​Create](https://shopify.dev/docs/api/admin-graphql/2025-04/mutations/customerCreate) * <\~>[customer​Email​Marketing​Consent​Update](https://shopify.dev/docs/api/admin-graphql/2025-04/mutations/customerEmailMarketingConsentUpdate) * <\~>[customer​Payment​Method​Send​Update​Email](https://shopify.dev/docs/api/admin-graphql/2025-04/mutations/customerPaymentMethodSendUpdateEmail) * <\~>[customer​Remove​Tax​Exemptions](https://shopify.dev/docs/api/admin-graphql/2025-04/mutations/customerRemoveTaxExemptions) * <\~>[customer​Replace​Tax​Exemptions](https://shopify.dev/docs/api/admin-graphql/2025-04/mutations/customerReplaceTaxExemptions) * <\~>[customer​Send​Account​Invite​Email](https://shopify.dev/docs/api/admin-graphql/2025-04/mutations/customerSendAccountInviteEmail) * <\~>[customer​Set](https://shopify.dev/docs/api/admin-graphql/2025-04/mutations/customerSet) * <\~>[customer​Sms​Marketing​Consent​Update](https://shopify.dev/docs/api/admin-graphql/2025-04/mutations/customerSmsMarketingConsentUpdate) * <\~>[customer​Update](https://shopify.dev/docs/api/admin-graphql/2025-04/mutations/customerUpdate) * <\~>[customer​Update​Default​Address](https://shopify.dev/docs/api/admin-graphql/2025-04/mutations/customerUpdateDefaultAddress) *** ## Interfaces * * [Comment​Event​Subject](https://shopify.dev/docs/api/admin-graphql/2025-04/interfaces/CommentEventSubject) interface * [Has​Events](https://shopify.dev/docs/api/admin-graphql/2025-04/interfaces/HasEvents) interface * [Has​Metafield​Definitions](https://shopify.dev/docs/api/admin-graphql/2025-04/interfaces/HasMetafieldDefinitions) interface * [Has​Metafields](https://shopify.dev/docs/api/admin-graphql/2025-04/interfaces/HasMetafields) interface * [Has​Store​Credit​Accounts](https://shopify.dev/docs/api/admin-graphql/2025-04/interfaces/HasStoreCreditAccounts) interface * [Legacy​Interoperability](https://shopify.dev/docs/api/admin-graphql/2025-04/interfaces/LegacyInteroperability) interface * [Node](https://shopify.dev/docs/api/admin-graphql/2025-04/interfaces/Node) interface *** ## ||-Customer Implements ### Implements * ||-[Comment​Event​Subject](https://shopify.dev/docs/api/admin-graphql/2025-04/interfaces/CommentEventSubject) * ||-[Has​Events](https://shopify.dev/docs/api/admin-graphql/2025-04/interfaces/HasEvents) * ||-[Has​Metafield​Definitions](https://shopify.dev/docs/api/admin-graphql/2025-04/interfaces/HasMetafieldDefinitions) * ||-[Has​Metafields](https://shopify.dev/docs/api/admin-graphql/2025-04/interfaces/HasMetafields) * ||-[Has​Store​Credit​Accounts](https://shopify.dev/docs/api/admin-graphql/2025-04/interfaces/HasStoreCreditAccounts) * ||-[Legacy​Interoperability](https://shopify.dev/docs/api/admin-graphql/2025-04/interfaces/LegacyInteroperability) * ||-[Node](https://shopify.dev/docs/api/admin-graphql/2025-04/interfaces/Node)