​
Overview

RevenueCat helps you track in-app purchases and subscription lifecycles across platforms. With OneSignal, you can use this data to send personalized messages based on a user’s subscription status. This integration updates user tags in OneSignal automatically with their latest subscription info.

​
Key benefits

With the RevenueCat–OneSignal integration, you can:
  • Send onboarding messages to users in a free trial or who just subscribed.
  • Re-engage churned users with surveys or discounts.
  • Send transactional messages for purchases, billing issues, or renewals.
With accurate subscription data in OneSignal, your campaigns will be smarter and more effective.

​
Requirements

​
Setup

​
Connect OneSignal to RevenueCat

  1. In your RevenueCat dashboard, navigate to your project settings and choose ‘OneSignal’ from the Integrations menu.
  2. Add your OneSignal App ID and OneSignal API key. See Keys and IDs for more information.
  3. Enter the tag names that RevenueCat should use, or choose the default tag names.

​
Pass RevenueCat the OneSignal ID

RevenueCat uses the OneSignal user ID (OneSignal ID) to update user tags in OneSignal based on their RevenueCat user details.
Setting the External ID in OneSignal is required for a stable identifier. If it changes mid-session, the OneSignal ID may also change, breaking the RevenueCat connection.
To pass the OneSignal ID to RevenueCat, you should:
1

Set the External ID in OneSignal

Set the External ID in OneSignal to your main user ID. This can be done with the SDK login method.
2

Get the OneSignal ID

We recommend using the user state observer method to get the OneSignal ID, but we also provide getter methods:
3

Pass the OneSignal ID to RevenueCat

Pass the OneSignal ID to RevenueCat.
  • RevenueCat property: $onesignalUserId
  • RevenueCat helper method: setOneSignalUserID() (recommended)

​
Send RevenueCat events to OneSignal

Users that have a mapped OneSignal ID to RevenueCat will have their tags updated automatically.

​
Testing the integration

1

Make a sandbox purchase

Simulate a new user installing your app, and go through your app flow to complete a sandbox purchase.
Make sure the OneSignal ID is set in RevenueCat.
2

Check that the required device data is collected

In RevenueCat, navigate to the Customer View for the test user that just made a purchase. Make sure that all of the required data is listed as attributes for the user.
3

Check that the OneSignal event delivered successfully

While still on the Customer View, click into the test purchase event in the Customer History and make sure that the OneSignal integration event exists and was delivered successfully.
4

Check that the OneSignal tags are updated

In OneSignal, navigate to Audience > Users and search for the OneSignal ID. You should see the tags that were updated by RevenueCat.
Integration complete! You should now see the tags in OneSignal update automatically as users make purchases or update their subscription status.

​
RevenueCat event tags

For every auto-renewing subscription event in RevenueCat, the following tags get added or updated on the user in OneSignal. By leaving the tag blank in the RevenueCat dashboard, you can choose to not send any value for specific tag(s).
TagDescription
app_user_idThe RevenueCat App User Id that triggered the event
period_typeThe latest period type for the purchase or renewal. Either: TRIAL (for free trials), INTRO (or introductory pricing), NORMAL (standard subscription)
purchased_atEpoch time in seconds of the latest subscription purchase or renewal
expiration_atEpoch time in seconds of the latest subscription expiration date
storeEither APP_STORE, PLAY_STORE, or STRIPE
environmentEither SANDBOX or PRODUCTION
last_event_typeThe latest event type from the user. Either: INITIAL_PURCHASE, TRIAL_STARTED, TRIAL_CONVERTED, TRIAL_CANCELLED, RENEWAL, CANCELLATION
product_idThe latest subscription product identifier that the user has purchased or renewed
entitlement_idsComma separated string of RevenueCat Entitlement identifiers that the user unlocked
active_subscriptionThe value will be set to true on any purchase/renewal event, and false on EXPIRATION
subscription_statusSee Subscription Status Attribute below
grace_period_expiration_atIf a billing issue occurs, we will send the date of the grace period expiration.
  • Auto-renewing subscriptions only
  • RevenueCat only updates data tags in OneSignal in response to auto-renewing subscription events.

​
RevenueCat event examples

Provided JSON examples show the tags sent to OneSignal based on RevenueCat Events. The event is saved as the last_event_type tag. 
{
    "app_id": "12345678-1234-1234-1234-123456789012",
    "tags": {
        "user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
        "period_type": "NORMAL",
        "purchased_at": 1600016247,
        "expiration_at": 1602608247,
        "store": "APP_STORE",
        "environment": "PRODUCTION",
        "last_event_type": "initial_purchase",
        "last_event_at": 1600016250,
        "product_id": "monthly_sub",
        "entitlement_ids": "Pro"
    }
}

​
subscription_status tag

Whenever RevenueCat sends an event to OneSignal, a subscription_status tag is added or updated with any applicable changes, using one of the following values:
StatusDescription
activeThe customer has an active, paid subscription which is set to renew at their next renewal date.
introThe customer has an active, paid subscription through a paid introductory offer.
cancelledThe customer has a paid subscription which is set to expire at their next renewal date.
grace_periodThe customer has a paid subscription which has entered a grace period after failing to renew successfully.
trialThe customer is in a trial period which is set to convert to paid at the end of their trial period.
cancelled_trialThe customer is in a trial period which is set to expire at the end of their trial period.
grace_period_trialThe customer was in a trial period and has now entered a grace period after failing to renew successfully.
expiredThe customer’s subscription has expired.
promotionalThe customer has access to an entitlement through a RevenueCat
expired_promotionalThe customer previously had access to an entitlement through a RevenueCat Granted Entitlement that has since expired.
pausedThe customer has a paid subscription which has been paused and is set to resume at some future date.
For customers with multiple active subscriptions, this attribute will represent the status of only the subscription for which the most recent event occurred.

​
FAQ

​
How do I know if the integration is working?

In OneSignal, navigate to Audience > Users and search for the OneSignal ID. You should see the tags that were updated by RevenueCat. You can also go to Audience > Segments and create a segment that filters for the tags you have set via RevenueCat.

​
How many tags can I set?

There is no limit to the amount of tags you can set in OneSignal, but there is a limit to how many tags each user can have at a given time. See our Pricing page for more information.