DocsStorefrontGuidesGraphQL Storefront

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
1mutation {
2  customer {
3    registerCustomer(
4      reCaptchaV2: { token: "" }
5      input: {
6        firstName: "John"
7        lastName: "Smith"
8        email: "jon@example.com"
9        password: "Password123!"
10        phone: "123-456-7890"
11        company: "BC"
12        address: {
13          firstName: "John"
14          lastName: "Smith"
15          address1: "123 Main Street"
16          address2: "Suite 200"
17          city: "Austin"
18          company: "Acme Corporation"
19          countryCode: "US"
20          stateOrProvince: "TX"
21          phone: "555-123-4567"
22          postalCode: "78701"
23        }
24        formFields: {
25          checkboxes: [{ fieldEntityId: 1, fieldValueEntityIds: [1, 2, 3] }]
26          multipleChoices: [{ fieldEntityId: 1, fieldValueEntityId: 2 }]
27          numbers: [{ fieldEntityId: 1, number: 1.0 }]
28          texts: [{ fieldEntityId: 1, text: "Customer notes" }]
29          passwords: [{ fieldEntityId: 1, password: "SecurePassword123!" }]
30        }
31      }
32    ) {
33      customer {
34        firstName
35        lastName
36      }
37      errors {
38        __typename
39        ... on ValidationError {
40          message
41        }
42        ... on CustomerRegistrationError {
43          message
44        }
45        ... on EmailAlreadyInUseError {
46          message
47        }
48        ... on AccountCreationDisabledError {
49          message
50        }
51      }
52    }
53  }
54}

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
1mutation {
2  customer {
3    updateCustomer(
4      reCaptchaV2: { token: "" }
5      input: {
6        firstName: "John"
7        lastName: "Smith"
8        email: "john@test.com"
9        phone: "123-456-7890"
10        company: "BC"
11        formFields: {
12          # optional
13          checkboxes: [{ fieldEntityId: 1, fieldValueEntityIds: [1, 2, 3] }]
14          multipleChoices: [{ fieldEntityId: 1, fieldValueEntityId: 2 }]
15          numbers: [{ fieldEntityId: 1, number: 1.0 }]
16          texts: [{ fieldEntityId: 1, text: "Customer notes" }]
17          passwords: [{ fieldEntityId: 1, password: "SecurePassword123!" }]
18        }
19      }
20    ) {
21      customer {
22        firstName
23        lastName
24      }
25      errors {
26        __typename
27        ... on ValidationError {
28          message
29        }
30        ... on CustomerDoesNotExistError {
31          message
32        }
33        ... on EmailAlreadyInUseError {
34          message
35        }
36      }
37    }
38  }
39}

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
1mutation {
2  customer {
3    addCustomerAddress(
4      reCaptchaV2: { token: "" }
5      input: {
6        firstName: "John"
7        lastName: "Smith"
8        address1: "1234 Fake Street"
9        address2: ""
10        city: "Austin"
11        company: "BC"
12        countryCode: "US"
13        stateOrProvince: "TX"
14        phone: "123-456-7890"
15        postalCode: "78610"
16        formFields: {
17          checkboxes: [{ fieldEntityId: 1, fieldValueEntityIds: [1, 2, 3] }]
18          multipleChoices: [{ fieldEntityId: 1, fieldValueEntityId: 2 }]
19          numbers: [{ fieldEntityId: 1, number: 1.0 }]
20          texts: [{ fieldEntityId: 1, text: "Customer notes" }]
21          passwords: [{ fieldEntityId: 1, password: "SecurePassword123!" }]
22        }
23      }
24    ) {
25      errors {
26        __typename
27        ... on ValidationError {
28          message
29        }
30        ... on CustomerNotLoggedInError {
31          message
32        }
33        ... on CustomerAddressCreationError {
34          message
35        }
36      }
37    }
38  }
39}

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
1mutation {
2  customer {
3    updateCustomerAddress(
4    reCaptchaV2: { token: "" },
5    input: {
6        addressEntityId: 1,
7        data: {
8        firstName: "John",
9        lastName: "Smith",
10        address1: "123 Main Street",
11        address2: "Suite 200",
12        city: "Austin",
13        company: "Acme Corporation",
14        countryCode: "US",
15        stateOrProvince: "TX",
16        phone: "555-123-4567",
17        postalCode: "78701",
18        formFields: {
19            checkboxes: [
20            {
21                fieldEntityId: 1,
22                fieldValueEntityIds: [1,2,3]
23            }
24            ],
25            multipleChoices: [
26            {
27                fieldEntityId: 1,
28                fieldValueEntityId: 2
29            }
30            ],
31            numbers: [
32            {
33                fieldEntityId: 1,
34                number: 1.0
35            }
36            ],
37            texts: [
38            {
39                fieldEntityId: 1,
40                text: "Customer notes"
41            }
42            ],
43            passwords: [
44            {
45                fieldEntityId: 1,
46                password: "SecurePassword123!"
47            }
48            ],
49        }
50        }
51    }
52    ) {
53    errors {
54        __typename
55        ... on ValidationError {
56        message
57        }
58        ... on CustomerNotLoggedInError {
59        message
60        }
61        ... on AddressDoesNotExistError {
62        message
63        }
64        ... on CustomerAddressUpdateError {
65        message
66        }
67      }
68    }
69  }
70}

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
1mutation {
2  customer {
3    deleteCustomerAddress(
4      reCaptchaV2: { token: "" }
5      input: { addressEntityId: 1 }
6    ) {
7      errors {
8        __typename
9        ... on CustomerNotLoggedInError {
10          message
11        }
12        ... on CustomerAddressDeletionError {
13          message
14        }
15      }
16    }
17  }
18}

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
1mutation {
2  customer {
3    changePassword(
4      input: { currentPassword: "Password1!", newPassword: "Password2!" }
5    ) {
6      errors {
7        ... on ValidationError {
8          path
9          message
10        }
11        ... on CustomerPasswordError {
12          message
13        }
14        ... on CustomerDoesNotExistError {
15          message
16        }
17        ... on CustomerNotLoggedInError {
18          message
19        }
20      }
21    }
22  }
23}

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
1mutation {
2  customer {
3    requestResetPassword(
4      reCaptchaV2: { token: "" }
5      input: { email: "john@test.com" }
6    ) {
7      errors {
8        ... on ValidationError {
9          message
10        }
11      }
12    }
13  }
14}

Reset a password

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

Example mutation: Reset a password
1mutation {
2  customer {
3    resetPassword(
4      input: {
5        customerEntityId: 1 # Provided in the link contained in the reset password email
6        token: "" # Provided in the link contained in the reset password email
7        newPassword: "NewPassword1234"
8      }
9    ) {
10      errors {
11        ... on ValidationError {
12          message
13        }
14        ... on ChangePasswordError {
15          message
16        }
17      }
18    }
19  }
20}

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
1query {
2    customer {
3      firstName
4      lastName
5      formFields {
6          entityId
7          name
8      }
9      addresses {
10          collectionInfo {
11              totalItems
12          }
13          edges {
14              node {
15                  entityId
16                  firstName
17                  lastName
18                  address1
19                  city
20                  stateOrProvince
21                  postalCode
22                  formFields {
23                      entityId
24                      name
25                  }
26              }
27          }
28      }
29    }
30}

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