Shopper Identity & Auth

Elective Commerce acts as a secure identity provider for your storefront. This guide covers the complete shopper lifecycle: from registration and email verification to session persistence and account recovery.

The Identity Lifecycle

1 Register the customer which triggers a verification email sent to the customer for verification.
2 Confirm the shopper's email via a stateless JWT handshake.
3 Use the X-Customer-Token to manage sessions.

01. Onboarding & Registration

Creating a shopper account requires basic profile information and a verificationUrl. This URL should point to a dedicated page on your storefront where you will handle the token verification.

POST /v1/auth/register

JSON BODY

email (string)Required. Must be unique within your store. Sanitized to lowercase.
password (string)Required. Minimum 8 characters. Capped at 42 characters.
firstName / lastName (string)Required. Used for order fulfillment and email personalization.
verificationUrl (url)Required. The base URL for the verification link sent via email.

Implementation

const register = async (form) => {
  const res = await fetch('https://api.electivecommerce.com/v1/auth/register', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer pk_live_...' },
    body: JSON.stringify({
      email: form.email,
      password: form.password,
      firstName: form.firstName,
      lastName: form.lastName,
      verificationUrl: window.location.origin + '/verify-email'
    })
  });
  return await res.json();
};

02. Email Verification

Elective Commerce sends a signed JWT to the shopper's email. Extract the token from the URL query parameters on your success page and POST it to the verification endpoint.

POST /v1/auth/verify-email

JSON BODY

token (string)Required. The signed JWT token received in the verification email.
email (string)Optional. If provided, we verify it matches the identity inside the token.

Implementation

const verifyEmail = async (token) => {
  const res = await fetch('https://api.electivecommerce.com/v1/auth/verify-email', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer pk_live_...' },
    body: JSON.stringify({ token })
  });
  return await res.json();
};

03. Login & Reconciliation

Exchanges credentials for a Customer Session Token. If an anonymous cartId is provided, the items will be reconciled into the shopper's persistent record.

POST /v1/auth/login

JSON BODY

email / password (string)Required shopper credentials.
cartId (uuid)Optional. The ID of the current anonymous shopping cart to be claimed.

Implementation

const login = async (email, password) => {
  const res = await fetch('https://api.electivecommerce.com/v1/auth/login', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer pk_live_...' },
    body: JSON.stringify({
      email,
      password,
      cartId: localStorage.getItem('active_cart_id') // Link anonymous cart
    })
  });
  const data = await res.json();
  if (data.success) {
    localStorage.setItem('shopper_token', data.token);
    localStorage.setItem('active_cart_id', data.customer.cart_id);
  }
};

04. Profile & Sessions

Use these endpoints to maintain the session state and fetch the authoritative cart ID after a page reload.

GET /v1/auth/me

HEADERS

X-Customer-TokenRequired. The JWT session token obtained during login/register.
AuthorizationRequired. Your Store's Public API Key (Bearer pk_live_...).

Implementation

const getProfile = async () => {
  const res = await fetch('https://api.electivecommerce.com/v1/auth/me', {
    headers: {
      'Authorization': 'Bearer pk_live_...',
      'X-Customer-Token': localStorage.getItem('shopper_token')
    }
  });
  return await res.json();
};

05. Password Recovery Request

Initiates the recovery flow. Elective Commerce will verify the account exists and send a stateless recovery token to the shopper's email.

POST /v1/auth/forgot-password

JSON BODY

email (string)Required. The account email address.
verificationUrl (url)Required. The storefront page to handle the reset token.

Implementation

const forgotPassword = async (email) => {
  const res = await fetch('https://api.electivecommerce.com/v1/auth/forgot-password', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer pk_live_...' },
    body: JSON.stringify({
      email,
      verificationUrl: window.location.origin + '/reset-password'
    })
  });
  return await res.json();
};

06. Finalizing Reset

Completes the recovery flow. The token is valid for 1 hour and can only be used once.

POST /v1/auth/reset-password

JSON BODY

token (string)Required. The JWT token from the reset email.
newPassword (string)Required. Minimum 8 characters.

Implementation

const resetPassword = async (token, newPassword) => {
  const res = await fetch('https://api.electivecommerce.com/v1/auth/reset-password', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer pk_live_...' },
    body: JSON.stringify({ token, newPassword })
  });
  return await res.json();
};

07. Session Termination

Invalidates the shopper's active session on the server. Always call this endpoint during logout to ensure stateful security.

POST /v1/auth/logout

HEADERS

X-Customer-TokenRequired. The session token to be destroyed.

Implementation

const logout = async () => {
  await fetch('https://api.electivecommerce.com/v1/auth/logout', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer pk_live_...',
      'X-Customer-Token': localStorage.getItem('shopper_token')
    }
  });
  localStorage.removeItem('shopper_token');
  window.location.href = '/login';
};