> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# 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`](/developer/docs/storefront/guides/graphql-storefront-api/customers) 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

| Action                                                                                                           | Effect on an outstanding reset link                                                                 |
| ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| The customer completes the reset through the link                                                                | The link stops working. The token is consumed on the first successful reset.                        |
| The customer requests another reset email                                                                        | Earlier links stop working. Only the newest link is valid, even if an earlier link has not expired. |
| The customer password changes in the control panel, through the Customers API, or in storefront account settings | The link stays valid until it expires or a new reset request replaces it.                           |

## 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:

**`Validate a reset token and set a new password`**

```graphql title="Validate a reset token and set a new password"
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.