All Tutorials

Update customer data with Storefront API

All Tutorials

Update customer data with Storefront API

Update customer data with Storefront API

This guide covers creating and updating customers using the Storefront API. You'll learn how to create a customer, generate access tokens, and do a few common tasks such as associating an address with a customer and recovering a customer's password.

Prerequisites

The guide assumes you're authenticated with the Storefront API, and that you have a storefront access token.

Creating the customer

You can create a customer using the customerCreate mutation. You can use this mutation to create a sign-up form on your custom storefront that provides the customer with an account on the Shopify store.

If the mutation is successful, then a welcome email is sent to the customer with the information that their account has been activated.

POST /api/2020-10/graphql.json

mutation customerCreate($input: CustomerCreateInput!) {
  customerCreate(input: $input) {
    customerUserErrors {
      code
      field
      message
    }
    customer {
      id
    }
  }
}

Variables

{
  "input": {
    "email": "user@example.com",
    "password": "HiZqFuDvDdQ7"
  }
}

Response

{
  "data": {
    "customerCreate": {
      "customerUserErrors": [],
      "customer": {
        "id": "Z2lkOi8vc2hvcGlmeS9DdXN0b21lci8xNzk4OTQ5MTA5ODI="
      }
    }
  }
}

Activating customers

If you pass an existing customer to customerCreate, then the mutation returns the following error:

{
  "customerUserErrors": [
    {
      "code": "CUSTOMER_DISABLED",
      "field": null,
      "message": "We have sent an email to example.customer@example.com, please click the link included to verify your email address."
    }
  ]
}

In this case, the customer account already exists, but it's disabled and needs to be activated. Instead of creating a new account, the mutation triggers an account activation email to be sent to the customer. The email includes an account activation link to Shopify where the customer can activate their account. You can use the link's activation URL to activate the customer.

If you're using iOS universal links, then the Shopify account activation URL redirects to your native app. The app receives the activation URL as a request parameter.

If your app is a headless storefront, then you can update the merchant's notification templates to link to the area of your app where the customer creates a password. Append the activation URL to the link as a URL parameter. To learn more, refer to Update the account invite template.

When your app has the activation URL, you can activate the customer's account by using one of the following mutations:

Update the account invite template

Update the Customer account invite email template so that it links to wherever in your storefront the customer can enter a new password. Include {{ customer.account_activation_url }} as a URL parameter at the end of the link.

Steps:

  1. From the Shopify admin, go to Settings > Notifications.
  2. In the Customers notifications section, click Customer account invite email template.
  3. In the template editor, update the Activate your account link to point to your storefront's account activation page. Pass the activation URL as a URL parameter by appending ?activation_url={{ customer.account_activation_url }}. For example:

    <td class="button__cell"><a href="https://www.my-app-domain.com/activate/?activation_url={{ customer.account_activation_url }}" class="button__text">Activate your account</a></td>

In the email notifications, the Activate your account link will be rendered with the customer's unique password reset URL:

<a href="https://www.my-app-domain.com/reset/?reset_url=https://a-merchant-store.myshopify.com/account/activate/3298995959864/e692decd24f9e5c6afe6200cd76b0aa4-1580934846">Activate your account</a>

customerActivate

Use the customerActivate mutation to send the customer's new password and an activation token to Shopify. The activation token is included in the account activation URL:

<a href="https://example.myshopify.com/account/activate/<customer_id>/<activation_token>">Activate your account</a>

The following mutation takes the activationToken from the Shopify account activation URL and sends it to Shopify along with the customer's password.

mutation customerActivate($id: ID!, $input: CustomerActivateInput!) {
  customerActivate(id: $id, input: $input) {
    customerUserErrors {
      code
      field
      message
    }
    customer {
      id
    }
  }
}

Variables

{
  "id": "Z2lkOi8vU2hvcGlmeS9FeGFtcGxlLzE=",
  "input": {
    "activationToken": "ae0f1d2e179c9571122a0595a6ac8125",
    "password": "HiZqFuDvDdQ7"
  }
}

customerActivateByUrl

Use the customerActivateByUrl mutation to send the customer's password and activation URL to Shopify. With this method, you don't need to parse the activation URL to extract the activation token.

Customer account activation workflow using customerActivateByUrl

POST /api/2020-04/graphql.json

mutation($activationUrl: URL!, $password: String!){
  customerActivateByUrl(
    activationUrl: $activationUrl,
    password: $password
  ) {
    customer { id }
    customerUserErrors { code field message }
  }
}

Variables

{
  "activationUrl": "https://a-merchant-store.myshopify.com/account/activate/2198995959864/66741d7259ddfcd54962e2f4989a28b0-1581021688",
  "password": "dihwlDJ37^&j"
}

Response

{
  "data": {
    "customerActivateByUrl": {
      "customer": {
        "id": "Z2lkOi8vc2hvcGlmeS9DdXN0b21lci8yMTk4OTk1OTU5ODY0",
      },
      "customerUserErrors": []
    }
  }
}

Creating an access token

After the customer account is created on your store, the customer can log in to their account. To log in a customer, you need to exchange their credentials for a customer access token. With an access token, you can query for customer data and perform update actions, such as associating an address with the customer.

To create a customer access token, you can use the following mutations:

customerAccessTokenCreate

The following mutation creates the access token:

POST /api/2020-10/graphql.json

mutation customerAccessTokenCreate($input: CustomerAccessTokenCreateInput!) {
  customerAccessTokenCreate(input: $input) {
    customerUserErrors {
      code
      field
      message
    }
    customerAccessToken {
      accessToken
      expiresAt
    }
  }
}

Variables

{
  "input": {
    "email": "user@example.com",
    "password": "HiZqFuDvDdQ7"
  }
}

Response

{
  "data": {
    "customerAccessTokenCreate": {
      "customerUserErrors": [],
      "customerAccessToken": {
        "accessToken": "5df718033d4765153f76470badab4c7c",
        "expiresAt": "2018-02-27T20:23:18Z"
      }
    }
  }
}

customerAccessTokenCreateWithMultipass

If you have a valid Multipass token for a customer, then you can exchange it for a customer access token by using the customerAccessTokenCreateWithMultipass mutation. When you redirect a Multipass customer to a store, customerAccessTokenCreateWithMultipass lets you generate an access token without the customer needing to provide their credentials.

If the customer doesn't exist in Shopify, then a new customer is created with the Multipass credentials. To learn more, refer to Multipass.

Viewing orders workflow using customerAccessTokenCreateWithMultipass

Checkout workflow using customerAccessTokenCreateWithMultipass

POST /api/2020-04/graphql.json

mutation($multipassToken: String!) {
  customerAccessTokenCreateWithMultipass(multipassToken: $multipassToken) {
    customerAccessToken { accessToken expiresAt }
    customerUserErrors { code field message }
  }
}

Variables

{
  "multipassToken": "RwANseawzCPlSobjxHTjCnHhnPOGgPJ-ruJ_fofUBO0pVn4ZDH6X1vxPVg6iPJD44OIXyEuD9V6TcP6a7eXGt5SN1npgO_OkyrFuR68BOeTJEkdvwTepNnqQklUGHYmG8CeR-9dk_utQnmQLRvpUKUSD6IVrTl9onyx09YIWRY7w67alquHdqF_mazvnl0Gv-Lp5-rqyTaMSKRpOxQCw0PX4z0ZTsG0mel9VW12N5I7yUOM8lpvi0y7LuFHqmzGOzTixGFcVGdp5ib_tca3Q54rbIHMYlo8Arz_ooUkkn8xeX8E-YwmqHSaePWOGjaliyPhT0NAckT8rI1ywdxw1x7mncvtisgfqmPlzTITT845r87zi1q4wbRlGf1pWzOMGD4xkVFmlPFIm_YNhKKuCE6XQmnaQ3Jh-q2a-4Yw26SuHpCImm70eeoBdWIJEs6bEz6AUlilBGg7NeAKj_jQNgYypJ0GJyFIXUipa8VpQa1b_NS4IRyircaVj_i1F0rcnaZgkeZiOqHYdeKwxGtp-8XowHMeSrnG8P3N_ON_SXIDJOXXkKf3rrGDCmJciFbDKjcC0Xf1vFRcj_fwpPm0zLQ=="
}

Response

{
  "data": {
    "customerAccessTokenCreateWithMultipass": {
      "customerAccessToken": {
        "accessToken": "59fa4a5971e010ba63fdb19dbe21d671",
        "expiresAt": "2020-03-20T14:34:43Z"
      },
      "customerUserErrors": []
    }
  }
}

Updating the address

When you have a customer access token, you can use it to associate or update an address for the customer.

POST /api/2020-10/graphql.json

mutation customerAddressCreate($customerAccessToken: String!, $address: MailingAddressInput!) {
  customerAddressCreate(customerAccessToken: $customerAccessToken, address: $address) {
    customerUserErrors {
      code
      field
      message
    }
    customerAddress {
      id
    }
  }
}

Variables

{
  "customerAccessToken": "e40e9017997a60ed8a6d7bf1f441d743",
  "address": {
    "lastName": "Doe",
    "firstName": "John",
    "address1": "123 Test Street",
    "province": "QC",
    "country": "Canada",
    "zip": "H3K0X2",
    "city": "Montreal"
  }
}

Response

{
  "data": {
    "customerAddressCreate": {
      "customerUserErrors": [],
      "customerAddress": {
        "id": "Z2lkOi8vc2hvcGlmeS9NYWlsaW5nQWRkcmVzcy8yMTg3MDUxOTkxMTA/bW9kZWxfbmFtZT1DdXN0b21lckFkZHJlc3MmY3VzdG9tZXJfYWNjZXNzX3Rva2VuPWU0MGU5MDE3OTk3YTYwZWQ4YTZkN2JmMWY0NDFkNzQz"
      }
    }
  }
}

Recovering and resetting passwords

You can use the customerRecover mutation to implement a password recovery flow on your custom storefront. The mutation requires the customer's email address and is used to send an email with a link to reset the password.

The following mutation recovers the customer's password:

POST /api/2020-10/graphql.json

mutation customerRecover($email: String!) {
  customerRecover(email: $email) {
    customerUserErrors {
      code
      field
      message
    }
  }
}

Variables

{
  "email": "user@example.com"
}

In response to a successful mutation, an email is sent with a reset password link. Clicking the link directs the customer to the Shopify account reset URL.

Using the customerReset mutation

If you're using iOS universal links, then the Shopify account reset redirect URL redirects to your native app. In this case, you can use the customerReset mutation to send the customer's new password and reset token to Shopify. The reset token is included in the account reset redirect URL.

The following mutation takes the reset token from the Shopify account reset URL and sends it to Shopify along with the customer's new password:

POST /api/2020-10/graphql.json

mutation customerReset($id: ID!, $input: CustomerResetInput!) {
  customerReset(id: $id, input: $input) {
    customerUserErrors {
      code
      field
      message
    }
    customer {
      id
    }
  }
}

Variables

{
  "id": "Z2lkOi8vU2hvcGlmeS9FeGFtcGxlLzE=",
  "input": {
    "resetToken": "ae0f1d2e179c9571122a0595a6ac8125",
    "password": "HiZqFuDvDdQ7"
  }
}

Response

{
  "data": {
    "customerReset": {
      "customerUserErrors": [],
      "customer": {
        "id": "Z2lkOi8vc2hvcGlmeS9DdXN0b21lci8xNzk4OTQ5MTA5ODI="
      }
    }
  }
}

Using the customerResetByUrl mutation

The customerResetByUrl mutation updates a customer's password by identifying the customer by their unique password-reset URL. This is the URL that's generated by the customer.reset_password_url Liquid variable.

The benefit of using customerResetByUrl over customerReset is that you don't need the customer's ID to identify the customer.

To pass the password-reset URL to your storefront, include customer.reset_password_url in the password reset email template.

Update the password reset template

Update the Customer account password reset email template so that it links to wherever in your storefront the customer can enter a new password. Include {{ customer.reset_password_url }} as a URL parameter at the end of the link.

Steps:

  1. From the Shopify admin, go to Settings > Notifications.
  2. In the Customers notifications section, click Customer account password reset email template.
  3. In the template editor, update the Reset your password link to point to your storefront's password reset page. Pass the password reset URL as a URL parameter by appending ?reset_url={{ customer.reset_password_url }}:

    <td class="button__cell"><a href="https://www.my-app-domain.com/reset/?reset_url={{ customer.reset_password_url }}" class="button__text">Reset your password</a></td>

In the email notifications, the Reset your password link will be rendered with the customer's unique password reset URL:

<a href="https://www.my-app-domain.com/reset/?reset_url=https://a-merchant-store.myshopify.com/account/reset/2198995959864/e692decd24f9e5c6afe6200cd76b0aa4-1580934624">Reset your password</a>

Send a password recovery email

To let a customer enter a new password, use the the customerRecover mutation to send a password-reset emails to the them: POST /api/2020-10/graphql.json

mutation sendPasswordRecoverEmail {
  customerRecover(email: "greg.piotrowski1@teleworm.us") {
    customerUserErrors { code field message }
  }
}

Use the reset URL to reset the password

When a customer clicks the password-reset link and is directed to your storefront, get the password reset URL from the request parameters. Use the customerResetByUrl mutation to reset the customer's password. Pass the password reset URL as the resetUrl argument, and the customer's new password as the password argument.

POST /api/2020-10/graphql.json

mutation resetPasswordByUrl($resetUrl: URL!, $password: String!) {
  customerResetByUrl(resetUrl: $resetUrl, password: $password) {
    customer { id }
    customerUserErrors { code field message}
  }
}

Variables

{
  "resetUrl": "https://a-merchant-store.myshopify.com/account/reset/2198995959864/e692decd24f9e5c6afe6200cd76b0aa4-1580934624",
  "password": "DV]C34QN67"
}

Response

{
  "data": {
    "customerResetByUrl": {
      "customer": {
        "id": "Z2lkOi8vc2hvcGlmeS9DdXN0b21lci8yMTk4OTk1OTU5ODY0"
      },
      "customerUserErrors": []
    }
  }
}