Skip to main content
Use properties (such as user tags and identifiers like External ID) to personalize messages and delivery payloads with Liquid syntax. OneSignal renders Liquid placeholders at send time, using data already stored on the user, subscription, Journey, message, template, app, or organization. You can use this data to personalize messages, Journey webhooks, and Event Streams.

​
When to use property personalization

Use property personalization to render content at send time using data that already exists in OneSignal—most commonly user tags, External ID, and subscription fields like email or phone number. This is the right approach when:
  • The data is already stored in OneSignal
  • You want Liquid placeholders replaced automatically when the message sends
  • You don’t need to fetch or compute fresh data at delivery time
If the value must be fetched or computed at send time (for example, live pricing or inventory), use Data Feeds or our API with custom_data.If the value comes from the event that caused a user to enter or progress through a Journey, use Custom Event personalization.

​
Channel support

Each channel supports specific property types and fields.
Supports User & Subscription properties in:
  • Subject, Reply-to, and Pre-header
  • Message body
  • HTML attributes (for example: <img src="{{ image_url }}" />)
  • Button actions (URLs, mailto, etc.)

​
How property personalization works

OneSignal replaces Liquid placeholders with the corresponding property values for the user and subscription being messaged.
Liquid
Hi {{ first_name | default: "friend" }}!
Congrats on reaching level {{ level | default: "1" }}!
If a user has tags first_name: Jon and level: 5, they see:
Text
Hi Jon! 
Congrats on reaching level 5!
If a user has no tags set, they see the default values instead.

​
Property Liquid reference

Use this section to look up the exact object and field names available in Liquid.

​
User & Subscription properties

Use user for user-level data. Use subscription when you need channel-specific values like email address or phone number.
​
user.tags
The Tags of the User. You can reference the tags in several ways:
  • Use the key directly or place the key after tags
  • Example tags set: first_name: Jon, level: 5
Liquid
Your first name is {{ first_name }}.
Your first name is {{ user.tags.first_name }}.
Your level is {{ level }}.
Your level is {{ user.tags.level }}.
  • Iterate over tags with for-loop syntax. This example outputs key:value pairs separated by commas.
Liquid
{% for tag in user.tags %}
{{ tag[0] }}: {{ tag[1] }}
{% unless forloop.last %}, 
{% endunless %}{% endfor %}
​
user.external_id
The External ID of the User.
Liquid
Your user ID is {{ user.external_id }}.
Your user ID is {{ subscription.external_id }}.
​
user.onesignal_id
The OneSignal ID of the User.
Liquid
Your OneSignal user ID is {{ user.onesignal_id }}.
​
subscription.email
The email address of the email Subscription being messaged.
Liquid
Thanks for subscribing with email {{ subscription.email }}.
​
subscription.phone_number
The phone number of the SMS Subscription being messaged.
Liquid
Thanks for subscribing with phone number {{ subscription.phone_number }}.
​
user.language
The language code of the user.
Liquid
Preferred language: {{ user.language }}
Preferred language: {{ subscription.language }}
​
user.subscriptions
The Subscriptions of the User.
  • Iterate over subscriptions with for-loop syntax.
  • This example outputs each subscription’s token and ID separated by commas.
JSON
{
  "subscriptions": "{% for subscription in user.subscriptions %}{% if subscription.subscription_token %}{{ subscription.subscription_token }}: {{ subscription.id }}{% unless forloop.last %}, {% endunless %}{% endif %}{% endfor %}"
}
​
subscription.unsubscribe_token
The token used with the Unsubscribe email with token API.
Liquid
Unsubscribe: https://your-domain.com/unsubscribe?token={{ subscription.unsubscribe_token }}

​
Journey properties

The journey object lets you reference the Journey name or access Custom Event Personalization for the Journey.
​
journey.name
The name of the Journey.
JSON
{
  "journey_name": "{{ journey.name }}"
}

​
Message properties

The message object provides access to the message ID, name, and template ID that can be helpful for Event Streams along with access to custom_data for personalizing messages sent from your backend.
​
message.id
The ID of the message set by OneSignal.
JSON
{
  "message_id": "{{ message.id }}"
}
​
message.name
The name of the message set by you, the sender.
JSON
{
  "message_name": "{{ message.name }}"
}
​
message.template_id
The ID of the template set by OneSignal.
JSON
{
  "template_id": "{{ message.template_id }}"
}

​
Template properties

The template object provides access to the template ID and name about the Template used to send the message. This can be helpful for Event Streams.
​
template.id
The ID of the template set by OneSignal.
JSON
{
  "template_id": "{{ template.id }}"
}
​
template.name
The name of the template set by you, the sender.
JSON
{
  "template_name": "{{ template.name }}"
}

​
App and organization properties

The app and org objects provide details about the App and Organization that sent the message. This can be helpful for Event Streams.
​
app.id
The ID of the app set by OneSignal.
JSON
{
  "app_id": "{{ app.id }}"
}
​
app.name
The name of the app set by you, the owner of the app.
JSON
{
  "app_name": "{{ app.name }}"
}
​
org.id
The ID of the Organization set by OneSignal.
JSON
{
  "org_id": "{{ org.id }}"
}
​
org.name
The name of the Organization set by you, the owner of the Organization.
JSON
{
  "org_name": "{{ org.name }}"
}

​
Example: Abandoned cart templates using tags

This example shows how to personalize abandoned cart messages using user tags. It builds on the Abandoned Cart tutorial. Example tags set:
JSON
{
  "cart_updated": "unix_timestamp_seconds",
  "product_image": "https://i.imgur.com/ssPCfbC.png",
  "product_name": "24 Pack of Acorns",
  "product_quantity": "1",
  "product_price": "$12.99",
  "cart_items_count": "4",
  "cart_url": "https://yourdomain.com/cart"
}

​
Email template

1

Create a new email template

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

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
3

Add liquid to paragraph blocks

In row 1, add:
Liquid
We're holding onto {{cart_items_count}} items in your cart, but don't wait too long, other squirrels are getting ahead!
In row 2, add a description of what the user is looking at:
Text
Currently in your cart:
In row 4, add another CTA:
Text
Checkout now while supplies last!
4

Display the most recent item

In row 3, configure the four columns:Column 1 (HTML block):
HTML
<img src="{{product_image}}" alt="Image" style="max-width:100%;" />
Columns 2–4 (Text blocks):
  • Column 2: {{product_name}}
  • Column 3: {{product_quantity}}
  • Column 4: {{product_price}}
5

Add the cart URL to the button

In the row 5 Button block, set the Action URL to:
{{cart_url}}
6

Test & preview the template

Send a test email to yourself using the Test & preview button.
  • Make sure the tags are set on your email Subscription.
7

Style the template

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 item_count = cart_items_count | plus: 0 %}
{% if item_count == 1 %}
You left {{product_name}} in your cart.
{% endif %}
{% if item_count == 2 %}
You left {{product_name}} and {{item_count | minus: 1}} more item in your cart.
{% endif %}
{% if item_count > 2 %}
You left {{product_name}} and {{item_count | minus: 1}} more items in your cart.
{% endif %}
Image field:
Liquid
{{product_image | default: "https://i.imgur.com/ssPCfbC.png"}}
Launch URL field:
Liquid
{{cart_url | default: "https://yourdomain.com/cart"}}
Success! You can now create more templates and use them in the Abandoned Cart Journey.

Message personalization

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

Tags

Learn how to set tags on users via SDK, API, or CSV import.

Using Liquid syntax

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

Templates

Create and manage reusable message templates for use in Journeys.

In-app message examples

Display personalized in-app messages based on tags.

Abandoned cart tutorial

Build an abandoned cart Journey using Tags and Properties.
Need help?Chat with our Support team or email [email protected]Please 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!