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
  • Update a customer’s stored payment instrument
  • Delete a customer’s stored payment instrument

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}

Update a customer’s stored payment instrument

Use the updateStoredPaymentInstrument mutation on the customer mutation type to update the billing address and/or promote a stored payment instrument to be the customer’s default. Instrument data itself, such as the card number, expiry, or brand, is immutable and cannot be changed through this mutation.

This field requires a valid customer JWT, the same as storedPaymentInstruments. Use a customer impersonation token, or a token retrieved while a customer is logged in to the storefront.

Both this mutation and deleteStoredPaymentInstrument act on an existing instrument’s token. Get an instrument’s token from the storedPaymentInstruments query before calling either mutation.

setAsDefault is promote-only: pass true to make this instrument the customer’s default. Omitting the field or passing false leaves the current default unchanged — there is no way to unset a default without promoting a different instrument in its place.

Billing address updates are supported only for card instruments whose payment method allows editing. Passing billingAddress for any other instrument returns an error.

On billingAddress, firstName, address1, city, and countryCode are required. lastName, email, company, address2, stateOrProvince, stateOrProvinceCode, postalCode, and phone are optional.

The result’s defaultStoredPaymentInstrumentToken is populated only when the request sets setAsDefault: true, in which case it echoes the token of the instrument just promoted. Billing-only updates, and requests where setAsDefault is omitted or false, return null for this field — even if the customer already has a different default instrument set.

Example mutation: Update a customer's stored payment instrument
1mutation {
2  customer {
3    updateStoredPaymentInstrument(
4      input: {
5        token: "a1b2c3d4e5"
6        setAsDefault: true
7        billingAddress: {
8          firstName: "John"
9          lastName: "Smith"
10          address1: "123 Main Street"
11          city: "Austin"
12          countryCode: "US"
13        }
14      }
15    ) {
16      storedPaymentInstrument {
17        token
18        paymentMethodId
19        details {
20          __typename
21          ... on StoredCard {
22            brand
23            last4
24            billingAddress {
25              firstName
26              lastName
27              email
28              company
29              address1
30              address2
31              city
32              stateOrProvince
33              stateOrProvinceCode
34              postalCode
35              countryCode
36              phone
37            }
38          }
39        }
40      }
41      defaultStoredPaymentInstrumentToken
42      errors {
43        __typename
44        message
45      }
46    }
47  }
48}

Delete a customer’s stored payment instrument

Use the deleteStoredPaymentInstrument mutation on the customer mutation type to delete a stored payment instrument. Deleting an instrument removes it from BigCommerce and unvaults the associated token at the payment provider.

This field requires a valid customer JWT, the same as storedPaymentInstruments. Use a customer impersonation token, or a token retrieved while a customer is logged in to the storefront.

Get the instrument’s token from the storedPaymentInstruments query before calling this mutation.

The mutation result contains only an errors list — there is no data payload on success. An empty errors array indicates the instrument was deleted.

Deleting the customer’s current default instrument automatically promotes another remaining instrument to be the new default.

Example mutation: Delete a customer's stored payment instrument
1mutation {
2  customer {
3    deleteStoredPaymentInstrument(input: { token: "a1b2c3d4e5" }) {
4      errors {
5        __typename
6        message
7      }
8    }
9  }
10}

Error handling

updateStoredPaymentInstrument and deleteStoredPaymentInstrument can fail in two different ways. Expected, request-specific failures — an unsupported payment method or a token that doesn’t belong to the customer — are returned in the mutation’s own errors array, as shown in the examples above. Authentication failures and unmapped or transient upstream errors are returned as top-level GraphQL errors instead, with data.customer set to null. Check both places when handling responses.

A missing or expired customer JWT returns a top-level error:

Example: top-level GraphQL error (missing customer token)
1{
2  "data": {
3    "customer": null
4  },
5  "errors": [
6    {
7      "message": "A customer access token is required for this operation, but it was not provided.",
8      "path": ["customer"],
9      "locations": [{ "line": 1, "column": 9 }],
10      "extensions": {
11        "code": "MISSING_CUSTOMER_ACCESS_TOKEN"
12      }
13    }
14  ]
15}

Transient or unmapped upstream failures also surface as a top-level error, but without an extensions.code:

Example: top-level GraphQL error (unmapped or transient failure)
1{
2  "data": {
3    "customer": null
4  },
5  "errors": [
6    {
7      "message": "Internal server error"
8    }
9  ]
10}

Join our Developer community to share your feedback with us in the BigCommerceDevs Slack.

Resources

Documentation

API reference

Storefront tokens

REST management API: customers

Community