Skip to main content
Skip to Content
DocsStorefrontGraphQL Storefront APICustomers

GraphQL Storefront API: Customers

BigCommerce’s GraphQL Storefront API Customers powers access to customer objects such as the ability to update a customer, get a customer address book, reset a password, and more. 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
  • Get a customer address book

When you register, change, or reset a password, you can validate it using the password complexity requirements under the CustomersSettings node before submitting the desired password to the BigCommerce platform.

Tokens

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

UI NamePermissionParameterDescription
Storefront API tokensmodifystore_storefront-apiCreate payment access tokens, process payments
Storefront API customer impersonation tokensmodifystore_storefront_api_customer_impersonationCreate 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 authenticate calls to the GraphQL Storefront API, your application can generate a bearer token. This can be done by 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 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. Note, if reCAPTCHA is provided it must be valid, otherwise it 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: "John"
        lastName: "Smith"
        email: "[email protected]"
        password: "Password123!"
        phone: "123-456-7890"
        company: "BC"
        address: {
          firstName: "John"
          lastName: "Smith"
          address1: "123 Main Street"
          address2: "Suite 200"
          city: "Austin"
          company: "Acme Corporation"
          countryCode: "US"
          stateOrProvince: "TX"
          phone: "555-123-4567"
          postalCode: "78701"
        }
        formFields: {
          checkboxes: [{ fieldEntityId: 1, fieldValueEntityIds: [1, 2, 3] }]
          multipleChoices: [{ fieldEntityId: 1, fieldValueEntityId: 2 }]
          numbers: [{ fieldEntityId: 1, number: 1.0 }]
          texts: [{ fieldEntityId: 1, text: "Customer notes" }]
          passwords: [{ fieldEntityId: 1, password: "SecurePassword123!" }]
        }
      }
    ) {
      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: Customer update
mutation {
  customer {
    updateCustomer(
      reCaptchaV2: { token: "" }
      input: {
        firstName: "John"
        lastName: "Smith"
        email: "[email protected]"
        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: "Customer notes" }]
          passwords: [{ fieldEntityId: 1, password: "SecurePassword123!" }]
        }
      }
    ) {
      customer {
        firstName
        lastName
      }
      errors {
        __typename
        ... on ValidationError {
          message
        }
        ... on CustomerDoesNotExistError {
          message
        }
        ... on EmailAlreadyInUseError {
          message
        }
      }
    }
  }
}

Add a customer address

The BigCommerce platform can support and store plenty of addresses per customer. Use the addCustomerAddress to include multiple addresses to the customer account. Similar to registerCustomer, add CustomerAddress using the form field configuration set up in the control panel for address fields.

Example mutation: Add a customer address
mutation {
  customer {
    addCustomerAddress(
      reCaptchaV2: { token: "" }
      input: {
        firstName: "John"
        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: "Customer notes" }]
          passwords: [{ fieldEntityId: 1, password: "SecurePassword123!" }]
        }
      }
    ) {
      errors {
        __typename
        ... on ValidationError {
          message
        }
        ... on CustomerNotLoggedInError {
          message
        }
        ... on CustomerAddressCreationError {
          message
        }
      }
    }
  }
}

Update a customer address

Use this 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: "John",
        lastName: "Smith",
        address1: "123 Main Street",
        address2: "Suite 200",
        city: "Austin",
        company: "Acme Corporation",
        countryCode: "US",
        stateOrProvince: "TX",
        phone: "555-123-4567",
        postalCode: "78701",
        formFields: {
            checkboxes: [
            {
                fieldEntityId: 1,
                fieldValueEntityIds: [1,2,3]
            }
            ],
            multipleChoices: [
            {
                fieldEntityId: 1,
                fieldValueEntityId: 2
            }
            ],
            numbers: [
            {
                fieldEntityId: 1,
                number: 1.0
            }
            ],
            texts: [
            {
                fieldEntityId: 1,
                text: "Customer notes"
            }
            ],
            passwords: [
            {
                fieldEntityId: 1,
                password: "SecurePassword123!"
            }
            ],
        }
        }
    }
    ) {
    errors {
        __typename
        ... on ValidationError {
        message
        }
        ... on CustomerNotLoggedInError {
        message
        }
        ... on AddressDoesNotExistError {
        message
        }
        ... on CustomerAddressUpdateError {
        message
        }
      }
    }
  }
}

Delete a customer address

Use this delete 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 in cases where the customer needs to update their password. The user must know their current password in order to complete the change.

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 as seen below.

Example mutation: Request a password reset
mutation {
  customer {
    requestResetPassword(
      reCaptchaV2: { token: "" }
      input: { email: "[email protected]" }
    ) {
      errors {
        ... on ValidationError {
          message
        }
      }
    }
  }
}

Reset a password

When a customer needs a password reset, use the resetPassword example mutation to complete the reset.

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
        }
      }
    }
  }
}

Get a customer address book

Use this query to view all the addresses a customer has added to their account.

Example query: Get a customer address book
query {
    customer {
      firstName
      lastName
      formFields {
          entityId
          name
      }
      addresses {
          collectionInfo {
              totalItems
          }
          edges {
              node {
                  entityId
                  firstName
                  lastName
                  address1
                  city
                  stateOrProvince
                  postalCode
                  formFields {
                      entityId
                      name
                  }
              }
          }
      }
    }
}

Join our Developer community to share your feedback with us in the BigCommerceDevs Slack or on our Discord server.

Resources

Documentation

API reference

Storefront tokens

REST management API: customers

Community

Did you find what you were looking for?
Data eventsOrders