Data feeds

Documentation Index

Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt

Use this file to discover all available pages before exploring further.

• A user’s current rewards balance
• Latest order status
• Personalized product recommendations

​

How Data Feeds work

1. Create a Data Feed – Configure how OneSignal connects to your API.
2. Attach the Data Feed to a message template.
3. Insert response fields in your message using Liquid syntax.
4. At send time, OneSignal makes an API call for each recipient, parses the response, and injects the data into your message.

​

Example: Display reward points

Hi {{ first_name }},

You have {{ data_feed.rewards.points }} points!
Your membership status is {{ data_feed.rewards.status_level }}.

Keep shopping to earn more points!

​

Creating and using a Data Feed

​

1. Set up your Data Feed configuration

• Name: A descriptive name like “Customer Rewards API” to help you distinguish feeds. Unique names are recommended but not required.
• Alias: A short identifier like rewards used in Liquid syntax (e.g., {{ data_feed.rewards.points }}). Must be unique, lowercase, alphanumeric, with no spaces or special characters.
• Method: The HTTP method OneSignal uses to contact your API. Usually GET, but POST is also supported.
• URL: Your API endpoint. Supports Liquid syntax so OneSignal can fetch user-specific data.

https://acme.com/customers/user_id={{ external_id }}/rewards

• Headers: Key-value pairs required by your API (e.g., authentication tokens). Supports Liquid syntax.
• Body: Optional JSON request body. Supports Liquid syntax, the same as Journey webhooks.

{
	"customer_id": "{{ subscription.external_id }}"
}

​

2. Attach the Data Feed to your message template

1. Navigate to Messages > Templates
2. In the Message section, select the Personalization button

3. Toggle on Data Feeds and select your feed

4. Save your template

​

3. Use the data in your message

{
	"external_id": "a1-b2c3",
	"points": 193,
	"status_level": "Gold"
}

You have {{ data_feed.rewards.points }} points!
Your membership status is {{ data_feed.rewards.status_level }}.

• Use a Data Feed
• Use the rewards Data Feed
  • Recall: the rewards feed knows to call the API with the external_id of the recipient
• From the response, insert the value of the points item (193) and the status_level item (Gold)

​

Requirements and limits

• Accept single-step authentication with auth tokens in headers
• Respond quickly. Under 250ms recommended (this directly affects send speed)
• Return JSON. Other formats are not supported at this time.
  • If you need a different format, share your use case.
• Handle your send volume. A low rate limit on your API slows message delivery.
• Return reasonably-sized payloads. Keep responses under 50 KB for best performance.

• One Data Feed per template. Fetch everything you need in a single API response.
• One API call per Data Feed per message.
• Journeys only. Not yet available for other sending methods.
• No chaining calls. The payload from one Data Feed cannot be used to call another.

​

Setting up your API

​

Authentication

Authorization: Bearer YOUR_TOKEN

X-API-Key: YOUR_KEY

​

JSON request body

​

JSON response

​

Personalization parameters

https://api.example.com/users/{{external_id}}/data
https://api.example.com/rewards?email={{email | url_encode}}

{
	"customer_id": "{{ external_id }}",
	"email": "{{ subscription.email }}"
}

​

Rate limits

​

Error handling

​

Getting started checklist

• What data do I want to show in my message? Working backwards from a simple outline with the items to be populated from your API identified will help you organize your thinking.
• Is this data available via a single API endpoint?
• How will I authenticate API requests?
• What identifier or other data item will I use to fetch personalized data?
• Is that identifier already stored in OneSignal? If not, how will it be populated?
• Can my API handle the volume of requests I’ll generate?
• What happens if my API doesn’t have data for a user?

​

Examples and advanced use cases

• Iterating with loops: abandoned cart
• Custom events properties
• Conditional display: order status
• Automation without personalization
• Personalized coupon codes

Let’s say you have a Data Feed cart that returns an array of items in the user’s cart, plus the cart total dollar amount:

{
  "items": [
    {
      "name": "Blue Running Shoes",
      "price": 84.00,
      "image_url": "https://acme.com/blue-running-shoes.png"
    },
    {
      "name": "Protein Bar",
      "price": 5.99,
      "image_url": "https://acme.com/protein-bar.png"
    }
  ],
  "total": 89.99
}

If you want to show each item in the cart, plus the cart total, you can use a for loop in Liquid:

<ul>
  {% for item in data_feed.cart.items %}
    <li>
      <strong>{{ item.name }}</strong><br>
      ${{ item.price }}<br>
      <img src="{{ item.image_url }}" alt="{{ item.name }}">
    </li>
  {% endfor %}
</ul>

<p>Cart total: ${{ data_feed.cart.total }}</p>

This will result in:

- Blue Running Shoes
- $84.00
- <running shoes image>
- Protein Bar
- $5.99
- <protein bar image>
Cart total: $89.99

If you’re using the email block editor, when inserting this sort of complex Liquid syntax, particularly if you need to include images or links, for best results use the custom HTML block element.

Want to see how to trigger this abandoned cart email using custom events? Check out the Custom events properties tab for the complete workflow.

Continuing the previous abandoned cart example, how might we know how to fetch that particular cart in the first place?One method might be to create a Journey triggered by a cart_abandoned custom event, where the properties includes a cart_id. In this example that event is being sent to OneSignal via API:

curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/custom_events \
  --header 'Accept: application/json' \
  --data '{
  "events": [
    {
      "name": "cart_abandoned",
      "external_id": "user_12345",
      "properties": {
        "cart_id": 98765
      }
    }
  ]
}'

The user user_12345 enters the journey when this event is fired, then reaches a node sending an email. That email template is set up with the cart Data Feed, where the URL is set to retrieve the contents of a particular cart like so:

https://acme.com/carts/{{ journey.event.cart_abandoned.data.cart_id }}

Thus, when this particular event is ingested and triggers the Journey:

1. The cart_id value of 98765 will be stored to the Journey
2. When the email step is reached, the cart Data Feed will reference that cart_id value and use it to call the cart API
3. The returned JSON properties will be parsed and inserted into the email as in the previous example above

Want to see how to conditionally display Data Feed content based on order status? Check out the Conditional display: order status tab to learn more.

Let’s say you want to include the status of a customer’s order, but only include a tracking number link if the order has been shipped. You can use an if statement to do so:

Your order is {{data_feed.order.status}}!

{% if data_feed.order.tracking_number != empty %}
Track it here: {{data_feed.order.tracking_url}}
{% endif %}

Here, the tracking link will only be displayed if the tracking_number exists.

Data Feeds can be used to automatically insert up-to-date information into your messages without necessarily needing to be personalized per recipient.For example, perhaps you insert a banner image at the top of your emails and change it monthly to keep up with holidays and other monthly events. Rather than remembering to upload a new image to OneSignal and changing all your templates each month, you might set up a Data Feed that fetches the current banner image URL from your CMS or other asset-management location.You would set up a banner Data Feed that points to an endpoint without any variables in the URL like so:

https://acme.com/assets/email-banner

Which returns a response with the current banner URL:

{
	"banner_url": "https://acme.com/assets/email-banner/2025july.png"
}

You’d set your email template to use {{ data_feed.banner.banner_url }} as the image source URL, automating this process going forward.

This example covers how to send personalized, single-use coupon codes in emails using a Data Feed that fetches a unique value from your API for each recipient.

​

Goal

Send an email such as:

Hi George, Complete your booking in the next 2 hours and save 10% with your personal code: XYZ123ABC

Each user receives a unique coupon code, generated live via an external API call when the email is sent, valid for the given time window, and scoped to that user.

​

Prerequisites

• Email channel configured in OneSignal (your app has email capability enabled)
• An external API that accepts a user identifier (for example, external_id) and campaign identifier, and returns JSON with the coupon code, discount, and expiration
• A unique identifier (such as external_id) for each user that your API can use to generate coupons
• A segment or trigger (for example, “abandoned search in last 24h”) used to send the email through a OneSignal Journey

​

Step 1: Create the Data Feed

1

Navigate to Data Feeds

In your OneSignal app, select Data feeds from the navigation bar, then click New data feed.

2

Configure the Data Feed

Configure the following fields:

• Data Feed Name: coupon_code_generator
• Alias: coupon
• Method: GET
• URL: https://api.example.com/generate-coupon?userId={{ external_id }}&campaign=AbandonedBooking10
• Headers:
  {
    "Authorization": "Bearer YOUR_API_TOKEN"
  }
  

3

Reference the API response

When the API returns JSON like this:

{
  "code": "AB10-5F3K-HT9L",
  "discount_percent": "10%",
  "expires_in_hours": 2
}

You can reference its values in your email template as:

• {{ data_feed.coupon.code }}
• {{ data_feed.coupon.discount_percent }}
• {{ data_feed.coupon.expires_in_hours }}

4

Test and activate the Data Feed

Click Send Test to verify your configuration, then click Activate to make the Data Feed available for use in templates.

​

Step 2: Create the email template

1. In OneSignal, go to Messages → Email → New Template
2. Use the Data Feed alias and fields within your message body. For example:

<h2>Hi {{ first_name }},</h2>
<p>
Complete your booking in the next {{ data_feed.coupon.expires_in_hours }} hours and save
{{ data_feed.coupon.discount_percent }} with your personal code:
<strong>{{ data_feed.coupon.code }}</strong>
</p>

<p><a href="https://example.com/checkout?coupon={{ data_feed.coupon.code }}">Use Code Now →</a></p>

• Use Liquid syntax in the form {{ data_feed.<alias>.<field> }}
• Make sure the Data Feed is attached to the template
• If using the drag-and-drop editor with custom Liquid logic, use an HTML block

​

Step 3: Attach the Data Feed and trigger the email

1. In the template composer, under Personalization, toggle Data Feeds and select your feed (coupon_code_generator)
2. This ensures OneSignal makes the API call at send time for each recipient, populates the data, and injects it into the email
3. Set up a Journey to automate the message:
   • Entry condition: Segment such as “abandoned search in last 24 hours”
   • Wait until: Create a booking_completed custom event. Configure the wait to exit the Journey if this event fires, or continue after 1 hour. If they complete a booking, they exit without receiving the email; otherwise, they continue to receive the coupon.
   • Send email: Use the personalized coupon email template
   • Ensure the Journey uses the email channel and that recipients are subscribed to email

​

Step 4: Manage coupon redemption and tracking

Your backend should:

1. Record each generated code along with userId, code, campaign, expiration_time, and a redeemed flag
2. Validate and mark codes as redeemed upon checkout
3. Log the redemption data (user, campaign, and time) for ROI analysis

​

Complete workflow example

Step	Event	Action
1	User triggers “abandoned search” segment	User enters Journey via segment
2	Journey triggers email send	OneSignal attaches Data Feed, calls your API with the user’s external_id and campaign name
3	API returns JSON	OneSignal populates data feed coupon fields and sends email
4	User receives email	Example: “Hi George! Save 10% with your personal code: AB10-5F3K-HT9L”
5	User redeems code	Backend validates and logs redemption

​

Testing

• Test with a user who has a known external_id
• Call your API manually to confirm correct JSON responses
• Use Preview in the OneSignal template editor to verify that data feed coupon fields populate
• Check API logs for latency and errors
• If a Data Feed call fails, OneSignal will skip sending the message to that recipient

​

FAQ

​

My Data Feed values are not appearing in the message. What should I check?

1. The Data Feed is attached to the template (under Personalization > Data Feeds).
2. Your Liquid syntax matches the JSON response structure exactly — {{ data_feed.<alias>.<field> }}.
3. The API endpoint returns valid JSON when called manually with the same identifiers.
4. The recipient has the required identifier (e.g., external_id) stored in OneSignal.

​

Why are messages sending slowly?

​

Why are some recipients not getting messages?

​

Can I use more than one Data Feed in a template?

​

Are Data Feeds available for push notifications or SMS?

​

What happens if my API is down when the message sends?

​

Related pages