Send dynamic, message-specific data through the Create Message API using custom_data. Reference values in templates with Liquid syntax for real-time personalization.
Use the custom_data field in the Create Message API to send dynamic data from your backend and render it inside templates using Liquid syntax.custom_data:
Is message-specific
Is not saved to user profiles and can’t be reused in later messages
Must be used with a template_id
Has a size limit set by OneSignal: 2KB for push and SMS, 10KB for email
Reference values in templates with:
Liquid
{{ message.custom_data.key_name }}
custom_data is ephemeral. Data is not saved to user profiles and cannot be reused in future messages. If you need persistent data, see Message personalization.
Data changes per message (order totals, cart items, balances)
You need arrays (product lists, line items, recommendations)
Data should not persist (one-time codes, temporary URLs)
You send backend-triggered messages
You want bulk personalization in one API request
custom_data is not the right fit when you’d send the same large dataset on every request (for example, a full product catalog that Liquid picks from per recipient). Use Dynamic Content for shared content, or Data Feeds to fetch data from your API at send time (email in Journeys only).
custom_data is not sent to devices. OneSignal uses it on its servers to render your template, then sends only the rendered message to APNs or FCM. APNs and FCM each limit the delivered push payload to 4,096 bytes. That limit applies to the final notification (title, message, Additional Data, and other fields), not to custom_data.
custom_data is different from the data field. The data field (Additional Data) is delivered to the device and has its own 2,048-byte limit. See Push overview.
Audience targeting (include_player_ids, include_aliases, or segments)
OneSignal renders the template at send time using your data.If Liquid syntax is invalid or keys don’t exist, those fields render as empty strings, but the message still sends.
Use simple key-value pairs for basic personalization like names, IDs, URLs, or any single-value data.Use case: Transactional messages (invoices, receipts, confirmations) where each field contains a single value.Template:
Liquid
Invoice {{ message.custom_data.invoice_id }} for {{ message.custom_data.product_name }} is ready.
Pass arrays of objects to work with multiple items like cart products, order line items, or recommendations. Arrays enable both direct access (indexing) and iteration (loops).Use case: Displaying product lists, leaderboards, order summaries, or any multi-item data.Indexing template (accessing first item):
Liquid
Your {{message.custom_data.cart_items[0].item_name}} is waiting for you!Image: {{message.custom_data.cart_items[0].img_url}}
Array indexing starts at 0, not 1. The first item is [0], second is [1], etc. Accessing an index that doesn’t exist returns empty (no error thrown).
Looping template (accessing all items):
Liquid
{% for item in message.custom_data.cart_items %}- {{ item.item_name }} — {{ item.img_url }}{% endfor %}
Send a single API request to multiple users where each recipient sees personalized content based on their external_id.How it works:
Structure custom_data as an object where keys are external_ids and values are user-specific data
In the template, use subscription.external_id to look up the current recipient’s data
OneSignal renders the template once per recipient with their specific data
Template:
Liquid
{% assign user = message.custom_data.users[subscription.external_id] %}Hi {{ user.first_name }}, you have {{ user.points }} points. Your level is {{ user.level }}.
What’s happening:
subscription.external_id contains the current recipient’s external_id (e.g., “user123”)
message.custom_data.users[subscription.external_id] looks up that user’s data from the custom_data object
user becomes a shorthand variable for that user’s data
Each recipient only sees their own personalized content
John (user123): “Hi John, you have 150 points. Your level is Gold.”
Sarah (user456): “Hi Sarah, you have 200 points. Your level is Platinum.”
Requirements for bulk personalization:
All recipients must have an external_id set in OneSignal
Each external_id in include_aliases must have a matching key in custom_data.users
If a recipient’s external_id is missing from custom_data, their message will have empty fields
The bulk custom_data object grows with every recipient you add, and the whole object counts toward the size limit. For push and SMS, this pattern fits only a small number of recipients per request. Split large audiences across multiple requests, or store per-user values as Tags instead.
Customer’s unique cart link (for buttons/launch URLs)
cart
array
List of products—supports counting, looping, and detail display
product_image
string
Product image (per item in array)
product_name
string
Product name (per item)
product_quantity
string
Quantity (per item)
product_price
string
Price with formatting (per item)
You can name fields anything you want—just ensure your template’s Liquid syntax matches.
Stay within the size limit: 2KB for push, 10KB for email. If you have large carts, limit to the first 3-5 items or send only essential fields. See custom_data size limits.
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
Example Abandoned Cart Email Template
1
Create the 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
Starter email template for abandoned cart
3
Display the item count
In row 1, add:
Liquid
We're holding onto {{message.custom_data.cart.size}} items in your cart, but don't wait too long, other squirrels are getting ahead!
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 %}
4
Start the for-loop
Use a for-loop to repeat the product display row for each cart item.In row 2 (loop start), add:
Text
{% for product in message.custom_data.cart %}
What this does:
Begins a loop that iterates over each object in the cart array
Creates a temporary variable called product that represents 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.
5
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):
Push notifications have character limits and operating system restrictions, so instead of showing all items, display the first product and indicate the total count with proper grammar.Here is an example push notification we will build:
Abandoned cart push template example
Message field:
Liquid
{% assign cart = message.custom_data.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 %}
Test templates with the actual custom_data structure before production
API rejects the request because custom_data is too large
Cause:custom_data exceeds the limit for the channel: 2KB for push and SMS, 10KB for email. This is a OneSignal limit, not an APNs or FCM limit. See custom_data size limits.Solutions:
Remove unnecessary fields from your payload
Shorten field names and values where possible
Limit arrays to first 3-5 items
Move large static content (like full HTML) to your template instead
