Anonymous Sessions Use Cases

When a user authenticates in your application, anonymous sessions and Actions allow you to transfer anonymous session data, such as shopping cart contents, preferences, and browsing history, to their authenticated user profile. You can reference the event.anonymous_session object in Actions:

{
  user_id: string;     // anonymous user id 
  session_id: string;  // anonymous session token id
  created_at: number;  // anonymous session creation timestamp
  expires_at: number;  // anonymous session expiration timestamp
  metadata: {          // anonymous session metadata object
    [key: string]: string
  };
}

Anonymous sessions and Actions use cases

Save anonymous session metadata to a new user

You can use a pre-user-registration Action trigger to copy anonymous metadata into the new user profile when they sign up:

exports.onExecutePreUserRegistration = async (event, api) => {
  if (event.anonymous_session) {
    // Store reference to the anonymous session
    api.user.setAppMetadata(
      'linked_anonymous_id',
      event.anonymous_session.user_id
    );

    // Migrate cart data
    if (event.anonymous_session.metadata.cart) {
      api.user.setAppMetadata(
        'migrated_cart',
        event.anonymous_session.metadata.cart
      );
    }

    // Copy preferences to user metadata
    if (event.anonymous_session.metadata.preferences) {
      api.user.setUserMetadata(
        'preferences',
        event.anonymous_session.metadata.preferences
      );
    }
  }
};

Save anonymous session metadata to an existing user

You can use a post-login Action trigger to save anonymous metadata to existing users when they log in:

exports.onExecutePostLogin = async (event, api) => {
  if (event.anonymous_session) {
    // Store last anonymous session reference
    api.user.setAppMetadata(
      'last_anonymous_session',
      event.anonymous_session.user_id
    );

    // Add anonymous cart to access token for your API to process
    api.accessToken.setCustomClaim(
      'anonymous_cart',
      event.anonymous_session.metadata.cart
    );

    // Track all linked sessions (optional)
    const linkedSessions =
      event.user.app_metadata?.linked_sessions || [];
    if (!linkedSessions.includes(event.anonymous_session.user_id)) {
      api.user.setAppMetadata('linked_sessions', [
        ...linkedSessions,
        event.anonymous_session.user_id,
      ]);
    }
  }
};

Merge user metadata with anonymous metadata

You can use a post-login Action trigger to merge anonymous metadata to an existing user metadata, such as a cart information, when they log in:

exports.onExecutePostLogin = async (event, api) => {
  if (!event.anonymous_session?.metadata?.cart) {
    return; // No anonymous cart to merge
  }

  const anonymousCart = event.anonymous_session.metadata.cart;
  const existingCart = event.user.app_metadata?.cart || { items: [] };

  // Merge cart items, combining quantities for matching SKUs
  const mergedItems = [...existingCart.items];
  for (const anonItem of anonymousCart.items) {
    const existingIndex = mergedItems.findIndex(
      (item) => item.sku === anonItem.sku
    );
    if (existingIndex >= 0) {
      mergedItems[existingIndex].qty += anonItem.qty;
    } else {
      mergedItems.push(anonItem);
    }
  }

  api.user.setAppMetadata('cart', { items: mergedItems });
  api.accessToken.setCustomClaim('cart', { items: mergedItems });
};

Handle multiple anonymous sessions

You can use a post-login Action trigger to manage anonymous session metadata from different devices, when the user logs in:

exports.onExecutePostLogin = async (event, api) => {
  if (!event.anonymous_session) return;

  const linkedSessions =
    event.user.app_metadata?.linked_sessions || [];

  // Option 1: Keep all linked sessions
  api.user.setAppMetadata('linked_sessions', [
    ...linkedSessions,
    {
      user_id: event.anonymous_session.user_id,
      linked_at: new Date().toISOString(),
      device: event.request.user_agent,
    },
  ]);

  // Option 2: Keep only the most recent
  api.user.setAppMetadata('last_anonymous_session', {
    user_id: event.anonymous_session.user_id,
    metadata: event.anonymous_session.metadata,
  });
};

Learn more

Configure Anonymous Sessions

Learn how to configure anonymous sessions.

Configure Custom Claims for Anonymous Sessions

Learn how to map anonymous session metadata into access token claims.