--- title: Customer - Storefront API description: > A customer account with the shop. Includes data such as contact information, [addresses](/docs/api/storefront/2026-04/objects/MailingAddress) and marketing preferences for logged-in customers, so they don't have to provide these details at every checkout. Access the customer through the [`customer`](/docs/api/storefront/2026-04/queries/customer) query using a customer access token obtained from the [`customerAccessTokenCreate`](/docs/api/storefront/2026-04/mutations/customerAccessTokenCreate) mutation. The object implements the [`HasMetafields`](/docs/api/storefront/2026-04/interfaces/HasMetafields) interface, enabling retrieval of [custom data](https://shopify.dev/docs/apps/build/custom-data) associated with the customer. api_version: 2026-04 api_name: storefront type: object api_type: graphql source_url: html: 'https://shopify.dev/docs/api/storefront/latest/objects/Customer' md: 'https://shopify.dev/docs/api/storefront/latest/objects/Customer.md' --- # Customer object Requires `unauthenticated_read_customers` access scope. A customer account with the shop. Includes data such as contact information, [addresses](https://shopify.dev/docs/api/storefront/2026-04/objects/MailingAddress) and marketing preferences for logged-in customers, so they don't have to provide these details at every checkout. Access the customer through the [`customer`](https://shopify.dev/docs/api/storefront/2026-04/queries/customer) query using a customer access token obtained from the [`customerAccessTokenCreate`](https://shopify.dev/docs/api/storefront/2026-04/mutations/customerAccessTokenCreate) mutation. The object implements the [`HasMetafields`](https://shopify.dev/docs/api/storefront/2026-04/interfaces/HasMetafields) interface, enabling retrieval of [custom data](https://shopify.dev/docs/apps/build/custom-data) associated with the customer. ## Fields * accepts​Marketing [Boolean!](https://shopify.dev/docs/api/storefront/latest/scalars/Boolean) non-null Token access required Indicates whether the customer has consented to be sent marketing material via email. * addresses [Mailing​Address​Connection!](https://shopify.dev/docs/api/storefront/latest/connections/MailingAddressConnection) non-null Token access required A list of addresses for the customer. * first [Int](https://shopify.dev/docs/api/storefront/latest/scalars/Int) ### Arguments Returns up to the first `n` elements from the list. * after [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) Returns the elements that come after the specified cursor. * last [Int](https://shopify.dev/docs/api/storefront/latest/scalars/Int) Returns up to the last `n` elements from the list. * before [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) Returns the elements that come before the specified cursor. * reverse [Boolean](https://shopify.dev/docs/api/storefront/latest/scalars/Boolean) Default:false Reverse the order of the underlying list. *** * avatar​Url [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) Token access required The URL of the customer's avatar image. * created​At [Date​Time!](https://shopify.dev/docs/api/storefront/latest/scalars/DateTime) non-null Token access required The date and time when the customer was created. * default​Address [Mailing​Address](https://shopify.dev/docs/api/storefront/latest/objects/MailingAddress) Token access required The customer’s default address. * display​Name [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String) non-null Token access required The customer’s name, email or phone number. * email [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) Token access required The customer’s email address. * first​Name [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) Token access required The customer’s first name. * id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) non-null Token access required A unique ID for the customer. * last​Name [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) Token access required The customer’s last name. * metafield [Metafield](https://shopify.dev/docs/api/storefront/latest/objects/Metafield) Token access required 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. * namespace [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) ### Arguments The container the metafield belongs to. If omitted, the app-reserved namespace will be used. * key [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required The identifier for the metafield. *** * metafields [\[Metafield\]!](https://shopify.dev/docs/api/storefront/latest/objects/Metafield) non-null Token access required A list of [custom fields](https://shopify.dev/docs/apps/build/custom-data) that a merchant associates with a Shopify resource. * identifiers [\[Has​Metafields​Identifier!\]!](https://shopify.dev/docs/api/storefront/latest/input-objects/HasMetafieldsIdentifier) required ### Arguments The list of metafields to retrieve by namespace and key. The input must not contain more than `250` values. *** * number​Of​Orders [Unsigned​Int64!](https://shopify.dev/docs/api/storefront/latest/scalars/UnsignedInt64) non-null Token access required The number of orders that the customer has made at the store in their lifetime. * orders [Order​Connection!](https://shopify.dev/docs/api/storefront/latest/connections/OrderConnection) non-null Token access required The orders associated with the customer. * first [Int](https://shopify.dev/docs/api/storefront/latest/scalars/Int) ### Arguments Returns up to the first `n` elements from the list. * after [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) Returns the elements that come after the specified cursor. * last [Int](https://shopify.dev/docs/api/storefront/latest/scalars/Int) Returns up to the last `n` elements from the list. * before [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) Returns the elements that come before the specified cursor. * reverse [Boolean](https://shopify.dev/docs/api/storefront/latest/scalars/Boolean) Default:false Reverse the order of the underlying list. * sort​Key [Order​Sort​Keys](https://shopify.dev/docs/api/storefront/latest/enums/OrderSortKeys) Default:ID Sort the underlying list by the given key. * query [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) Apply one or multiple filters to the query. Refer to the detailed [search syntax](https://shopify.dev/api/usage/search-syntax) for more information about using filters. * processed\_at *** * phone [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) Token access required The customer’s phone number. * social​Login​Provider [Social​Login​Provider](https://shopify.dev/docs/api/storefront/latest/objects/SocialLoginProvider) Token access required The social login provider associated with the customer. * tags [\[String!\]!](https://shopify.dev/docs/api/storefront/latest/scalars/String) non-null Token access required A comma separated list of tags that have been added to the customer. Additional access scope required: unauthenticated\_read\_customer\_tags. * updated​At [Date​Time!](https://shopify.dev/docs/api/storefront/latest/scalars/DateTime) non-null Token access required The date and time when the customer information was updated. *** ## Map ### Fields with this object * [CartBuyerIdentity.customer](https://shopify.dev/docs/api/storefront/latest/objects/CartBuyerIdentity#field-CartBuyerIdentity.fields.customer) ### Possible type in * [Metafield​Parent​Resource](https://shopify.dev/docs/api/storefront/latest/unions/MetafieldParentResource) *** ## Queries * [customer](https://shopify.dev/docs/api/storefront/latest/queries/customer) query Retrieves the [`Customer`](https://shopify.dev/docs/api/storefront/2026-04/objects/Customer) associated with the provided access token. Use the [`customerAccessTokenCreate`](https://shopify.dev/docs/api/storefront/2026-04/mutations/customerAccessTokenCreate) mutation to obtain an access token using legacy customer account authentication (email and password). The returned customer includes data such as contact information, [addresses](https://shopify.dev/docs/api/storefront/2026-04/objects/MailingAddress), [orders](https://shopify.dev/docs/api/storefront/2026-04/objects/Order), and [custom data](https://shopify.dev/docs/apps/build/custom-data) associated with the customer. * customer​Access​Token [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required ### Arguments The customer access token. *** *** ## Customer Queries ### Queried by * [customer](https://shopify.dev/docs/api/storefront/latest/queries/customer) *** ## Mutations * [customer​Activate](https://shopify.dev/docs/api/storefront/latest/mutations/customerActivate) mutation Activates a customer account using an activation token received from the [`customerCreate`](https://shopify.dev/docs/api/storefront/2026-04/mutations/customerCreate) mutation. The customer sets their password during activation and receives a [`CustomerAccessToken`](https://shopify.dev/docs/api/storefront/2026-04/objects/CustomerAccessToken) for authenticated access. For a simpler approach that doesn't require parsing the activation URL, use [`customerActivateByUrl`](https://shopify.dev/docs/api/storefront/2026-04/mutations/customerActivateByUrl) instead. *** **Caution:** This mutation handles customer credentials. Always use HTTPS and never log or expose the password or access token. *** * id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required ### Arguments Specifies the customer to activate. * input [Customer​Activate​Input!](https://shopify.dev/docs/api/storefront/latest/input-objects/CustomerActivateInput) required The fields used to activate a customer. *** * [customer​Activate​By​Url](https://shopify.dev/docs/api/storefront/latest/mutations/customerActivateByUrl) mutation Activates a customer account using the full activation URL from the [`customerCreate`](https://shopify.dev/docs/api/storefront/2026-04/mutations/customerCreate) mutation. This approach simplifies activation by accepting the complete URL directly, eliminating the need to parse it for the customer ID and activation token. Returns a [`CustomerAccessToken`](https://shopify.dev/docs/api/storefront/2026-04/objects/CustomerAccessToken) for authenticating subsequent requests. *** **Caution:** Store the returned access token securely. It grants access to the customer\'s account data. *** * activation​Url [URL!](https://shopify.dev/docs/api/storefront/latest/scalars/URL) required ### Arguments The customer activation URL. * password [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required A new password set during activation. *** * [customer​Create](https://shopify.dev/docs/api/storefront/latest/mutations/customerCreate) mutation Creates a new [`Customer`](https://shopify.dev/docs/api/storefront/2026-04/objects/Customer) account with the provided contact information and login credentials. The customer can then sign in for things such as accessing their account, viewing order history, and managing saved addresses. *** **Caution:** This mutation creates customer credentials. Ensure passwords are collected securely and never logged or exposed in client-side code. *** * input [Customer​Create​Input!](https://shopify.dev/docs/api/storefront/latest/input-objects/CustomerCreateInput) required ### Arguments The fields used to create a new customer. *** * [customer​Default​Address​Update](https://shopify.dev/docs/api/storefront/latest/mutations/customerDefaultAddressUpdate) mutation Updates the default address of an existing [`Customer`](https://shopify.dev/docs/api/storefront/2026-04/objects/Customer). Requires a [customer access token](https://shopify.dev/docs/api/storefront/2026-04/mutations/customerDefaultAddressUpdate#arguments-customerAccessToken) to identify the customer and an address ID to specify which address to set as the new default. * customer​Access​Token [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required ### Arguments The access token used to identify the customer. * address​Id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required ID of the address to set as the new default for the customer. *** * [customer​Reset](https://shopify.dev/docs/api/storefront/latest/mutations/customerReset) mutation Resets a customer's password using the reset token from a password recovery email. On success, returns the updated [`Customer`](https://shopify.dev/docs/api/storefront/2026-04/objects/Customer) and a new [`CustomerAccessToken`](https://shopify.dev/docs/api/storefront/2026-04/objects/CustomerAccessToken) for immediate authentication. Use the [`customerRecover`](https://shopify.dev/docs/api/storefront/2026-04/mutations/customerRecover) mutation to send the password recovery email that provides the reset token. Alternatively, use [`customerResetByUrl`](https://shopify.dev/docs/api/storefront/2026-04/mutations/customerResetByUrl) if you have the full reset URL instead of the customer ID and token. *** **Caution:** This mutation handles sensitive customer credentials. Validate password requirements on the client before submission. *** * id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required ### Arguments Specifies the customer to reset. * input [Customer​Reset​Input!](https://shopify.dev/docs/api/storefront/latest/input-objects/CustomerResetInput) required The fields used to reset a customer’s password. *** * [customer​Reset​By​Url](https://shopify.dev/docs/api/storefront/latest/mutations/customerResetByUrl) mutation Resets a customer's password using the reset URL from a password recovery email. The reset URL is generated by the [`customerRecover`](https://shopify.dev/docs/api/storefront/2026-04/mutations/customerRecover) mutation. On success, returns the updated [`Customer`](https://shopify.dev/docs/api/storefront/2026-04/objects/Customer) and a new [`CustomerAccessToken`](https://shopify.dev/docs/api/storefront/2026-04/objects/CustomerAccessToken) for immediate authentication. *** **Caution:** This mutation handles customer credentials. Ensure the new password is transmitted securely and never logged or exposed in client-side code. *** * reset​Url [URL!](https://shopify.dev/docs/api/storefront/latest/scalars/URL) required ### Arguments The customer's reset password url. * password [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required New password that will be set as part of the reset password process. *** * [customer​Update](https://shopify.dev/docs/api/storefront/latest/mutations/customerUpdate) mutation Updates a [customer's](https://shopify.dev/docs/api/storefront/2026-04/objects/Customer) personal information such as name, password, and marketing preferences. Requires a valid [`CustomerAccessToken`](https://shopify.dev/docs/api/storefront/2026-04/objects/CustomerAccessToken) to authenticate the customer making the update. If the customer's password is updated, then all previous access tokens become invalid. The mutation returns a new access token in the payload to maintain the customer's session. *** **Caution:** Password changes invalidate all existing access tokens. Ensure your app handles the new token returned in the response to avoid logging the customer out. *** * customer​Access​Token [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required ### Arguments The access token used to identify the customer. * customer [Customer​Update​Input!](https://shopify.dev/docs/api/storefront/latest/input-objects/CustomerUpdateInput) required The customer object input. *** *** ## Customer Mutations ### Mutated by * [customer​Activate](https://shopify.dev/docs/api/storefront/latest/mutations/customerActivate) * [customer​Activate​By​Url](https://shopify.dev/docs/api/storefront/latest/mutations/customerActivateByUrl) * [customer​Create](https://shopify.dev/docs/api/storefront/latest/mutations/customerCreate) * [customer​Default​Address​Update](https://shopify.dev/docs/api/storefront/latest/mutations/customerDefaultAddressUpdate) * [customer​Reset](https://shopify.dev/docs/api/storefront/latest/mutations/customerReset) * [customer​Reset​By​Url](https://shopify.dev/docs/api/storefront/latest/mutations/customerResetByUrl) * [customer​Update](https://shopify.dev/docs/api/storefront/latest/mutations/customerUpdate) *** ## Interfaces * [Has​Metafields](https://shopify.dev/docs/api/storefront/latest/interfaces/HasMetafields) interface *** ## Customer Implements ### Implements * [Has​Metafields](https://shopify.dev/docs/api/storefront/latest/interfaces/HasMetafields)