Custom event best practices

Send and leverage Custom Events in OneSignal. This page shows how to shape event properties so every OneSignal feature can read them, and how one event can do several jobs at once. For sending and limits, see Custom events.

Prerequisites

A paid plan. Custom Events and custom Conversion Metrics are available on all paid plans.
Custom Events flowing into OneSignal from the SDK (OneSignal.User.trackEvent), the API, or an integration such as Segment or Amplitude. See Send Custom Events to OneSignal.

Make the most of your events and event properties

Use each Custom Event to trigger Journeys, build Segments, and measure conversions. The table shows where you set up each job and what the event needs.

Job	Where you set it up	What the event needs
Trigger a Journey	Journey entry rules, exit rules, and Wait Until steps	An event name. Add properties to filter Journey entry or personalize the messages.
Build a Segment	Audience > Segments, Custom Event filter	An event name, with storage turned on. Add properties to target a subset of the people who performed the event.
Measure a conversion	Data > Events & conversions > Conversion Metrics	An event name to count. To total a value such as revenue, add a numeric property and turn on Track a value for each event.

Shape properties for how you will use them

Name each event for the action your customer took, and put the details of that action in event properties. For example, send the SKU as a property: purchase_completed with "sku": "SKU-4412". Don’t add it to the name, as in purchase_completed_SKU-4412, because every product then creates a new event name. See Name events so you don’t reach the limit. Event properties can be used for different actions:

Use	Example
Filter (Segment filters, Journey entry filters, Wait Until conditions)	`plan: "pro"`, `category: "shoes"`, `order_number: 1`
Personalize messages (see Custom Event personalization)	`product_name: "Blue Sweater"`, `image_url`, `deep_link`
Measure a conversion value (must be a number)	`total: 84.5`

Follow these rules so filters and metrics behave the way you expect:

Send numbers as numbers. Segment filters skip a number sent as a string, so a total of "84.5" never matches greater than 50. Conversion Metrics only offer number-typed properties for value tracking.
Filter strings match exactly and are case sensitive. "Apple Pay" and "apple_pay" are different values. Use lowercase values from a set you control.
Use the same property names on every event. Send product_id on every commerce event, so the same filters and metrics work across all of them.

Event examples

See how these event examples can perform multiple jobs within OneSignal. Use an event for one job or for all of them. Send an example as an item in the events array of the Create custom events API, or pass its name and properties to trackEvent in the SDK.

Purchase completed

JSON

{
  "name": "purchase_completed",
  "external_id": "user_12345",
  "properties": {
    "order_id": "ord_98213",
    "cart_id": "cart_5541",
    "total": 84.5,
    "currency": "USD",
    "category": "shoes",
    "order_number": 1,
    "items": [
      {
        "name": "Trail Runner",
        "sku": "TR-220",
        "price": 84.5
      }
    ]
  }
}

Trigger an onboarding series for first-time buyers. Start a post-purchase Journey when purchase_completed arrives with order_number equal to 1.
Segment big spenders. Target people who performed purchase_completed in the last 90 days with a total over 100.
Measure the revenue your messages drive. Create a Conversion Metric on purchase_completed and turn on Track a value for each event for total. Your message, template, and Journey reports then show the purchase revenue each message drove.
Personalize the order confirmation with the product they bought. For example: “Thanks for your order. Your Trail Runner ships soon.”

Checkout started

JSON

{
  "name": "checkout_started",
  "external_id": "user_12345",
  "properties": {
    "cart_id": "cart_5541",
    "cart_total": 129.0,
    "currency": "USD",
    "item_count": 2
  }
}

Trigger a cart-recovery Journey. Start the Journey when checkout_started arrives, then wait up to 1 hour for purchase_completed. People who don’t buy in that hour get a reminder.
Segment high-value shoppers. Target people who performed checkout_started in the last 7 days with a cart_total over 75.
Measure checkouts. Create a Conversion Metric on checkout_started to see which campaigns get people to checkout. Track a value for cart_total to see how much cart value your messages drive.
Personalize the reminder with the size of their cart. For example: “You left 2 items in your cart.”

JSON

{
  "name": "signup_completed",
  "external_id": "user_12345",
  "properties": {
    "plan": "trial",
    "signup_method": "google"
  }
}

Trigger separate onboarding for trial and paid users. Start each onboarding Journey when signup_completed arrives, and filter entry on plan.
Segment trial users. Target people who performed signup_completed in the last 7 days with plan set to trial.
Measure signups. Create a Conversion Metric on signup_completed to see which acquisition messages drive signups.
Personalize the welcome message by plan. For example, trial users see “Your 14-day trial has started.”

Level completed

JSON

{
  "name": "level_completed",
  "external_id": "user_12345",
  "properties": {
    "level": 5,
    "stars": 3,
    "duration_seconds": 212
  }
}

Trigger milestone rewards. Start a Journey when a player completes level 1 (level_completed with level equal to 1). Then add a Wait Until step for each milestone at levels 5, 10, and 20, each followed by a reward message. See Progressive journeys.
Segment advanced players. Target players who performed level_completed in the last 30 days with a level of 10 or higher, and send them offers for your most committed players.
Measure re-engagement. Create a Conversion Metric on level_completed to see which messages bring players back.
Personalize the reward with the level and stars they earned. For example: “Level 5 cleared with 3 stars!”

Subscription cancelled

JSON

{
  "name": "subscription_cancelled",
  "external_id": "user_12345",
  "properties": {
    "plan": "pro",
    "reason": "too_expensive",
    "months_active": 14
  }
}

Trigger a win-back Journey. Start the Journey when subscription_cancelled arrives.
Segment recently cancelled users. Target people who performed subscription_cancelled in the last 30 days. Use this Segment in a Journey Yes/No branch to skip promotional steps for them.
Measure recovered revenue. Track the resubscription, not the cancellation. Create a Conversion Metric on subscription_started, turn on Track a value for each event for its price property, and set the metric as the Message Goal on your win-back messages.
Personalize the offer by cancellation reason. For example, users who cancelled over price see “Here’s 30% off your next 3 months.”

FAQ

Should this be a Custom Event or a Tag?

If it describes a customer action, or happened at a moment in time, send a Custom Event. If it describes a customer attribute, send it as a Tag. A purchase is a Custom Event. A customer’s favorite team is a Tag. Custom Events are more powerful than Tags, and OneSignal recommends using them over Tags in most cases. See Tags vs Custom Events.

Can one Segment filter combine properties from two different events?

No. Property filters apply to a single event occurrence. To target people who did one thing and another, add a second Custom Event filter to the Segment. To target people who did one thing with two matching properties, add both properties to the same filter and choose With all of the following properties.

Can Journey exit rules filter on event properties?

No. Exit rules match on the event name only, so any occurrence of that event exits the user. To act on specific property values, filter the entry rule or a Wait Until condition instead.

Custom events

Send events, verify them, and use them across OneSignal.

Custom event storage and retention

Turn on storage and set retention per event.

Segmentation

Build Segments with Custom Event filters.

Conversion metrics

Measure the conversions and revenue your messages drive.

First steps & settings

Message channels

Journeys

OneSignal AI

Audience & events

Analytics & Integrations

Privacy & Security

Custom event best practices

Prerequisites

Make the most of your events and event properties

Shape properties for how you will use them

Event examples

Purchase completed

Checkout started

Level completed

Subscription cancelled

FAQ

Should this be a Custom Event or a Tag?

Can one Segment filter combine properties from two different events?

Can Journey exit rules filter on event properties?

Custom events

Custom event storage and retention

Segmentation

Conversion metrics

​Prerequisites

​Make the most of your events and event properties

​Shape properties for how you will use them

​Event examples

​Purchase completed

​Checkout started

​Signup completed

​Level completed

​Subscription cancelled

​FAQ

​Should this be a Custom Event or a Tag?

​Can one Segment filter combine properties from two different events?

​Can Journey exit rules filter on event properties?

​Related pages

Custom events

Custom event storage and retention

Segmentation

Conversion metrics

Prerequisites

Make the most of your events and event properties

Shape properties for how you will use them

Event examples

Purchase completed

Checkout started

Signup completed

Level completed

Subscription cancelled

FAQ

Should this be a Custom Event or a Tag?

Can one Segment filter combine properties from two different events?

Can Journey exit rules filter on event properties?

Related pages