> ## Documentation Index
> Fetch the complete documentation index at: https://www.commercengine.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify a forgotten account's sign-in code

> Verifies the one-time password `POST /auth/forgot-username` sent and signs the shopper in, as `POST /auth/verify-otp` does for a login: it returns the `User` with `access_token` and `refresh_token`, and the session's visitor data (cart, attribute values) moves to the account. When the customer has several active users (a business account), a call without `user_id` returns them in `users` instead, without signing in; call again with the same `otp` and `otp_token` and the chosen user's `id` as `user_id`. A wrong code, an expired one, the 5th wrong try (which uses the code up), and the token of a lookup that matched no account all get the same 400 (`invalid-otp`); after one, request a new code. Requires the access token the code was requested with.



## OpenAPI

````yaml https://openapi.commercengine.io/ce-storefront.json post /auth/forgot-username/verify-otp
openapi: 3.2.0
info:
  version: '1.0'
  title: CE Storefront APIs
  summary: Customer-facing e-commerce API for building exceptional shopping experiences
  description: >-
    Public-facing API for Commerce Engine storefronts, enabling seamless
    shopping experiences with product browsing, cart management, checkout
    processing, user accounts, and order tracking. Perfect for building web,
    mobile, and headless commerce applications.
  contact:
    name: Support
    email: support@commercengine.io
    url: https://www.commercengine.io/contact-us
  license:
    url: https://www.commercengine.io/contact-us
    name: All Rights Reserved
servers:
  - url: https://staging.api.commercengine.io/api/v1/{store_id}/storefront
    description: Staging Server
    variables:
      store_id:
        description: Store ID
        default: store_id
    x-speakeasy-server-id: staging
  - url: https://prod.api.commercengine.io/api/v1/{store_id}/storefront
    description: Prod Server
    variables:
      store_id:
        description: Store ID
        default: store_id
    x-speakeasy-server-id: prod
security: []
tags:
  - name: section-identity
    summary: Identity
    kind: nav
  - name: Authentication
    description: >-
      Start an anonymous session for each visitor, then sign them in or register
      them with a one-time password over SMS, WhatsApp or email, or with a
      password. Every flow ends in the access and refresh tokens your app sends
      with each request.
    summary: Authentication
    kind: nav
    parent: section-identity
  - name: Account recovery
    description: >-
      Get a shopper back into their account: reset a forgotten password, or find
      the account by its KYC document numbers and sign in with the one-time code
      sent to it.
    summary: Account recovery
    kind: nav
    parent: section-identity
  - name: Users
    description: >-
      The signed-in shopper's `User`: read and update the profile, manage the
      profile image, change the password, check whether the email and phone are
      verified, and deactivate or delete the account.
    summary: Users
    kind: nav
    parent: section-identity
  - name: Customer attributes
    description: >-
      The store's customer attributes (`StorefrontAttribute`) and the shopper's
      values for them (`UserAttributeValue`), for building profile forms.
    summary: Customer attributes
    kind: nav
    parent: section-identity
  - name: section-customers
    summary: Customers
    kind: nav
  - name: Addresses
    description: >-
      The customer's saved addresses, as `CustomerAddress` objects, to offer at
      checkout and manage on the account page.
    summary: Addresses
    kind: nav
    parent: section-customers
  - name: Bank accounts
    description: >-
      The customer's bank accounts, as `CustomerBankAccount` objects: add,
      update, verify and remove them.
    summary: Bank accounts
    kind: nav
    parent: section-customers
  - name: KYC documents
    description: >-
      The KYC documents the store requires (`KycDocumentConfig`) and the ones
      the customer has added (`Document`). Verify a document number before
      saving it.
    summary: KYC documents
    kind: nav
    parent: section-customers
  - name: Saved payment methods
    description: >-
      The cards, UPI IDs and wallets the customer has saved, to offer at
      checkout.
    summary: Saved payment methods
    kind: nav
    parent: section-customers
  - name: Mandates
    description: >-
      Recurring-payment mandates the customer authorizes (`CustomerMandate`):
      create, update, pause, resume or revoke them, and list the debits
      scheduled against them (`MandateDebitSchedule`).
    summary: Mandates
    kind: nav
    parent: section-customers
  - name: Loyalty
    description: >-
      The store's `LoyaltyProgram` and the customer's standing in it: their
      `CustomerLoyalty` and `LoyaltyPointActivity`. Redeem points on a cart
      under Carts.
    summary: Loyalty
    kind: nav
    parent: section-customers
  - name: Credit
    description: >-
      What the customer can spend on credit: their bank-transfer
      `CustomerCreditBalance` and their credit line
      (`CustomerCreditLineBalance`). Apply the credit balance to a cart under
      Carts.
    summary: Credit
    kind: nav
    parent: section-customers
  - name: section-catalog
    summary: Catalog
    kind: nav
  - name: Products
    description: >-
      Browse and search the store's catalog: list `Product`s and SKUs, read a
      product and its variants, and show similar, up-sell and cross-sell items.
    summary: Products
    kind: nav
    parent: section-catalog
  - name: Categories
    description: >-
      The store's categories, as `ProductCategory` objects with their child
      categories, for navigation and filtering.
    summary: Categories
    kind: nav
    parent: section-catalog
  - name: Reviews
    description: >-
      Reviews of products and sellers: show them, let a shopper review a
      product, and list what the customer has reviewed or can review next.
    summary: Reviews
    kind: nav
    parent: section-catalog
  - name: Marketplace catalog
    description: >-
      A marketplace's catalog as shoppers browse it: `MarketplaceProduct`s with
      their seller, variants, SKUs, categories and reviews, plus search and
      recommendations.
    summary: Marketplace catalog
    kind: nav
    parent: section-catalog
  - name: section-shopping
    summary: Shopping
    kind: nav
  - name: Carts
    description: >-
      The shopper's `Cart`: create it, add, update or remove items, set the
      address, and apply loyalty points or credit balance. Each update returns
      the full, updated `Cart`.
    summary: Carts
    kind: nav
    parent: section-shopping
  - name: Coupons & promotions
    description: >-
      The coupons and promotions a shopper can use: list what the store offers,
      see which apply to a cart and why the rest don't, and apply or remove a
      coupon.
    summary: Coupons & promotions
    kind: nav
    parent: section-shopping
  - name: Fulfillment
    description: >-
      How an order reaches the shopper: check that a pincode is serviceable,
      list the delivery and collect-in-store options for a cart, and save the
      cart's choice.
    summary: Fulfillment
    kind: nav
    parent: section-shopping
  - name: Wishlist
    description: Products the shopper saved for later, as `Item` objects.
    summary: Wishlist
    kind: nav
    parent: section-shopping
  - name: section-orders
    summary: Orders
    kind: nav
  - name: Orders
    description: >-
      Place an order from the cart and follow it afterwards: list orders, read
      an `OrderDetail`, cancel it, list its shipments, and offer past items
      again.
    summary: Orders
    kind: nav
    parent: section-orders
  - name: Order payments
    description: >-
      Pay for an order after checkout: poll its payment status, retry or cancel
      a payment request, and list its `OrderPayment`s and refunds.
    summary: Order payments
    kind: nav
    parent: section-orders
  - name: Returns
    description: >-
      Return delivered items: create an `OrderReturn`, add attachments, follow
      it, and cancel it.
    summary: Returns
    kind: nav
    parent: section-orders
  - name: section-payments
    summary: Payments
    kind: nav
  - name: Payments
    description: >-
      The payment methods the store accepts and the checks around paying with
      them: card BIN details, VPA and IFSC lookups, and authenticating a payment
      with a direct OTP.
    summary: Payments
    kind: nav
    parent: section-payments
  - name: PayU
    description: >-
      Generate the hash PayU requires on the requests your app sends it, such as
      validating a UPI ID or saving and retrieving cards.
    summary: PayU
    kind: nav
    parent: section-payments
  - name: section-store
    summary: Store
    kind: nav
  - name: Store
    description: >-
      The store your app runs on: check that it exists and read its
      `StoreConfig`, from brand and currency to KYC, customer groups and payment
      providers.
    summary: Store
    kind: nav
    parent: section-store
  - name: Sellers
    description: >-
      A marketplace's sellers: a seller's profile (`SellerDetail`) and the
      sellers authorized for a customer (`SellerInfo`).
    summary: Sellers
    kind: nav
    parent: section-store
  - name: Locations
    description: Countries, states and pincodes for address forms.
    summary: Locations
    kind: nav
    parent: section-store
  - name: Newsletter
    description: Sign a shopper up for the store's newsletter.
    summary: Newsletter
    kind: nav
    parent: section-store
externalDocs:
  url: https://llm-docs.commercengine.io
  description: Commerce Engine API Reference Documentation
paths:
  /auth/forgot-username/verify-otp:
    post:
      tags:
        - Account recovery
      summary: Verify a forgotten account's sign-in code
      description: >-
        Verifies the one-time password `POST /auth/forgot-username` sent and
        signs the shopper in, as `POST /auth/verify-otp` does for a login: it
        returns the `User` with `access_token` and `refresh_token`, and the
        session's visitor data (cart, attribute values) moves to the account.
        When the customer has several active users (a business account), a call
        without `user_id` returns them in `users` instead, without signing in;
        call again with the same `otp` and `otp_token` and the chosen user's
        `id` as `user_id`. A wrong code, an expired one, the 5th wrong try
        (which uses the code up), and the token of a lookup that matched no
        account all get the same 400 (`invalid-otp`); after one, request a new
        code. Requires the access token the code was requested with.
      operationId: verify-forgot-username-otp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - otp
                - otp_token
              properties:
                otp:
                  description: The code the shopper received.
                  type: string
                otp_token:
                  description: The `otp_token` of `POST /auth/forgot-username`.
                  type: string
                user_id:
                  description: >-
                    The user to sign in as, from `users`. Needed only when the
                    business has several active users.
                  type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                  - success
                  - content
                properties:
                  message:
                    type: string
                  success:
                    type: boolean
                  content:
                    description: >-
                      Signed in: the `User` and its tokens. Several users to
                      choose from: `users`.
                    oneOf:
                      - title: Signed in
                        type: object
                        properties:
                          user:
                            $ref: '#/components/schemas/User'
                          access_token:
                            type: string
                          refresh_token:
                            type: string
                        required:
                          - user
                          - access_token
                          - refresh_token
                      - title: Choose a user
                        type: object
                        properties:
                          users:
                            description: >-
                              The business's active users, primary first. The
                              code stays valid until it signs one in.
                            type: array
                            items:
                              $ref: '#/components/schemas/ForgotUsernameUser'
                        required:
                          - users
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - Authorization: []
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/operations/verify-forgot-username-otp
        description: API reference for the verify-forgot-username-otp operation
components:
  schemas:
    User:
      title: User
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/User
        description: API reference for the User schema
      required:
        - id
        - first_name
        - last_name
        - email
        - is_email_verified
        - phone
        - country_code
        - is_phone_verified
        - profile_image_url
        - is_anonymous
        - is_logged_in
        - login_methods
        - notification_preferences
      properties:
        id:
          description: The unique ID of the user.
          type: string
          readOnly: true
        first_name:
          description: User’s first name.
          type:
            - string
            - 'null'
        last_name:
          description: User’s last name.
          type:
            - string
            - 'null'
        email:
          description: User’s email I’d.
          type:
            - string
            - 'null'
          format: email
        is_email_verified:
          description: Boolean indicating whether the email is verified.
          type: boolean
          readOnly: true
        phone:
          description: Phone number saved on the user account, or null when absent.
          type:
            - string
            - 'null'
        country_code:
          anyOf:
            - $ref: '#/components/schemas/CountryCode'
            - type: 'null'
        is_phone_verified:
          description: Boolean indicating whether the phone is verified.
          type: boolean
          readOnly: true
        profile_image_url:
          description: URL to the user's profile image.
          type:
            - string
            - 'null'
          readOnly: true
        is_anonymous:
          description: Indicates whether the user is anonymous.
          type: boolean
          readOnly: true
        is_logged_in:
          description: Indicates whether the user is currently logged in.
          type: boolean
          readOnly: true
        login_methods:
          type: array
          items:
            type: string
            enum:
              - email
              - phone
              - whatsapp
              - password
        notification_preferences:
          $ref: '#/components/schemas/NotificationPreferences'
          description: >-
            User's notification preferences are categorized by transactional,
            promotional, and newsletter types.
        customer_group_id:
          description: User's customer group ID.
          type:
            - string
            - 'null'
          writeOnly: true
        customer_id:
          description: >-
            The unique ID of the customer. Can be used to identify the customer
            in the system. It can be different from the user ID if there are
            multiple users created for the same customer.
          type: string
          readOnly: true
        customer_group:
          description: User's customer group.
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/CustomerGroup'
          readOnly: true
        business:
          description: User's business information.
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/Business'
        metadata:
          description: >-
            The customer's own data as key-value pairs, shared by all its users.
            In an update, each key sent is set, a key sent as `null` is removed,
            and keys not sent are kept; `null` or `{}` changes nothing. At most
            50 keys and 16 KB as JSON.
          type:
            - object
            - 'null'
          additionalProperties: true
        attributes:
          description: >-
            Customer attribute values to set, as `PUT
            /auth/user/{id}/attributes` sets them, in the same change. Read them
            with `GET /auth/user/{id}/attributes`.
          type: array
          items:
            $ref: '#/components/schemas/UserAttributeInput'
          maxItems: 50
          writeOnly: true
        is_primary:
          description: Whether this user is the primary user for its customer.
          type: boolean
          readOnly: true
        kyc_status:
          description: >-
            KYC status of the customer. Only present on the user-detail/update
            response; `null` when not applicable.
          type:
            - string
            - 'null'
          readOnly: true
        created_at:
          description: Timestamps indicate when the user's account was created.
          type: string
          format: date-time
          readOnly: true
        modified_at:
          description: Timestamps indicating when the user account was last modified.
          type: string
          format: date-time
          readOnly: true
    ForgotUsernameUser:
      title: ForgotUsernameUser
      description: >-
        A user of the recovered account's business, as much as it takes to
        choose one: the name and the masked contact.
      type: object
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/schemas/ForgotUsernameUser
        description: API reference for the ForgotUsernameUser schema
      required:
        - id
        - first_name
        - last_name
        - email
        - phone
      properties:
        id:
          description: Pass as `user_id` to sign in as this user.
          type: string
        first_name:
          type:
            - string
            - 'null'
        last_name:
          type:
            - string
            - 'null'
        email:
          description: 'Masked: its first three characters and its domain.'
          type:
            - string
            - 'null'
        phone:
          description: 'Masked: its last four digits.'
          type:
            - string
            - 'null'
    CountryCode:
      type: string
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/CountryCode
        description: API reference for the CountryCode schema
      default: '+91'
      pattern: ^\+?\d{1,4}$
    NotificationPreferences:
      title: NotificationPreferences
      description: 'Set channel preferences for each type of '
      type: object
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/schemas/NotificationPreferences
        description: API reference for the NotificationPreferences schema
      required:
        - transactional
        - promotional
        - newsletter
      properties:
        transactional:
          $ref: '#/components/schemas/NotificationChannelPreferences'
          description: >-
            These notifications are typically critical for user engagement,
            providing updates, confirmations, or alerts related to their account
            activities.
        promotional:
          $ref: '#/components/schemas/NotificationChannelPreferences'
          description: >-
            These notifications aim to engage users with promotional content and
            enhance their overall experience with the platform.
        newsletter:
          $ref: '#/components/schemas/NotificationChannelPreferences'
          description: >
            These notifications are often sent periodically as part of a
            subscription service.
    CustomerGroup:
      title: CustomerGroup
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/CustomerGroup
        description: API reference for the CustomerGroup schema
      required:
        - id
        - name
        - description
        - is_default
        - active
      properties:
        id:
          type: string
          readOnly: true
        name:
          type: string
        description:
          type:
            - string
            - 'null'
        is_default:
          description: first record will be treated as default if not changed.
          type: boolean
        active:
          type: boolean
          default: true
    Business:
      title: Business
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/Business
        description: API reference for the Business schema
      required:
        - type
        - name
      properties:
        type:
          type:
            - string
            - 'null'
        name:
          type:
            - string
            - 'null'
        registered_address:
          anyOf:
            - $ref: '#/components/schemas/BusinessAddress'
            - type: 'null'
        metadata:
          description: Alias of the customer metadata.
          type:
            - object
            - 'null'
          additionalProperties: true
    UserAttributeInput:
      title: UserAttributeInput
      description: >-
        A value to set for one attribute, named by its `attribute_id` or its
        `slug` (one of the two). Shoppers can set visible, active `custom`
        attributes that aren't `is_readonly`.
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/schemas/UserAttributeInput
        description: API reference for the UserAttributeInput schema
      oneOf:
        - title: By id
          type: object
          properties:
            attribute_id:
              description: The attribute's `id`.
              type: string
            value:
              description: >-
                The value, of the attribute's `attribute_type`, at most 4 KB as
                JSON. `null`, an empty string or only spaces removes it. `[]`
                and `{}` are values.
              anyOf:
                - type: string
                - type: number
                - type: boolean
                - type: array
                - type: object
                  additionalProperties: true
                - type: 'null'
          required:
            - attribute_id
            - value
        - title: By slug
          type: object
          properties:
            slug:
              description: The attribute's `slug`.
              type: string
            value:
              description: >-
                The value, of the attribute's `attribute_type`, at most 4 KB as
                JSON. `null`, an empty string or only spaces removes it. `[]`
                and `{}` are values.
              anyOf:
                - type: string
                - type: number
                - type: boolean
                - type: array
                - type: object
                  additionalProperties: true
                - type: 'null'
          required:
            - slug
            - value
    NotificationChannelPreferences:
      title: NotificationChannelPreferences
      description: Set specific channel preferences
      type: object
      externalDocs:
        url: >-
          https://llm-docs.commercengine.io/storefront/schemas/NotificationChannelPreferences
        description: API reference for the NotificationChannelPreferences schema
      required:
        - email
        - sms
        - whatsapp
      properties:
        email:
          description: >-
            Indicates whether the user has opted to receive notifications via
            email.
          type: boolean
        sms:
          description: >-
            Indicates whether the user has opted to receive notifications via
            SMS.
          type: boolean
        whatsapp:
          description: >-
            Indicates whether the user has opted to receive notifications via
            WhatsApp.
          type: boolean
    BusinessAddress:
      title: BusinessAddress
      type: object
      externalDocs:
        url: https://llm-docs.commercengine.io/storefront/schemas/BusinessAddress
        description: API reference for the BusinessAddress schema
      required:
        - first_name
        - last_name
        - country_code
        - phone
        - email
        - address_line1
        - address_line2
        - landmark
        - pincode
        - city
        - state
        - country
        - tax_identification_number
        - business_name
        - is_phone_verified
        - is_email_verified
      properties:
        id:
          type:
            - string
            - 'null'
          pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{26}$
          readOnly: true
        first_name:
          type: string
        last_name:
          type:
            - string
            - 'null'
        country_code:
          description: >-
            Two-letter code begin with a plus sign prefix that identifies
            different countries. By default it will be +91 if not provided.
          type: string
        phone:
          description: 10 digit phone number without country code.
          type: string
        email:
          type: string
        address_line1:
          type: string
        address_line2:
          type:
            - string
            - 'null'
        landmark:
          type:
            - string
            - 'null'
        pincode:
          type: string
        city:
          type: string
        state:
          type: string
        country:
          type: string
        tax_identification_number:
          description: Tax Identification Number specific to the country of operation.
          type:
            - string
            - 'null'
          examples: []
        business_name:
          description: Use in billing & shipping details only.
          type:
            - string
            - 'null'
        is_default_billing:
          description: >-
            Indicates if the address is the default billing address for the
            customer.
          type: boolean
        is_default_shipping:
          description: >-
            Indicates if the address is the default shipping address for the
            customer.
          type: boolean
        is_phone_verified:
          type: boolean
          readOnly: true
        is_email_verified:
          type: boolean
          readOnly: true
        nickname:
          description: Nickname for the address.
          type:
            - string
            - 'null'
          default: null
      examples: []
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            type: object
            required:
              - message
              - success
              - code
            properties:
              message:
                type: string
                x-speakeasy-error-message: true
              success:
                type: boolean
              code:
                type: string
              errors:
                type: object
              details:
                type: string
    Unauthorized:
      description: >-
        Authentication failed. Codes include `token-required`, `token-expired`
        and `token_not_valid` for an invalid or expired token.
      content:
        application/json:
          schema:
            type: object
            required:
              - message
              - success
              - code
            properties:
              message:
                type: string
                examples:
                  - Not authorized for given operation on the Resource.
                x-speakeasy-error-message: true
              success:
                type: boolean
                default: false
              code:
                type: string
                examples:
                  - unauthorized
              details:
                type: string
    Forbidden:
      description: >-
        Access denied. `token-required` requires an authenticated session;
        `permission-denied` means the caller cannot access this resource. On
        POS, `session-expired` requires signing in again.
      content:
        application/json:
          schema:
            type: object
            required:
              - code
              - message
              - success
            properties:
              code:
                type: string
              message:
                type: string
                x-speakeasy-error-message: true
              success:
                type: boolean
              details:
                type: string
    InternalServerError:
      description: The request failed because of an unexpected error.
      content:
        application/json:
          schema:
            type: object
            required:
              - code
              - message
              - success
            properties:
              code:
                type: string
              message:
                type: string
                x-speakeasy-error-message: true
              success:
                type: boolean
              details:
                type: string
  securitySchemes:
    Authorization:
      type: http
      description: Access token
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.