Personalize with Custom Events

Custom Events let you personalize Journey messages using event properties (product names, prices, URLs, arrays, etc.). Event properties become available in templates only if the event:

Triggers Journey entry, or
Matches a Wait Until condition inside the Journey

Stored event properties can be accessed using Liquid syntax.

How Custom Event personalization works

Add event properties to your Journey messages following these steps:

Send a Custom Event with properties

Example Custom Events payload:

JSON

{
  "name": "purchase",
  "properties": {
    "item": "Blue Sweater",
    "price": "29.99",
    "order status": "pending",
    "details": [
      {
        "manufacturer": "Company A",
        "model": "1234567890"
      },
      {
        "manufacturer": "Company B",
        "model": "9876543210"
      }
    ]
  },
  "external_id": "user_12345",
  "timestamp": "2025-10-21T19:09:32.263Z",
}

Reference event properties in your Journey message templates

Use Liquid syntax to access event properties.

Common Liquid access patterns

What you want	Liquid	Output
Event name	`{{ journey.first_event.name }}`	`purchase`
Property	`{{ journey.first_event.properties.item }}`	`Blue Sweater`
Nested properties	`{{ journey.first_event.properties.details.first.manufacturer }}`	`Company A`
Property with special characters	`{{ journey.last_event.properties["order status"] }}`	`pending`
Timestamp	`{{ journey.last_event.timestamp \| date: "%B %d, %Y at %I:%M %p" }}`	`October 21, 2025 at 07:09 PM`

Nested Liquid access patterns

You can also access nested properties using dot and bracket notation:

Liquid

{{ journey.first_event.properties.details.first.manufacturer }} = Company A
{{ journey.first_event.properties.details.last.manufacturer }} = Company B
{{ journey.first_event.properties.details[0].manufacturer }} = Company A
{{ journey.first_event.properties.details[1].manufacturer }} = Company B

Invalid Liquid or missing properties render as empty strings. Messages still send. Use default filters to set a fallback.

Create a Journey

Setup the Journey to use the Custom Event as the entry rule and/or Wait Until condition.

See Journeys settings for Entry rules.
See Journeys actions for Wait Until conditions.

Add message nodes with the templates.

Event property storage rules

You can use multiple events in your Journey by combining entry rules and Wait Until steps.
Maximum: 100 stored event properties per user per Journey instance (oldest dropped).
Event properties are stored per user, per Journey instance.
Events sent before entry are not accessible.
Event properties are cleared when the user exits the Journey.

Events stored in one Journey cannot be accessed in another Journey.

Custom Event Liquid reference

Use these objects to access stored events inside the Journey.

The first stored event for this Journey instance.

If using a Custom Event Entry Rule, than this is the event that caused Journey entry.
If not using a Custom Event Entry Rule, then this is the first event stored by matching a Wait Until condition.

Liquid

Thanks for purchasing {{ journey.first_event.properties.item | default: "your item" }}!

The most recent stored event for this Journey instance.

If only one event is stored, first_event and last_event return the same thing.

Liquid

Your most recent purchase was {{ journey.last_event.properties.item | default: "made" }}!

The most recent stored event with a specific name.

Replace EVENT_NAME with your event name (e.g., purchase).
If the same event name is used multiple times, this returns the most recent instance.

Liquid

{% assign event = journey.event.purchase %}

If your event name includes spaces or special characters, use bracket notation.Example Event: "name": "order status"

Liquid

{% assign event = journey.event["order status"] %}

array

All stored events for this Journey instance, in the order they were stored.

Use for loops to iterate over them.

Liquid

{% for event in journey.all_events %}
• {{ event.properties.item | default: "Item" }} — ${{ event.properties.price | default: "0.00" }}
{% endfor %}

journey.first_event is shorthand for journey.all_events[0].
journey.last_event is shorthand for the most recent event in the array.

Example: Abandoned cart templates using Custom Events

This example shows how to personalize abandoned cart messages using Custom Events. It builds on the Abandoned Cart tutorial. Example Custom Event set:

JSON

{
  "events": [
    {
      "name": "cart_abandoned",
      "properties": {
        "cart_url": "https://yourdomain.com/username/cart",
        "cart": [
          {
            "product_name": "24 Pack of Acorns",
            "product_image": "https://i.imgur.com/ssPCfbC.png",
            "product_price": "$12.99",
            "product_quantity": "1"
          },
          {
            "product_name": "Fancy Sweater",
            "product_image": "https://i.imgur.com/8QWTfV4.png",
            "product_price": "$9.99",
            "product_quantity": "1"
          }
        ]
      },
      "external_id": "ID_OF_THE_USER"
    }
  ]
}

Email template

This example shows how to build an email template that displays:

The cart item count
Each product with image, name, quantity, and price using a for-loop
A button that links to the customer’s unique cart URL

Create the email template

Navigate to Messages > Templates > New Email Template and open the Drag & Drop Editor.

Add the layout structure

Create five rows:

Rows 1, 2, and 4: one column with a Paragraph block
Row 3: four columns with HTML | Paragraph | Paragraph | Paragraph
Row 5: one column with a Button block

Starter email template for abandoned cart

Display the item count

In row 1, add:

Liquid

We're holding onto {{journey.first_event.properties.cart.size}} items in your cart, but don't wait too long!

For better grammar, you could use a conditional to say “1 item” vs “2 items”, but for abandoned cart emails, plural is usually acceptable.

Liquid

{% assign cart = message.custom_data.cart %}
{% assign item_count = cart.size | plus: 0 %}
{% if item_count == 1 %}
We're holding onto {{item_count}} item in your cart, but don't wait too long, other squirrels are getting ahead!
{% endif %}
{% if item_count > 1 %}
We're holding onto {{item_count}} items in your cart, but don't wait too long, other squirrels are getting ahead!
{% endif %}

Start the for-loop

Use a for-loop to repeat the product display row for each cart item.In row 2 (loop start), add:

Liquid

{% for product in journey.first_event.properties.cart %}

What this does:

Begins a loop that iterates over each object in the cart array
Creates a temporary variable product representing the current item
Everything between {% for %} and {% endfor %} repeats once per cart item
You can name product anything (e.g., item, cartItem)—just stay consistent

For-loop placement: Make sure the {% for %} syntax is in its own Text block row. Don’t put it inside a multi-column row with other content, as this can break email rendering in some clients.

Display product details

This 4-column row shows image, name, quantity, and price. Because it’s inside the loop, it repeats for every cart item.In row 3 (product details), configure:Column 1 - HTML block (product image):

<img src="{{product.product_image}}" alt="Product image" style="max-width:100%;" />

Columns 2–4 - Text blocks (product name, quantity, price):

Column 2: {{product.product_name}}
Column 3: {{product.product_quantity}}
Column 4: {{product.product_price}}

How the loop works:

On first iteration, product = first object in cart array
{{product.product_image}} gets the first item’s image
On second iteration, product = second object
Row repeats automatically for all cart items

Field name matching: Keys like product_image must exactly match your event payload (case-sensitive). Mismatches render as empty strings.

End the for-loop

Close the loop to mark where repetition stops.In row 4 (loop end), add:

Liquid

{% endfor %}

Every {% for %} must have a matching {% endfor %}. Missing this will break email rendering.

Add the cart URL button

In the row 5 Button block, set the Action URL to:

Liquid

{{journey.first_event.properties.cart_url}}

Finished base email template for abandoned cart without styling

Test the template

Add the template to a blank Journey and set the entry rule to a Custom Event.
Enabling the Journey and entering yourself into it via the Custom Event API.
Verify the data displays correctly.

Success! Now you can apply your own styling to the template. See Design emails with drag-and-drop.

Push template

Push notifications have limited space, so display one item and mention the total count. Message field: Display item and count with correct grammar using conditional statements.

Liquid

{% assign cart = journey.first_event.properties.cart %}
{% assign item_count = cart.size | plus: 0 %}
{% if item_count == 1 %}
You left {{cart.first.product_name}} in your cart.
{% endif %}
{% if item_count == 2 %}
You left {{cart.first.product_name}} and {{item_count | minus: 1}} more item in your cart.
{% endif %}
{% if item_count > 2 %}
You left {{cart.first.product_name}} and {{item_count | minus: 1}} more items in your cart.
{% endif %}

Image field:

Liquid

{{journey.first_event.properties.cart.first.product_image | default: "https://i.imgur.com/ssPCfbC.png"}}

Launch URL field:

Liquid

{{journey.first_event.properties.cart_url | default: "https://yourdomain.com/cart"}}

Send yourself a test push notification by adding it to the test Journey and entering yourself into it via another Custom Event API call. You should see a notification similar to this appear:

Success! You can now create more templates and use them in the Abandoned Cart Journey.

Troubleshooting & best practices

Common mistakes:

Mistake	Why it fails	Correct syntax
`{{ journey.first_event.item }}`	Missing `.properties`	`{{ journey.first_event.properties.item }}`
`{{ journey.event.purchase.item }}`	Missing `.properties`	`{{ journey.event.purchase.properties.item }}`
`{{ journey.first_event.properties.Item }}`	Wrong case (should be `item`)	`{{ journey.first_event.properties.item }}`
`{{ event.properties.item }}`	Missing `journey.` prefix	`{{ journey.first_event.properties.item }}`

Best practices:

Always test templates before going live
Use default filters for optional properties
Validate event schema matches template expectations

Message personalization

Overview of all personalization options in OneSignal, including when to use Custom Events vs other methods.

Custom Events

Complete guide to implementing and sending Custom Events via SDK or API.

Journeys overview

Learn how to build automated messaging workflows with triggers, conditions, and actions.

Journey settings

Configure event-triggered entry rules and Journey behavior.

Wait Until actions

Use Wait Until nodes to store additional events during Journey progression.

Using Liquid syntax

Complete Liquid reference with filters, conditionals, loops, and string manipulation.

Templates

Create and manage reusable message templates for use in Journeys.

Need help?Chat with our Support team or email support@onesignal.comPlease include:

Details of the issue you’re experiencing and steps to reproduce if available
Your OneSignal App ID
The External ID or Subscription ID if applicable
The URL to the message you tested in the OneSignal Dashboard if applicable
Any relevant logs or error messages

We’re happy to help!

First steps & settings

Message channels

Journeys

OneSignal AI

Audience & events

Analytics & Integrations

Privacy & Security

Personalize with Custom Events

How Custom Event personalization works

Common Liquid access patterns

Nested Liquid access patterns

Event property storage rules

Custom Event Liquid reference

Example: Abandoned cart templates using Custom Events

Email template

Push template

Troubleshooting & best practices

Message personalization

Custom Events

Journeys overview

Journey settings

Wait Until actions

Using Liquid syntax

Templates

​How Custom Event personalization works

​Common Liquid access patterns

​Nested Liquid access patterns

​Event property storage rules

​Custom Event Liquid reference

​Example: Abandoned cart templates using Custom Events

​Email template

​Push template

​Troubleshooting & best practices

​Related pages

Message personalization

Custom Events

Journeys overview

Journey settings

Wait Until actions

Using Liquid syntax

Templates

How Custom Event personalization works

Common Liquid access patterns

Nested Liquid access patterns

Event property storage rules

Custom Event Liquid reference

Example: Abandoned cart templates using Custom Events

Email template

Push template

Troubleshooting & best practices

Related pages