Customer password reset

Customers who forget their password request a reset email, follow the link in that email, and set a new password. This page describes how reset links behave so you can handle expiry, invalidation, and error states consistently, whether you use a Stencil storefront or the GraphQL Storefront API.

Password reset flow

BigCommerce issues and checks the reset token. Your integration only has to send the customer to the right page or mutation at each step:

1. The customer requests a reset email with their email address.
2. BigCommerce sends an email with a link that contains the customer ID (c) and a reset token (t).
3. The customer opens the link and submits a new password. The token is checked when the page loads and again when the password is submitted.

On a Stencil storefront, the theme’s Forgot Password and Set New Password pages handle all three steps. Reset links point to /login.php?action=change_password with the c and t query parameters.

On a headless storefront, call the requestResetPassword mutation with the customer’s email address and set path to your own reset page. BigCommerce appends c and t to that path. Your page then calls resetPassword with customerEntityId set to c, token set to t, and the new password.

Requesting a reset email

Requesting a reset email does not reveal whether an account exists for the address. On a Stencil storefront, the shopper sees a confirmation message either way. With the GraphQL Storefront API, requestResetPassword returns an empty errors array and sends no email when no account matches the address.

Link lifetime

A reset link is valid for 12 hours from the time BigCommerce sends the email. After that, the token expires and the link is treated as invalid.

Link invalidation

Expired or invalid link behavior

Stencil storefront

The storefront checks the token when the Set New Password page loads. If the link is expired, already used, or superseded by a newer request, the page shows this message above the form:

The link you were given in the Request Password email is invalid. Please request another new password to receive a new link.

The form is still visible. If the shopper submits a new password, the storefront checks the token again and redirects to the Request New Password page with the same message. The message is translatable through the ForgotPasswordInvalidLink key in front_language.ini.

Because the check happens when the page loads, a Stencil storefront does not need a separate validation step.

GraphQL Storefront API

There is no public query that validates a reset token before you submit a new password. Send the resetPassword mutation and check its errors array:

mutation ResetPassword($customerEntityId: Int!, $token: String!, $newPassword: String!) {
  customer {
    resetPassword(
      input: { customerEntityId: $customerEntityId, token: $token, newPassword: $newPassword }
    ) {
      errors {
        __typename
        ... on ValidationError {
          message
        }
        ... on CustomerPasswordError {
          message
        }
      }
    }
  }
}

The mutation returns HTTP 200 even when it rejects the reset, so treat a non-empty errors array as a failure:

• Expired, invalid, or superseded token, or a customer ID that doesn’t match the token: a CustomerPasswordError with the message Invalid password reset token or customerEntityId.
• Password that doesn’t meet the store’s password requirements: a CustomerPasswordError with the message Invalid password.

To keep the experience close to a Stencil storefront, show the same invalid-link message on your reset page when the mutation returns an error, and offer a link to request a new email.