GraphQL Storefront API: customers (beta)

ℹ️

This feature of the GraphQL Storefront API is currently in beta.

BigCommerce's GraphQL Storefront API provides the same access to customer objects as the REST Storefront API in addition to supporting some of the same actions as the REST Management API.

Developers can use GraphQL Storefront API to create an end-to-end shopper experience and manage some customer account use cases. Customer mutations and queries can do the following:

Register a customer
Update a customer
Add a customer address
Update a customer address
Delete a customer address
Change a customer password
Request a password reset
Reset a password

Authentication

To make requests, create a store-level or app-level API account with one or more of the following token creation OAuth scopes:

UI Name	Permission	Parameter	Description
Storefront API tokens	modify	`store_storefront-api`	Create payment access tokens, process payments
Storefront API customer impersonation tokens	modify	`store_storefront_api_customer_impersonation`	Create GraphQL Storefront API bearer tokens that allow customer impersonation

No additional scopes are required to use the GraphQL Storefront API. For more information, see token creation OAuth scopes.

To generate a bearer token your application can pass to authenticate calls to the GraphQL Storefront API, using either the Create a storefront token or the Create a customer impersonation token REST endpoint. On a Stencil storefront, you can also access a token directly from the page context. Learn more about Using auto-generated tokens in Stencil themes.

For more information, see Creating a token in the GraphQL Storefront API overview and Dynamic tokens in the Authentication and example requests article.

reCAPTCHA

Captcha is not required when the reCAPTCHA setting is disabled in the control panel. Be sure to use a valid user verification response reCAPTCHA token if reCAPTCHA is enabled.

Customer impersonation tokens do not require the use of reCAPTCHA even when the reCAPTCHA setting is enabled. You can bypass the reCAPTCHA and it will still function. If a reCAPTCHA value is provided it must be valid, or the request will be rejected.

Example queries and mutations

Register a customer

Register a customer using the form field configuration set up in the control panel for both the account signup and address fields.

Example mutation: Register a customer

mutation {
  customer {
    registerCustomer(
      reCaptchaV2: { token: "" }
      input: {
        firstName: "Jon"
        lastName: "Smith"
        email: "jon@test.com"
        password: "Password123!"
        phone: "123-456-7890"
        company: "BC"
        address: {
          firstName: "Jon"
          lastName: "Smith"
          address1: "1234 Fake Street"
          address2: ""
          city: "Austin"
          company: "BC"
          countryCode: "US"
          stateOrProvince: "TX"
          phone: "123-456-7890"
          postalCode: "78610"
        }
        formFields: {
          checkboxes: [{ fieldEntityId: 1, fieldValueEntityIds: [1, 2, 3] }]
          multipleChoices: [{ fieldEntityId: 1, fieldValueEntityId: 2 }]
          numbers: [{ fieldEntityId: 1, number: 1.0 }]
          texts: [{ fieldEntityId: 1, text: "text" }]
          passwords: [{ fieldEntityId: 1, password: "password" }]
        }
      }
    ) {
      customer {
        firstName
        lastName
      }
      errors {
        __typename
        ... on ValidationError {
          message
        }
        ... on CustomerRegistrationError {
          message
        }
        ... on EmailAlreadyInUseError {
          message
        }
        ... on AccountCreationDisabledError {
          message
        }
      }
    }
  }
}

Update a customer

Update customer information, except for password and address. Use either resetPassword, or changePassword to reset or update the user password.

Example mutation: Update a customer

mutation {
  customer {
    updateCustomer(
      reCaptchaV2: { token: "" }
      input: {
        firstName: "Jon"
        lastName: "Smith"
        email: "jon@test.com"
        phone: "123-456-7890"
        company: "BC"
        formFields: {
          # optional
          checkboxes: [{ fieldEntityId: 1, fieldValueEntityIds: [1, 2, 3] }]
          multipleChoices: [{ fieldEntityId: 1, fieldValueEntityId: 2 }]
          numbers: [{ fieldEntityId: 1, number: 1.0 }]
          texts: [{ fieldEntityId: 1, text: "text" }]
          passwords: [{ fieldEntityId: 1, password: "password" }]
        }
      }
    ) {
      customer {
        firstName
        lastName
      }
      errors {
        __typename
        ... on ValidationError {
          message
        }
        ... on CustomerDoesNotExistError {
          message
        }
        ... on EmailAlreadyInUseError {
          message
        }
      }
    }
  }
}

Add a customer address

Stores support several addresses per customer. Use the addCustomerAddress mutation to save one or more addresses to a customer account. Similar to registerCustomer, addCustomerAddress uses the form field configuration set up for address fields in the control panel.

Example mutation: Add a customer address

mutation {
  customer {
    addCustomerAddress(
      reCaptchaV2: { token: "" }
      input: {
        firstName: "Jon"
        lastName: "Smith"
        address1: "1234 Fake Street"
        address2: ""
        city: "Austin"
        company: "BC"
        countryCode: "US"
        stateOrProvince: "TX"
        phone: "123-456-7890"
        postalCode: "78610"
        formFields: {
          checkboxes: [{ fieldEntityId: 1, fieldValueEntityIds: [1, 2, 3] }]
          multipleChoices: [{ fieldEntityId: 1, fieldValueEntityId: 2 }]
          numbers: [{ fieldEntityId: 1, number: 1.0 }]
          texts: [{ fieldEntityId: 1, text: "text" }]
          passwords: [{ fieldEntityId: 1, password: "password" }]
        }
      }
    ) {
      errors {
        __typename
        ... on ValidationError {
          message
        }
        ... on CustomerNotLoggedInError {
          message
        }
        ... on CustomerAddressCreationError {
          message
        }
      }
    }
  }
}

Update a customer address

Use the updateCustomerAddress mutation when a customer needs to make changes to an address associated with their account.

Example mutation: Update a customer address

mutation {
  customer {
    updateCustomerAddress(
    reCaptchaV2: { token: "" },
    input: {
        addressEntityId: 1,
        data: {
        firstName: "Jon",
        lastName: "Smith",
        address1: "1234 Fake Street",
        address2: "",
        city: "Austin",
        company: "BC",
        countryCode: "US",
        stateOrProvince: "TX",
        phone: "123-456-7890",
        postalCode: "78610",
        formFields: {
            checkboxes: [
            {
                fieldEntityId: 1,
                fieldValueEntityIds: [1,2,3]
            }
            ],
            multipleChoices: [
            {
                fieldEntityId: 1,
                fieldValueEntityId: 2
            }
            ],
            numbers: [
            {
                fieldEntityId: 1,
                number: 1.0
            }
            ],
            texts: [
            {
                fieldEntityId: 1,
                text: "text"
            }
            ],
            passwords: [
            {
                fieldEntityId: 1,
                password: "password"
            }
            ],
        } 
        }
    }
    ) {
    errors {
        __typename
        ... on ValidationError {
        message
        }
        ... on CustomerNotLoggedInError {
        message
        }
        ... on AddressDoesNotExistError {
        message
        }
        ... on CustomerAddressUpdateError {
        message
        }
      }
    }
  }
}

Delete a customer address

Use the deleteCustomerAddress mutation when a customer needs to delete an address associated with their account.

Example mutation: Delete a customer address

mutation {
  customer {
    deleteCustomerAddress(
      reCaptchaV2: { token: "" }
      input: { addressEntityId: 1 }
    ) {
      errors {
        __typename
        ... on CustomerNotLoggedInError {
          message
        }
        ... on CustomerAddressDeletionError {
          message
        }
      }
    }
  }
}

Change a customer password

Use the changePassword mutation when the customer needs to update their password. The user must know their current password in order to complete the change using this mutation.

Example mutation: change a user password

mutation {
  customer {
    changePassword(
      input: { currentPassword: "Password1!", newPassword: "Password2!" }
    ) {
      errors {
        ... on ValidationError {
          path
          message
        }
        ... on CustomerPasswordError {
          message
        }
        ... on CustomerDoesNotExistError {
          message
        }
        ... on CustomerNotLoggedInError {
          message
        }
      }
    }
  }
}

Request a password reset

A customer can request a password reset using the requestResetPassword mutation.

Example mutation: Request a password reset

mutation {
  customer {
    requestResetPassword(
      reCaptchaV2: { token: "" }
      input: { email: "jon@test.com" }
    ) {
      errors {
        ... on ValidationError {
          message
        }
      }
    }
  }
}

Reset a password

When a customer needs a password reset, use the resetPassword mutation to complete the reset. You do not need to know the current password to use this mutation.

Example mutation: reset a password

mutation {
  customer {
    resetPassword(
      input: {
        customerEntityId: 1 # Provided in the link contained in the reset password email
        token: "" # Provided in the link contained in the reset password email
        newPassword: "NewPassword1234"
      }
    ) {
      errors {
        ... on ValidationError {
          message
        }
        ... on ChangePasswordError {
          message
        }
      }
    }
  }
}

Resources

Join our Developer community to share your feedback with us in the BigCommerceDevs Slack or on our Discord server. You can also use GitHub to ask a question (opens in a new tab) or report an issue (opens in a new tab).

Documentation

API reference

Authentication: storefront tokens

REST Management API: customers

Customers V3

Did you find what you were looking for?

Cart and Checkout Routes and Content