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 for apps that don't have a legitimate use for the associated data.

Anchor to Fields and connectionsFields and connections

Anchor to addressesaddresses • [MailingAddress!]!non-null: A list of addresses associated with the customer.
Anchor to addressesV2addressesV2 • MailingAddressConnection!non-null: The addresses associated with the customer.
Anchor to amountSpentamountSpent • MoneyV2!non-null: The total amount that the customer has spent on orders in their lifetime.
Anchor to canDeletecanDelete • 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.
Anchor to companyContactProfilescompanyContactProfiles • [CompanyContact!]!non-null: A list of the customer's company contact profiles.
Anchor to createdAtcreatedAt • DateTime!non-null: The date and time when the customer was added to the store.
Anchor to dataSaleOptOutdataSaleOptOut • Boolean!non-null: Whether the customer has opted out of having their data sold.
Anchor to defaultAddressdefaultAddress • MailingAddress: The default address associated with the customer.
Anchor to defaultEmailAddressdefaultEmailAddress • CustomerEmailAddress: The customer's default email address.
Anchor to defaultPhoneNumberdefaultPhoneNumber • CustomerPhoneNumber: The customer's default phone number.
Anchor to displayNamedisplayName • 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.
Anchor to eventsevents • EventConnection!non-null: A list of events associated with the customer.
Anchor to firstNamefirstName • String: The customer's first name.
Anchor to idid • ID!non-null: A globally-unique ID.
Anchor to imageimage • Image!non-null: The image associated with the customer.
Anchor to lastNamelastName • String: The customer's last name.
Anchor to lastOrderlastOrder • Order: The customer's last order.
Anchor to legacyResourceIdlegacyResourceId • UnsignedInt64!non-null: The ID of the corresponding resource in the REST Admin API.
Anchor to lifetimeDurationlifetimeDuration • String!non-null: The amount of time since the customer was first added to the store.

Example: 'about 12 years'.
Anchor to localelocale • String!non-null: The customer's locale.
Anchor to mergeablemergeable • CustomerMergeable!non-null: Whether the customer can be merged with another customer.
Anchor to metafieldmetafield • Metafield: A custom field, including its namespace and key, that's associated with a Shopify resource for the purposes of adding and storing additional information.
Anchor to metafieldsmetafields • MetafieldConnection!non-null: A list of custom fields that a merchant associates with a Shopify resource.
Anchor to multipassIdentifiermultipassIdentifier • String: A unique identifier for the customer that's used with Multipass login.
Anchor to notenote • String: A note about the customer.
Anchor to numberOfOrdersnumberOfOrders • UnsignedInt64!non-null: The number of orders that the customer has made at the store in their lifetime.
Anchor to ordersorders • OrderConnection!non-null: A list of the customer's orders.
Anchor to paymentMethodspaymentMethods • CustomerPaymentMethodConnection!non-null: A list of the customer's payment methods.
Anchor to productSubscriberStatusproductSubscriberStatus • CustomerProductSubscriberStatus!non-null: Possible subscriber states of a customer defined by their subscription contracts.
Anchor to statestate • 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.
Anchor to statisticsstatistics • CustomerStatistics!non-null: The statistics for a given customer.
Anchor to storeCreditAccountsstoreCreditAccounts • 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.
Anchor to subscriptionContractssubscriptionContracts • SubscriptionContractConnection!non-null: A list of the customer's subscription contracts.
Anchor to tagstags • [String!]!non-null: A comma separated list of tags that have been added to the customer.
Anchor to taxExempttaxExempt • Boolean!non-null: Whether the customer is exempt from being charged taxes on their orders.
Anchor to taxExemptionstaxExemptions • [TaxExemption!]!non-null: The list of tax exemptions applied to the customer.
Anchor to updatedAtupdatedAt • DateTime!non-null: The date and time when the customer was last updated.
Anchor to verifiedEmailverifiedEmail • 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.

Show

deprecated fields and connections Deprecated

Anchor to emailemail • StringDeprecated: The customer's email address. Use defaultEmailAddress.emailAddress instead.
Anchor to emailMarketingConsentemailMarketingConsent • CustomerEmailMarketingConsentStateDeprecated: The current email marketing state for the customer. If the customer doesn't have an email address, then this property is null. Use defaultEmailAddress.marketingState, defaultEmailAddress.marketingOptInLevel, defaultEmailAddress.marketingUpdatedAt, and defaultEmailAddress.sourceLocation instead.
Anchor to hasTimelineCommenthasTimelineComment • Boolean!non-nullDeprecated: Whether the merchant has added timeline comments about the customer on the customer's page. To query for comments on the timeline, use the events connection and a query argument containing verb:comment, or look for a CommentEvent in the __typename of events.
Anchor to marketmarket • MarketDeprecated: The market that includes the customer’s default address. This market field will be removed in a future version of the API.
Anchor to metafieldDefinitionsmetafieldDefinitions • MetafieldDefinitionConnection!non-nullDeprecated: List of metafield definitions. This field will be removed in a future version. Use the root metafieldDefinitions field instead.
Anchor to phonephone • StringDeprecated: The customer's phone number. Use defaultPhoneNumber.phoneNumber instead.
Anchor to smsMarketingConsentsmsMarketingConsent • CustomerSmsMarketingConsentStateDeprecated: 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. Use defaultPhoneNumber.marketingState, defaultPhoneNumber.marketingOptInLevel, defaultPhoneNumber.marketingUpdatedAt, defaultPhoneNumber.marketingCollectedFrom, and defaultPhoneNumber.sourceLocation instead.
Anchor to unsubscribeUrlunsubscribeUrl • URL!non-nullDeprecated: The URL to unsubscribe the customer from the mailing list. Use defaultEmailAddress.marketingUnsubscribeUrl instead.
Anchor to validEmailAddressvalidEmailAddress • Boolean!non-nullDeprecated: 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. Use defaultEmailAddress.validFormat instead.

Was this section helpful?

Anchor to QueriesQueries

Anchor to customer customer • query: Returns a Customer resource by ID.
Anchor to customerByIdentifier customerByIdentifier • query: Return a customer by an identifier.
Anchor to customers customers • query: Returns a list of customers.

Was this section helpful?

Anchor to MutationsMutations

Anchor to customerAddTaxExemptions customerAddTaxExemptions • mutation: Add tax exemptions for the customer.
Anchor to customerCreate customerCreate • mutation: Create a new customer. As of API version 2022-10, apps using protected customer data must meet the protected customer data requirements.
Anchor to customerEmailMarketingConsentUpdate customerEmailMarketingConsentUpdate • mutation: Update a customer's email marketing information information.
Anchor to customerPaymentMethodSendUpdateEmail customerPaymentMethodSendUpdateEmail • mutation: Sends a link to the customer so they can update a specific payment method.
Anchor to customerRemoveTaxExemptions customerRemoveTaxExemptions • mutation: Remove tax exemptions from a customer.
Anchor to customerReplaceTaxExemptions customerReplaceTaxExemptions • mutation: Replace tax exemptions for a customer.
Anchor to customerSendAccountInviteEmail customerSendAccountInviteEmail • mutation: Sends the customer an account invite email.
Anchor to customerSet 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

Any list field (e.g. addresses, 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.
Anchor to customerSmsMarketingConsentUpdate customerSmsMarketingConsentUpdate • mutation: Update a customer's SMS marketing consent information.
Anchor to customerUpdate 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.
Anchor to customerUpdateDefaultAddress customerUpdateDefaultAddress • mutation: Updates a customer's default address.

Was this section helpful?

Anchor to InterfacesInterfaces

Anchor to CommentEventSubject CommentEventSubject • interface
Anchor to HasEvents HasEvents • interface
Anchor to HasMetafieldDefinitions HasMetafieldDefinitions • interface
Anchor to HasMetafields HasMetafields • interface
Anchor to HasStoreCreditAccounts HasStoreCreditAccounts • interface
Anchor to LegacyInteroperability LegacyInteroperability • interface
Anchor to Node Node • interface

Was this section helpful?