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
  • Get a customer’s stored payment instruments

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}

Get a customer’s stored payment instruments

Use the storedPaymentInstruments field on the Customer type to list the payment instruments a customer has saved, such as cards, PayPal accounts, and bank accounts.

This field requires a valid customer JWT. Use a customer impersonation token, or a token retrieved while a customer is logged in to the storefront. For unauthenticated requests, the parent customer query resolves to null, so no instruments are returned.

The connection returns one StoredPaymentInstrument per edge. Each instrument’s details field is a StoredPaymentInstrumentDetails union — use inline fragments (... on StoredCard, ... on StoredPaypalAccount, ... on StoredBankAccount) to select the type-specific fields. The connection also exposes defaultStoredPaymentInstrumentToken, the token of the customer’s default instrument when one is set.

The connection follows the Relay cursor connection spec. Page through results with the first/after (forward) or last/before (backward) arguments, and read pageInfo to determine whether more pages are available and which cursors to request next. Each edge’s cursor is the value to pass to after (or before) to continue paging from that instrument.

To narrow the result set to specific payment methods, pass the filters argument with one or more paymentMethodIds (for example, ["braintree.credit_card", "braintree.paypal"]). An empty or omitted list returns all instruments.

The example below requests the first 10 instruments after a given cursor, filtered to cards and PayPal accounts, and selects the full set of fields available on each instrument type.

Example query: Get a customer's stored payment instruments
1query {
2  customer {
3    storedPaymentInstruments(
4      first: 10
5      after: "eyJ0b2tlbiI6ImExYjJjM2Q0ZTUifQ=="
6      filters: { paymentMethodIds: ["braintree.credit_card", "braintree.paypal"] }
7    ) {
8      defaultStoredPaymentInstrumentToken
9      pageInfo {
10        hasNextPage
11        hasPreviousPage
12        startCursor
13        endCursor
14      }
15      edges {
16        cursor
17        node {
18          token
19          paymentMethodId
20          details {
21            __typename
22            ... on StoredCard {
23              brand
24              last4
25              issuerIdentificationNumber
26              expires {
27                month
28                year
29              }
30              billingAddress {
31                firstName
32                lastName
33                email
34                company
35                address1
36                address2
37                city
38                stateOrProvince
39                stateOrProvinceCode
40                postalCode
41                countryCode
42                phone
43              }
44            }
45            ... on StoredPaypalAccount {
46              email
47            }
48            ... on StoredBankAccount {
49              maskedAccountNumber
50              issuer
51            }
52          }
53        }
54      }
55    }
56  }
57}

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