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.
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.
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.
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.
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.
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.
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.
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.
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
- GraphQL Storefront API overview
- Guide to API accounts: Store-level API accounts
- Guide to API accounts: OAuth token creation scopes
- Authentication and example requests: BigCommerce-generated JWTs