Skip to main content
Send subscription and purchase data from RevenueCat to OneSignal so you can message users based on where they are in their subscription. RevenueCat updates each user’s Tags with their latest subscription status. It can also send each purchase event to OneSignal as a Custom Event. With the RevenueCat integration, you can:
  • Send onboarding messages to users who start a free trial or subscribe.
  • Re-engage churned users with surveys or discounts.
  • Send transactional messages for purchases, renewals, and billing issues.
  • Start a Journey the moment a user starts a trial, cancels, or hits a billing issue.

Requirements

You should be familiar with Tags, Users, and Subscriptions.

Setup

Pass the OneSignal ID to RevenueCat

RevenueCat uses the OneSignal ID to find the user in OneSignal. RevenueCat only updates users that have a OneSignal ID saved in RevenueCat.
Set the External ID in OneSignal before you send the OneSignal ID to RevenueCat. Calling login can change the OneSignal ID. If RevenueCat has the old ID, its updates do not reach the user.
1

Set the External ID in OneSignal

Set the External ID to your main user ID with the SDK login method.
2

Get the OneSignal ID

Use the user state observer so you get the OneSignal ID whenever it changes. Getter methods are also available.In the observer, check that the External ID matches the user you expect before you pass the OneSignal ID on. Cached requests, for example from a device that was offline, can report a different user.
3

Pass the OneSignal ID to RevenueCat

Save the OneSignal ID in RevenueCat as the $onesignalUserId subscriber attribute. Use the RevenueCat helper method setOnesignalUserID(), or set the attribute directly.If your app already uses OneSignal, also send the OneSignal ID for existing users when they update to the new app version. See RevenueCat’s code examples.
On OneSignal SDK v4 and below, RevenueCat uses the $onesignalId attribute (the Player ID) and the setOnesignalID() helper method instead.

Connect OneSignal to RevenueCat

1

Open the OneSignal integration

In the RevenueCat dashboard, open your project settings and choose OneSignal from the Integrations menu.
2

Add your OneSignal apps

Enter the App ID and App API key of the OneSignal app for each kind of purchase. See Keys and IDs to find them.
  • Production: production purchases go to this app.
  • Sandbox: sandbox purchases go to this app. It can be the same app as Production, or a separate app, such as the one your development builds use.
If you leave both fields in a section empty, RevenueCat does not send events for that kind of purchase.
3

Choose whether to send Custom Events

Turn Send as Custom Events on to send each event as a Custom Event as well as updating Tags. It is on by default for new integrations. Turn it off if your OneSignal app is on the Free plan.
4

Set your tag names

Enter the tag names RevenueCat should use, or keep the defaults. See Tags RevenueCat sends.
RevenueCat picks the OneSignal app from the purchase’s environment, not your build type. Purchases from TestFlight, Google Play license testers, and other test accounts are sandbox purchases, even in a release build. Make sure those users exist in your Sandbox app, or the update fails.
Integrations created before the Sandbox section existed show the same app in both Production and Sandbox. They keep sending sandbox purchases where they did before. To send sandbox purchases to a different app, change the Sandbox section.

Test the integration

1

Make a sandbox purchase

Install your app as a new user and complete a sandbox purchase. The event goes to the OneSignal app in the Sandbox section, so set that up first.
2

Check the OneSignal ID in RevenueCat

In RevenueCat, open the Customer View for the test user. Confirm $onesignalUserId is listed in the user’s attributes.
3

Check that the event was delivered

In the Customer View, open the test purchase in the Customer History. Confirm the OneSignal integration event exists and was delivered.
4

Check the user in OneSignal

In the Sandbox OneSignal app, go to Audience > Users & subscriptions and search for the OneSignal ID. Confirm the user has the Tags RevenueCat set. If Send as Custom Events is on, go to Data > Events & conversions and confirm the event, such as INITIAL_PURCHASE, arrived.
Tags in OneSignal now update automatically as users purchase, renew, or change their subscription.
Test with a new user and with an existing user who updates to the new version of your app.

Events RevenueCat sends

RevenueCat sends the following events. The event name is the value of the last_event_type tag and the name of the Custom Event. Not every store reports every event. See RevenueCat’s Events table for store support.
Do not remove access on SUBSCRIPTION_PAUSED. Remove access only on EXPIRATION.

Tags RevenueCat sends

For every event, RevenueCat adds or updates these Tags on the user. When you create the integration, an empty tag name uses the default name. To stop sending a tag, clear its name in the RevenueCat dashboard after you create the integration. If every tag name is blank, RevenueCat sends nothing to OneSignal.
active_subscription has no default name. RevenueCat sends it only after you enter a tag name for it in the RevenueCat dashboard.

subscription_status tag

When an event changes the user’s subscription status, RevenueCat updates subscription_status to one of these values. For example, the NON_RENEWING_PURCHASE example below does not include it. For customers with more than one active subscription, subscription_status reflects only the subscription with the most recent event.

Tag examples

These examples show the tag update RevenueCat sends to OneSignal for each event.

Custom Events RevenueCat sends

With Send as Custom Events on, RevenueCat sends every event in Events RevenueCat sends to OneSignal as a Custom Event, in addition to updating Tags. It is on by default for new integrations. Integrations set up before the option existed have it off until you turn it on. Each Custom Event:
  • Is named with the event name, such as TRIAL_STARTED or RENEWAL.
  • Goes to the same OneSignal user and app as the tag update.
  • Uses the time of the event as its timestamp, such as the purchase or expiration time.
  • Includes the subscription data as event properties, under the tag names you configured.
The event properties leave out app_user_id, last_event_type, last_event_at, and any tag with a blank name. If every tag name is blank, RevenueCat sends neither the tag update nor the Custom Event.
Use RevenueCat Custom Events to:
  • Start a Journey when a user triggers TRIAL_STARTED or BILLING_ISSUE.
  • Wait in a Journey until a user triggers TRIAL_CONVERTED, then send a fallback if they don’t.
  • Personalize Journey messages with event properties, such as {{ journey.first_event.properties.product_id }} when the event entered the user into the Journey. Property names match the tag names you configured in RevenueCat.
  • Segment users by the purchase events they triggered.
Custom Events require:

Custom Events

Trigger Journeys, personalize messages, and segment users with Custom Events.

FAQ

How do I know if the integration is working?

Search for the user’s OneSignal ID in Audience > Users & subscriptions and check for the Tags RevenueCat set. In RevenueCat, the Customer History shows whether each OneSignal integration event was delivered. To check Custom Events, go to Data > Events & conversions.

Why are RevenueCat events not reaching OneSignal?

The most common cause is a missing or outdated OneSignal ID in RevenueCat. Confirm $onesignalUserId is set on the user in RevenueCat, and that you call login before you send it. Also check that the purchase went to the right app: sandbox purchases, including TestFlight and Google Play license testers, go to the app in the Sandbox section.

Why are my sandbox purchases updating the wrong app?

RevenueCat sends sandbox purchases to the app in the Sandbox section and production purchases to the app in the Production section. Update the Sandbox section in the RevenueCat dashboard to change where sandbox purchases go.

Can I use RevenueCat Custom Events on the Free plan?

No. Custom Events require a paid OneSignal plan. On the Free plan, turn off Send as Custom Events in RevenueCat. Tag updates still work.

Does RevenueCat send revenue amounts to OneSignal?

No. RevenueCat does not send prices or revenue to OneSignal. It sends subscription data, such as the product, store, status, and dates.

How many tags can I set?

OneSignal limits how many Tags each user can have at once. The limit depends on your plan. See Pricing. To send fewer Tags, clear the names of the tags you don’t need in the RevenueCat dashboard.

Custom Events

Trigger Journeys, personalize messages, and segment users with events.

Tags

Store user properties and use them for segmentation and personalization.

Journey settings

Enter users into Journeys when they trigger a Custom Event.

Keys and IDs

Find your OneSignal App ID and App API key.