--- title: Mutation - Storefront API description: The schema’s entry-point for mutations. This acts as the public, top-level API from which all mutation queries must start. api_version: 2026-01 api_name: storefront type: object api_type: graphql source_url: html: https://shopify.dev/docs/api/storefront/latest/objects/mutation md: https://shopify.dev/docs/api/storefront/latest/objects/mutation.md --- # Mutation object The schema’s entry-point for mutations. This acts as the public, top-level API from which all mutation queries must start. ## Fields * cart​Attributes​Update [Cart​Attributes​Update​Payload](https://shopify.dev/docs/api/storefront/latest/types/CartAttributesUpdatePayload) Updates the attributes on a [`Cart`](https://shopify.dev/docs/api/storefront/2026-01/objects/Cart). Attributes are custom key-value pairs that store additional information, such as gift messages, special instructions, or order notes. * attributes [\[Attribute​Input!\]!](https://shopify.dev/docs/api/storefront/latest/input-objects/AttributeInput) required ### Arguments An array of key-value pairs that contains additional information about the cart. The input must not contain more than `250` values. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required The ID of the cart. *** * cart​Buyer​Identity​Update [Cart​Buyer​Identity​Update​Payload](https://shopify.dev/docs/api/storefront/latest/types/CartBuyerIdentityUpdatePayload) Updates the buyer identity on a [`Cart`](https://shopify.dev/docs/api/storefront/2026-01/objects/Cart), including contact information, location, and checkout preferences. The buyer's country determines [international pricing](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/markets/international-pricing) and should match their shipping address. Use this mutation to associate a logged-in customer via access token, set a B2B company location, or configure checkout preferences like delivery method. Preferences prefill checkout fields but don't sync back to the cart if overwritten at checkout. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required ### Arguments The ID of the cart. * buyer​Identity [Cart​Buyer​Identity​Input!](https://shopify.dev/docs/api/storefront/latest/input-objects/CartBuyerIdentityInput) required The customer associated with the cart. Used to determine [international pricing](https://shopify.dev/custom-storefronts/internationalization/international-pricing). Buyer identity should match the customer's shipping address. *** * cart​Create [Cart​Create​Payload](https://shopify.dev/docs/api/storefront/latest/types/CartCreatePayload) Creates a new [`Cart`](https://shopify.dev/docs/api/storefront/2026-01/objects/Cart) for a buyer session. You can optionally initialize the cart with merchandise lines, discount codes, gift card codes, buyer identity for international pricing, and custom attributes. The returned cart includes a `checkoutUrl` that directs the buyer to complete their purchase. * input [Cart​Input](https://shopify.dev/docs/api/storefront/latest/input-objects/CartInput) ### Arguments The fields used to create a cart. *** * cart​Delivery​Addresses​Add [Cart​Delivery​Addresses​Add​Payload](https://shopify.dev/docs/api/storefront/latest/types/CartDeliveryAddressesAddPayload) Adds delivery addresses to a [`Cart`](https://shopify.dev/docs/api/storefront/2026-01/objects/Cart). A cart can have up to 20 delivery addresses. One address can be marked as selected for checkout, and addresses can optionally be marked as one-time use so they aren't saved to the customer's account. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required ### Arguments The ID of the cart. * addresses [\[Cart​Selectable​Address​Input!\]!](https://shopify.dev/docs/api/storefront/latest/input-objects/CartSelectableAddressInput) required A list of delivery addresses to add to the cart. The input must not contain more than `250` values. *** * cart​Delivery​Addresses​Remove [Cart​Delivery​Addresses​Remove​Payload](https://shopify.dev/docs/api/storefront/latest/types/CartDeliveryAddressesRemovePayload) Removes delivery addresses from a [`Cart`](https://shopify.dev/docs/api/storefront/2026-01/objects/Cart) by their IDs, allowing batch removal in a single request. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required ### Arguments The ID of the cart. * address​Ids [\[ID!\]!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required A list of delivery addresses by handle to remove from the cart. The input must not contain more than `250` values. *** * cart​Delivery​Addresses​Replace [Cart​Delivery​Addresses​Replace​Payload](https://shopify.dev/docs/api/storefront/latest/types/CartDeliveryAddressesReplacePayload) Replaces all delivery addresses on a [`Cart`](https://shopify.dev/docs/api/storefront/2026-01/objects/Cart) with a new set of addresses in a single operation. Unlike [`cartDeliveryAddressesUpdate`](https://shopify.dev/docs/api/storefront/2026-01/mutations/cartDeliveryAddressesUpdate), which modifies existing addresses, this mutation removes all current addresses and sets the provided list as the new delivery addresses. One address can be marked as selected, and each address can be flagged for one-time use or configured with a specific validation strategy. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required ### Arguments The ID of the cart. * addresses [\[Cart​Selectable​Address​Input!\]!](https://shopify.dev/docs/api/storefront/latest/input-objects/CartSelectableAddressInput) required A list of delivery addresses to replace on the cart. The input must not contain more than `250` values. *** * cart​Delivery​Addresses​Update [Cart​Delivery​Addresses​Update​Payload](https://shopify.dev/docs/api/storefront/latest/types/CartDeliveryAddressesUpdatePayload) Updates one or more delivery addresses on a [`Cart`](https://shopify.dev/docs/api/storefront/2026-01/objects/Cart). Each address can be modified to change its details, set it as the pre-selected address for checkout, or mark it for one-time use so it isn't saved to the customer's account. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required ### Arguments The ID of the cart. * addresses [\[Cart​Selectable​Address​Update​Input!\]!](https://shopify.dev/docs/api/storefront/latest/input-objects/CartSelectableAddressUpdateInput) required The delivery addresses to update. The input must not contain more than `250` values. *** * cart​Discount​Codes​Update [Cart​Discount​Codes​Update​Payload](https://shopify.dev/docs/api/storefront/latest/types/CartDiscountCodesUpdatePayload) Updates the discount codes applied to a [`Cart`](https://shopify.dev/docs/api/storefront/2026-01/objects/Cart). This mutation replaces all existing discount codes with the provided list, so pass an empty array to remove all codes. Discount codes are case-insensitive. After updating, check each [`CartDiscountCode`](https://shopify.dev/docs/api/storefront/2026-01/objects/CartDiscountCode) in the cart's [`discountCodes`](https://shopify.dev/docs/api/storefront/2026-01/objects/Cart#field-Cart.fields.discountCodes) field to see whether the code is applicable to the cart's current contents. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required ### Arguments The ID of the cart. * discount​Codes [\[String!\]!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required The case-insensitive discount codes that the customer added at checkout. The input must not contain more than `250` values. *** * cart​Gift​Card​Codes​Add [Cart​Gift​Card​Codes​Add​Payload](https://shopify.dev/docs/api/storefront/latest/types/CartGiftCardCodesAddPayload) Adds gift card codes to a [`Cart`](https://shopify.dev/docs/api/storefront/2026-01/objects/Cart) without replacing any codes already applied. Gift card codes are case-insensitive. To replace all gift card codes instead of adding to them, use [`cartGiftCardCodesUpdate`](https://shopify.dev/docs/api/storefront/2026-01/mutations/cartGiftCardCodesUpdate). * cart​Id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required ### Arguments The ID of the cart. * gift​Card​Codes [\[String!\]!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required The case-insensitive gift card codes to add. The input must not contain more than `250` values. *** * cart​Gift​Card​Codes​Remove [Cart​Gift​Card​Codes​Remove​Payload](https://shopify.dev/docs/api/storefront/latest/types/CartGiftCardCodesRemovePayload) Removes gift cards from a [`Cart`](https://shopify.dev/docs/api/storefront/2026-01/objects/Cart) using their IDs. You can retrieve the IDs of applied gift cards from the cart's [`appliedGiftCards`](https://shopify.dev/docs/api/storefront/2026-01/objects/Cart#field-Cart.fields.appliedGiftCards) field. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required ### Arguments The ID of the cart. * applied​Gift​Card​Ids [\[ID!\]!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required The gift cards to remove. The input must not contain more than `250` values. *** * cart​Gift​Card​Codes​Update [Cart​Gift​Card​Codes​Update​Payload](https://shopify.dev/docs/api/storefront/latest/types/CartGiftCardCodesUpdatePayload) Updates the gift card codes applied to the cart. Unlike [`cartGiftCardCodesAdd`](https://shopify.dev/docs/api/storefront/2026-01/mutations/cartGiftCardCodesAdd), which adds codes without replacing existing ones, this mutation sets the gift card codes for the cart. Gift card codes are case-insensitive. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required ### Arguments The ID of the cart. * gift​Card​Codes [\[String!\]!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required The case-insensitive gift card codes. The input must not contain more than `250` values. *** * cart​Lines​Add [Cart​Lines​Add​Payload](https://shopify.dev/docs/api/storefront/latest/types/CartLinesAddPayload) Adds one or more merchandise lines to an existing [`Cart`](https://shopify.dev/docs/api/storefront/2026-01/objects/Cart). Each line specifies the [product variant](https://shopify.dev/docs/api/storefront/2026-01/objects/ProductVariant) to purchase. Quantity defaults to `1` if not provided. You can add up to 250 lines in a single request. Use [`CartLineInput`](https://shopify.dev/docs/api/storefront/2026-01/input-objects/CartLineInput) to configure each line's merchandise, quantity, selling plan, custom attributes, and any parent relationships for nested line items such as warranties or add-ons. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required ### Arguments The ID of the cart. * lines [\[Cart​Line​Input!\]!](https://shopify.dev/docs/api/storefront/latest/input-objects/CartLineInput) required A list of merchandise lines to add to the cart. The input must not contain more than `250` values. *** * cart​Lines​Remove [Cart​Lines​Remove​Payload](https://shopify.dev/docs/api/storefront/latest/types/CartLinesRemovePayload) Removes one or more merchandise lines from a [`Cart`](https://shopify.dev/docs/api/storefront/2026-01/objects/Cart). Accepts up to 250 line IDs per request. Returns the updated cart along with any errors or warnings. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required ### Arguments The ID of the cart. * line​Ids [\[ID!\]!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required The merchandise line IDs to remove. The input must not contain more than `250` values. *** * cart​Lines​Update [Cart​Lines​Update​Payload](https://shopify.dev/docs/api/storefront/latest/types/CartLinesUpdatePayload) Updates one or more merchandise lines on a [`Cart`](https://shopify.dev/docs/api/storefront/2026-01/objects/Cart). You can modify the quantity, swap the merchandise, change custom attributes, or update the selling plan for each line. You can update a maximum of 250 lines per request. Omitting the [`attributes`](https://shopify.dev/docs/api/storefront/2026-01/mutations/cartLinesUpdate#arguments-lines.fields.attributes) field or setting it to null preserves existing line attributes. Pass an empty array to clear all attributes from a line. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required ### Arguments The ID of the cart. * lines [\[Cart​Line​Update​Input!\]!](https://shopify.dev/docs/api/storefront/latest/input-objects/CartLineUpdateInput) required The merchandise lines to update. The input must not contain more than `250` values. *** * cart​Metafield​Delete [Cart​Metafield​Delete​Payload](https://shopify.dev/docs/api/storefront/latest/types/CartMetafieldDeletePayload) Deletes a cart metafield. *** **Note:** This mutation won\'t trigger \Shopify Functions\. The changes won\'t be available to Shopify Functions until the buyer goes to checkout or performs another cart interaction that triggers the functions. *** * input [Cart​Metafield​Delete​Input!](https://shopify.dev/docs/api/storefront/latest/input-objects/CartMetafieldDeleteInput) required ### Arguments The input fields used to delete a cart metafield. *** * cart​Metafields​Set [Cart​Metafields​Set​Payload](https://shopify.dev/docs/api/storefront/latest/types/CartMetafieldsSetPayload) Sets [`Metafield`](https://shopify.dev/docs/api/storefront/2026-01/objects/Metafield) values on a cart, creating new metafields or updating existing ones. Accepts up to 25 metafields per request. Cart metafields can automatically copy to order metafields when an order is created, if there's a matching order metafield definition with the [cart to order copyable](https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities#cart-to-order-copyable) capability enabled. *** **Note:** This mutation doesn\'t trigger \Shopify Functions\. Changes aren\'t available to Shopify Functions until the buyer goes to checkout or performs another cart interaction that triggers the functions. *** * metafields [\[Cart​Metafields​Set​Input!\]!](https://shopify.dev/docs/api/storefront/latest/input-objects/CartMetafieldsSetInput) required ### Arguments The list of Cart metafield values to set. Maximum of 25. The input must not contain more than `250` values. *** * cart​Note​Update [Cart​Note​Update​Payload](https://shopify.dev/docs/api/storefront/latest/types/CartNoteUpdatePayload) Updates the note on a [`Cart`](https://shopify.dev/docs/api/storefront/2026-01/objects/Cart). The note is a text field that stores additional information, such as a personalized message from the buyer or special instructions for the order. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required ### Arguments The ID of the cart. * note [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required The note on the cart. *** * cart​Selected​Delivery​Options​Update [Cart​Selected​Delivery​Options​Update​Payload](https://shopify.dev/docs/api/storefront/latest/types/CartSelectedDeliveryOptionsUpdatePayload) Updates the selected delivery option for one or more [`CartDeliveryGroup`](https://shopify.dev/docs/api/storefront/2026-01/objects/CartDeliveryGroup) objects in a cart. Each delivery group represents items shipping to a specific address and offers multiple delivery options with different costs and methods. Use this mutation when a customer chooses their preferred shipping method during checkout. The [`deliveryOptionHandle`](https://shopify.dev/docs/api/storefront/2026-01/input-objects/CartSelectedDeliveryOptionInput#field-CartSelectedDeliveryOptionInput.fields.deliveryOptionHandle) identifies which [`CartDeliveryOption`](https://shopify.dev/docs/api/storefront/2026-01/objects/CartDeliveryOption) to select for each delivery group. * cart​Id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required ### Arguments The ID of the cart. * selected​Delivery​Options [\[Cart​Selected​Delivery​Option​Input!\]!](https://shopify.dev/docs/api/storefront/latest/input-objects/CartSelectedDeliveryOptionInput) required The selected delivery options. The input must not contain more than `250` values. *** * customer​Access​Token​Create [Customer​Access​Token​Create​Payload](https://shopify.dev/docs/api/storefront/latest/types/CustomerAccessTokenCreatePayload) Token access required For legacy customer accounts only. Creates a [`CustomerAccessToken`](https://shopify.dev/docs/api/storefront/2026-01/objects/CustomerAccessToken) using the customer's email and password. The access token is required to read or modify the [`Customer`](https://shopify.dev/docs/api/storefront/2026-01/objects/Customer) object, such as updating account information or managing addresses. The token has an expiration time. Use [`customerAccessTokenRenew`](https://shopify.dev/docs/api/storefront/2026-01/mutations/customerAccessTokenRenew) to extend the token before it expires, or create a new token if it's already expired. *** **Caution:** This mutation handles customer credentials. Always transmit requests over HTTPS and never log or expose the password. *** * input [Customer​Access​Token​Create​Input!](https://shopify.dev/docs/api/storefront/latest/input-objects/CustomerAccessTokenCreateInput) required ### Arguments The fields used to create a customer access token. *** * customer​Access​Token​Create​With​Multipass [Customer​Access​Token​Create​With​Multipass​Payload](https://shopify.dev/docs/api/storefront/latest/types/CustomerAccessTokenCreateWithMultipassPayload) Token access required Creates a [`CustomerAccessToken`](https://shopify.dev/docs/api/storefront/2026-01/objects/CustomerAccessToken) using a [multipass token](https://shopify.dev/docs/api/multipass) instead of email and password. This enables single sign-on for customers who authenticate through an external system. If the customer doesn't exist in Shopify, then a new customer record is created automatically. If the customer exists but the record is disabled, then the customer record is re-enabled. *** **Caution:** Multipass tokens are only valid for 15 minutes and can only be used once. Generate tokens on-the-fly when needed rather than in advance. *** * multipass​Token [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required ### Arguments A valid [multipass token](https://shopify.dev/api/multipass) to be authenticated. *** * customer​Access​Token​Delete [Customer​Access​Token​Delete​Payload](https://shopify.dev/docs/api/storefront/latest/types/CustomerAccessTokenDeletePayload) Token access required Permanently destroys a [`CustomerAccessToken`](https://shopify.dev/docs/api/storefront/2026-01/objects/CustomerAccessToken). Use this mutation when a customer explicitly signs out or when you need to revoke the token. Use [`customerAccessTokenCreate`](https://shopify.dev/docs/api/storefront/2026-01/mutations/customerAccessTokenCreate) to generate a new token with the customer's credentials. *** **Caution:** This action is irreversible. The customer needs to sign in again to obtain a new access token. *** * customer​Access​Token [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required ### Arguments The access token used to identify the customer. *** * customer​Access​Token​Renew [Customer​Access​Token​Renew​Payload](https://shopify.dev/docs/api/storefront/latest/types/CustomerAccessTokenRenewPayload) Token access required Extends the validity of a [`CustomerAccessToken`](https://shopify.dev/docs/api/storefront/2026-01/objects/CustomerAccessToken) before it expires. The renewed token maintains authenticated access to customer operations. Renewal must happen before the token's [`expiresAt`](https://shopify.dev/docs/api/storefront/2026-01/objects/CustomerAccessToken#field-CustomerAccessToken.fields.expiresAt) time. If a token has already expired, then use [`customerAccessTokenCreate`](https://shopify.dev/docs/api/storefront/2026-01/mutations/customerAccessTokenCreate) to generate a new token with the customer's credentials. *** **Caution:** Store access tokens securely. Never store tokens in plain text or insecure locations, and avoid exposing them in URLs or logs. *** * customer​Access​Token [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required ### Arguments The access token used to identify the customer. *** * customer​Activate [Customer​Activate​Payload](https://shopify.dev/docs/api/storefront/latest/types/CustomerActivatePayload) Token access required Activates a customer account using an activation token received from the [`customerCreate`](https://shopify.dev/docs/api/storefront/2026-01/mutations/customerCreate) mutation. The customer sets their password during activation and receives a [`CustomerAccessToken`](https://shopify.dev/docs/api/storefront/2026-01/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-01/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 [Customer​Activate​By​Url​Payload](https://shopify.dev/docs/api/storefront/latest/types/CustomerActivateByUrlPayload) Token access required Activates a customer account using the full activation URL from the [`customerCreate`](https://shopify.dev/docs/api/storefront/2026-01/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-01/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​Address​Create [Customer​Address​Create​Payload](https://shopify.dev/docs/api/storefront/latest/types/CustomerAddressCreatePayload) Token access required Creates a new [`MailingAddress`](https://shopify.dev/docs/api/storefront/2026-01/objects/MailingAddress) for a [`Customer`](https://shopify.dev/docs/api/storefront/2026-01/objects/Customer). Use the customer's [access token](https://shopify.dev/docs/api/storefront/2026-01/mutations/customerAddressCreate#arguments-customerAccessToken) to identify them. Successful creation returns the new address. Each customer can have multiple addresses. * customer​Access​Token [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required ### Arguments The access token used to identify the customer. * address [Mailing​Address​Input!](https://shopify.dev/docs/api/storefront/latest/input-objects/MailingAddressInput) required The customer mailing address to create. *** * customer​Address​Delete [Customer​Address​Delete​Payload](https://shopify.dev/docs/api/storefront/latest/types/CustomerAddressDeletePayload) Token access required Permanently deletes a specific [`MailingAddress`](https://shopify.dev/docs/api/storefront/2026-01/objects/MailingAddress) for a [`Customer`](https://shopify.dev/docs/api/storefront/2026-01/objects/Customer). Requires a valid [customer access token](https://shopify.dev/docs/api/storefront/2026-01/mutations/customerAddressDelete#arguments-customerAccessToken) to authenticate the request. *** **Caution:** This action is irreversible. You can\'t recover the deleted address. *** * id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required ### Arguments Specifies the address to delete. * customer​Access​Token [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required The access token used to identify the customer. *** * customer​Address​Update [Customer​Address​Update​Payload](https://shopify.dev/docs/api/storefront/latest/types/CustomerAddressUpdatePayload) Token access required Updates an existing [`MailingAddress`](https://shopify.dev/docs/api/storefront/2026-01/objects/MailingAddress) for a [`Customer`](https://shopify.dev/docs/api/storefront/2026-01/objects/Customer). Requires a [customer access token](https://shopify.dev/docs/api/storefront/2026-01/mutations/customerAddressUpdate#arguments-customerAccessToken) to identify the customer, an ID to specify which address to modify, and an [`address`](https://shopify.dev/docs/api/storefront/2026-01/input-objects/MailingAddressInput) with the updated fields. Successful update returns the updated [`MailingAddress`](https://shopify.dev/docs/api/storefront/2026-01/objects/MailingAddress). * customer​Access​Token [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required ### Arguments The access token used to identify the customer. * id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) required Specifies the customer address to update. * address [Mailing​Address​Input!](https://shopify.dev/docs/api/storefront/latest/input-objects/MailingAddressInput) required The customer’s mailing address. *** * customer​Create [Customer​Create​Payload](https://shopify.dev/docs/api/storefront/latest/types/CustomerCreatePayload) Token access required Creates a new [`Customer`](https://shopify.dev/docs/api/storefront/2026-01/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 [Customer​Default​Address​Update​Payload](https://shopify.dev/docs/api/storefront/latest/types/CustomerDefaultAddressUpdatePayload) Token access required Updates the default address of an existing [`Customer`](https://shopify.dev/docs/api/storefront/2026-01/objects/Customer). Requires a [customer access token](https://shopify.dev/docs/api/storefront/2026-01/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​Recover [Customer​Recover​Payload](https://shopify.dev/docs/api/storefront/latest/types/CustomerRecoverPayload) Token access required Sends a reset password email to the customer. The email contains a reset password URL and token that you can pass to the [`customerResetByUrl`](https://shopify.dev/docs/api/storefront/2026-01/mutations/customerResetByUrl) or [`customerReset`](https://shopify.dev/docs/api/storefront/2026-01/mutations/customerReset) mutation to reset the customer's password. This mutation is throttled by IP. With private access, you can provide a [`Shopify-Storefront-Buyer-IP` header](https://shopify.dev/docs/api/usage/authentication#optional-ip-header) instead of the request IP. The header is case-sensitive. *** **Caution:** Ensure the value provided to \\Shopify-Storefront-Buyer-I\P\\ is trusted. Unthrottled access to this mutation presents a security risk. *** * email [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required ### Arguments The email address of the customer to recover. *** * customer​Reset [Customer​Reset​Payload](https://shopify.dev/docs/api/storefront/latest/types/CustomerResetPayload) Token access required 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-01/objects/Customer) and a new [`CustomerAccessToken`](https://shopify.dev/docs/api/storefront/2026-01/objects/CustomerAccessToken) for immediate authentication. Use the [`customerRecover`](https://shopify.dev/docs/api/storefront/2026-01/mutations/customerRecover) mutation to send the password recovery email that provides the reset token. Alternatively, use [`customerResetByUrl`](https://shopify.dev/docs/api/storefront/2026-01/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 [Customer​Reset​By​Url​Payload](https://shopify.dev/docs/api/storefront/latest/types/CustomerResetByUrlPayload) Token access required 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-01/mutations/customerRecover) mutation. On success, returns the updated [`Customer`](https://shopify.dev/docs/api/storefront/2026-01/objects/Customer) and a new [`CustomerAccessToken`](https://shopify.dev/docs/api/storefront/2026-01/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 [Customer​Update​Payload](https://shopify.dev/docs/api/storefront/latest/types/CustomerUpdatePayload) Token access required Updates a [customer's](https://shopify.dev/docs/api/storefront/2026-01/objects/Customer) personal information such as name, password, and marketing preferences. Requires a valid [`CustomerAccessToken`](https://shopify.dev/docs/api/storefront/2026-01/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. *** * shop​Pay​Payment​Request​Session​Create [Shop​Pay​Payment​Request​Session​Create​Payload](https://shopify.dev/docs/api/storefront/latest/types/ShopPayPaymentRequestSessionCreatePayload) Creates a [Shop Pay payment request session](https://shopify.dev/docs/api/storefront/2026-01/objects/ShopPayPaymentRequestSession) for processing payments. The session includes a checkout URL where customers complete their purchase and a token for subsequent operations like submitting the payment. The `sourceIdentifier` must be unique across all orders to ensure accurate reconciliation. For a complete integration guide including the JavaScript SDK setup and checkout flow, refer to the [Shop Component API documentation](https://shopify.dev/docs/api/commerce-components/pay). For implementation steps, see the [development journey guide](https://shopify.dev/docs/api/commerce-components/pay/development-journey). For common error scenarios, see the [troubleshooting guide](https://shopify.dev/docs/api/commerce-components/pay/troubleshooting-guide). * source​Identifier [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required ### Arguments A unique identifier for the payment request session. * payment​Request [Shop​Pay​Payment​Request​Input!](https://shopify.dev/docs/api/storefront/latest/input-objects/ShopPayPaymentRequestInput) required A payment request object. *** * shop​Pay​Payment​Request​Session​Submit [Shop​Pay​Payment​Request​Session​Submit​Payload](https://shopify.dev/docs/api/storefront/latest/types/ShopPayPaymentRequestSessionSubmitPayload) Finalizes a [Shop Pay payment request session](https://shopify.dev/docs/api/storefront/2026-01/objects/ShopPayPaymentRequestSession). Call this mutation after creating a session with [`shopPayPaymentRequestSessionCreate`](https://shopify.dev/docs/api/storefront/2026-01/mutations/shopPayPaymentRequestSessionCreate). The [`idempotencyKey`](https://shopify.dev/docs/api/storefront/2026-01/mutations/shopPayPaymentRequestSessionSubmit#arguments-idempotencyKey) argument ensures the payment transaction occurs only once, preventing duplicate charges. On success, returns a [`ShopPayPaymentRequestReceipt`](https://shopify.dev/docs/api/storefront/2026-01/objects/ShopPayPaymentRequestReceipt) with the processing status and a receipt token. For a complete integration guide including the JavaScript SDK setup and checkout flow, refer to the [Shop Component API documentation](https://shopify.dev/docs/api/commerce-components/pay). For implementation steps, see the [development journey guide](https://shopify.dev/docs/api/commerce-components/pay/development-journey). For common error scenarios, see the [troubleshooting guide](https://shopify.dev/docs/api/commerce-components/pay/troubleshooting-guide). * token [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required ### Arguments A token representing a payment session request. * payment​Request [Shop​Pay​Payment​Request​Input!](https://shopify.dev/docs/api/storefront/latest/input-objects/ShopPayPaymentRequestInput) required The final payment request object. * idempotency​Key [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required The idempotency key is used to guarantee an idempotent result. * order​Name [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) The order name to be used for the order created from the payment request. *** *** ## Map No referencing types