Skip to main content

Custom timeline entries

With Custom Timeline Entries you can log custom events in a customer's timeline that are specific to your product and systems using the Core API. This lets you have the full context when helping your customers.

Some example use cases for Custom Timeline Entries are:

  • Subscription changes
  • Account level changes such as email changes or password resets
  • Custom contact forms for getting in touch, bug reports, feature requests, etc.
  • Logging outages or errors, so you know when someone gets in touch if they were affected
  • Invoicing events
  • Order refunds or delivery events

Custom Timeline entries are built using the Plain UI Components and displayed in the customer's timeline.

Custom Timeline Entry examples


  • Custom Timeline Entry refers to an entry created in the customers timeline via the API.
  • Plain UI Component are used to build a Custom Timeline Entry.



This section provides a high-level overview of how Custom Timeline Entries can be created, for a technical walk through see the creating a custom timeline entry recipe.

The steps to create a custom timeline entry in a customer's timeline are:

  1. Upsert a customer in Plain (see customer upsert recipe).
  2. Build a request for the entry you want to add to the customer's timeline, using Plain UI Components.
  3. Make the request to the upsertCustomTimelineEntry API endpoint.

Diagram showing Custom Timeline Entry architecture


The Custom Timeline Entry Playground lets you build and preview the component JSON needed to create an entry. Use this to prototype an entry before starting to build your API integration.

Custom Timeline Entry Playground

Custom Timeline Entries vs. Customer Cards

Timeline Entries are used to add context to a customer's timeline. They should be used when you want to add data at a specific point in time. If you want to be able to always see certain key information about a customer (e.g. their pricing plan they are on) outside their timeline, then using Customer Cards is more appropriate.


Creating Customer Timeline Entries is a billable activity. If a Custom Timeline Entry is created for a customer, this customer will count towards your workspace's monthly active customer total.