AtlasGo to Atlas↗️

No results

Help CenterCustom DataCustom Events: Best Practices

Custom Events: Best Practices

Last updated September 18, 2023


Custom events are used to track important customer behaviors and system events throughout your app. In Atlas, they can be used in three places:

  1. the customer timeline
  2. session recordings
  3. as search or trigger criteria in finder, chatbots, and automations

In this article, we'll review best practices for:

  • when to use client vs server API calls
  • when to use each event type
  • how to name custom events
  • common events for different business models

When to use client vs server API calls

Sending events via the client typically provides more context, while sending events via the server is typically more reliable.

Use client-side API calls when:

  • information isn't stored in your database (eg, page views, button clicks, page scroll length, etc.)
  • it's easier to send information from the client (eg, UTM tag, device, user agent, etc.)

When to use each event type

There are six different event types you can call with Atlas: identify, track, page, screen, group, and alias. Each one answers a different question about a customer:

  • identify: who is this customer?
  • call this at account creation, account updated, user login, and when a user accesses any login gated pages
  • track: what are they doing?
  • page / screen: which page (web) / screen (app) are they on?
  • call this when a customer navigates to a new page or screen in your app
  • group: which account do they belong to?
  • call this when a customer is assigned to a new account
  • alias: do they have a past id?

How to name custom events

Use the "Object-Action" naming convention for events when possible. For instance, "Account Created," "Customer Signed Up," and "Product Searched."

When naming properties, use snake case (eg, property_name).

Common events for different business models

Two common business models we encounter are ecommerce and B2B SaaS. Here are some common events for each type of business:


  • Browsing: Products Searched, Product List Viewed, Product List Filtered
  • Promotions: Promotion Viewed, Promotion Clicked
  • Core Ordering: Product Clicked, Product Viewed, Product Added, Product Removed, Cart Viewed, Checkout Started, Checkout Step Viewed, Checkout Step Completed, Payment Info Entered, Order Completed, Order Updated, Order Refunded, Order Cancelled
  • Coupons: Coupon Entered, Coupon Applied, Coupon Denied, Coupon Removed
  • Wishlisting: Product Added to Wishlist, Product Removed from Wishlist, WIshlist Product Added to Cart
  • Sharing: Product Shared, Cart Shared
  • Reviewing: Product Reviewed

B2B SaaS

  • Account Created, Account Deleted, Signed Up, Signed In, Signed Out, Invite Sent, Account Added User, Account Removed User, Trial Started, Trial Ended


" Collecting Data on the Client or Server ," Segment

" Spec Overview ," Segment

" Best Practices for Event Calls ," Segment

Was this article helpful?