Superwall

Integrate in-app purchase events from RevenueCat with Superwall

👍

The Superwall integration is available to all users signed up after September '23, the legacy Grow and Pro plans, and Enterprise plans. If you're on a legacy Free or Starter plan and want to access this integration, migrate to our new pricing via your billing settings.

Superwall can be a helpful integration for optimizing pricing and understanding which paywalls are producing customers with the highest LTV. RevenueCat can automatically send billing, subscription, and revenue metrics to Superwall, a paywall SDK that lets you remotely update every aspect of your paywall.

With our Superwall integration, you can:

  • Create paywalls on-the-fly without shipping app updates
  • Determine which paywalls have high trial conversion rates
  • Find which product & paywall combinations have the highest LTVs
  • Offer discounts to users who churn

Events

The Superwall integration tracks the following events:

Event TypeDefault Event NameDescriptionApp StorePlay StoreAmazonStripePromo
Initial PurchaseINITIAL_PURCHASEA new subscription has been purchased.✅✅✅✅❌
RenewalRENEWALAn existing subscription has been renewed or a lapsed user has resubscribed.✅✅✅✅❌
CancellationCANCELLATIONA subscription or non-renewing purchase has been cancelled. See cancellation reasons for more details.✅✅✅✅✅
UncancellationUNCANCELLATIONA non-expired cancelled subscription has been re-enabled.✅✅✅❌❌
Non Subscription PurchaseNON_RENEWING_PURCHASEA customer has made a purchase that will not auto-renew.✅✅✅✅✅
Subscription PausedSUBSCRIPTION_PAUSEDA subscription has been paused.❌✅❌❌❌
ExpirationEXPIRATIONA subscription has expired and access should be removed.

If you have Platform Server Notifications configured, this event will occur as soon as we are notified (within seconds to minutes) of the expiration.

If you do not have notifications configured, delays may be approximately 1 hour.
✅✅✅✅✅
Billing IssueBILLING_ISSUEThere has been a problem trying to charge the subscriber. This does not mean the subscription has expired.

Can be safely ignored if listening to CANCELLATION event + cancel_reason=BILLING_ERROR.
✅✅✅✅❌
Product ChangePRODUCT_CHANGEA subscriber has changed the product of their subscription.

This does not mean the new subscription is in effect immediately. See Managing Subscriptions for more details on updates, downgrades, and crossgrades.
✅✅❌✅❌
Transfer TRANSFERA transfer of transactions and entitlements was initiated between one App User ID(s) to another.✅✅✅✅❌

Setup

1. Set Superwall User Identity

In order to associate RevenueCat subscription data with Superwall paywall events, the RevenueCat app user ID must match the Superwall app user ID. You can read more about how Superwall handles user ID’s in their documentation here. You can set up a custom app user ID in RevenueCat by following the instructions in our Identifying Users documentation.

2. Send RevenueCat events to Superwall

After you've set up the Purchases SDK and Superwall SDK to have the same user identity, you can "turn on" the integration from the RevenueCat dashboard.

  1. Navigate to your project in the RevenueCat dashboard and find the Integrations card in the left menu. Select + New

  1. Choose Superwall from the Integrations menu
  2. Add your Superwall Token (Superwall settings > Integrations)

Remember to select Add Integration

Testing the Superwall integration

Make a sandbox purchase with a new user

Simulate a new user installing your app, and go through your app flow to complete the sandbox purchase.

Check that the Superwall event delivered successfully

While still on the Customer View, select the purchase event in the Customer History page and make sure that the Superwall integration event exists and was delivered successfully.

Check Superwall dashboard for the delivered event

Navigate to your Superwall dashboard > Users and search for the created app user ID. You will see events RevenueCat has dispatched to the Superwall under 'Recent Events'.

Sample Events

Below are sample JSONs that are delivered to Superwall for each event type.

{
    "event": {
        "event_timestamp_ms": 1641980452341,
        "product_id": "annual",
        "period_type": "NORMAL",
        "purchased_at_ms": 1641980447000,
        "expiration_at_ms": 1642585247000,
        "environment": "PRODUCTION",
        "entitlement_ids": [
            "premium"
        ],
        "presented_offering_id": null,
        "transaction_id": "123456789012345",
        "original_transaction_id": "123456789012345",
        "is_family_share": false,
        "country_code": "US",
        "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
        "aliases": [
            "12abc345d67e890fgh12j3lm456n7890"
        ],
        "original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
        "currency": "USD",
        "price": 89.99,
        "price_in_purchased_currency": 89.99,
        "subscriber_attributes": {
            "$ip": {
                "value": "123.45.67.89",
                "updated_at_ms": 1641980373773
            },
            "$idfa": {
                "value": "00000000-0000-0000-0000-000000000000",
                "updated_at_ms": 1641980373773
            },
            "$idfv": {
                "value": "12345A6B-C789-0D1E-FG23-456H6I7J890K",
                "updated_at_ms": 1641980373773
            },
            "$appsflyerId": {
                "value": "1234567890123-1234567890123456789",
                "updated_at_ms": 1641980373775
            }
        },
        "store": "APP_STORE",
        "takehome_percentage": 0.7,
        "offer_code": null,
        "type": "INITIAL_PURCHASE",
        "id": "12345678-1234-1234-1234-123456789012",
        "app_id": "1234567890"
    },
    "api_version": "1.0"
}
{
    "event": {
        "event_timestamp_ms": 1641990066553,
        "product_id": "weekly",
        "period_type": "NORMAL",
        "purchased_at_ms": 1642018648000,
        "expiration_at_ms": 1642623448000,
        "environment": "PRODUCTION",
        "entitlement_ids": [
            "premium"
        ],
        "presented_offering_id": null,
        "transaction_id": "123456789012345",
        "original_transaction_id": "123456789012345",
        "is_family_share": false,
        "country_code": "US",
        "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
        "aliases": [
            "12abc345d67e890fgh12j3lm456n7890"
        ],
        "original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
        "currency": "USD",
        "is_trial_conversion": false,
        "price": 4.99,
        "price_in_purchased_currency": 4.99,
        "subscriber_attributes": {
            "$ip": {
                "value": "123.45.67.89",
                "updated_at_ms": 1635966996059
            },
            "$idfa": {
                "value": "00000000-0000-0000-0000-000000000000",
                "updated_at_ms": 1635966996058
            },
            "$idfv": {
                "value": "12345A6B-C789-0D1E-FG23-456H6I7J890K",
                "updated_at_ms": 1634600054627
            },
            "$email": {
                "value": "[email protected]",
                "updated_at_ms": 1635967259599
            },
            "$appsflyerId": {
                "value": "1234567890123-1234567890123456789",
                "updated_at_ms": 1634600054630
            },
            "$displayName": {
                "value": "FirstLast",   
                "updated_at_ms": 1635967185821
            }
        },
        "store": "APP_STORE",
        "takehome_percentage": 0.7,
        "offer_code": null,
        "type": "RENEWAL",
        "id": "12345678-1234-1234-1234-123456789012",
        "app_id": "1234567890"
    },
    "api_version": "1.0"
}
{
    "event": {
        "event_timestamp_ms": 1641979460185,
        "product_id": "annual",
        "period_type": "NORMAL",
        "purchased_at_ms": 1641489607000,
        "expiration_at_ms": 1673025607000,
        "environment": "PRODUCTION",
        "entitlement_ids": [
            "premium"
        ],
        "presented_offering_id": null,
        "transaction_id": "123456789012345",
        "original_transaction_id": "123456789012345",
        "is_family_share": false,
        "country_code": "US",
        "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
        "aliases": [
            "12abc345d67e890fgh12j3lm456n7890"
        ],
        "original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
        "cancel_reason": "UNSUBSCRIBE",
        "currency": "USD",
        "price": 0.0,
        "price_in_purchased_currency": 0.0,
        "subscriber_attributes": {
            "$ip": {
                "value": "123.45.67.89",
                "updated_at_ms": 1640922085884
            },
            "$idfa": {
                "value": "00000000-0000-0000-0000-000000000000",
                "updated_at_ms": 1640922085883
            },
            "$idfv": {
                "value": "12345A6B-C789-0D1E-FG23-456H6I7J890K",
                "updated_at_ms": 1640884773572
            },
            "$email": {
                "value": "[email protected]",
                "updated_at_ms": 1640884952087
            },
            "$appsflyerId": {
                "value": "1234567890123-1234567890123456789",
                "updated_at_ms": 1640884773577
            },
            "$displayName": {
                "value": "FirstLast",   
                "updated_at_ms": 1640884932761
            }
        },
        "store": "APP_STORE",
        "takehome_percentage": 0.7,
        "offer_code": null,
        "type": "CANCELLATION",
        "id": "12345678-1234-1234-1234-123456789012",
        "app_id": "1234567890"
    },
    "api_version": "1.0"
}
{
    "event": {
        "event_timestamp_ms": 1663976681591,
        "product_id": "annual",
        "period_type": "NORMAL",
        "purchased_at_ms": 1642861650000,
        "expiration_at_ms": 1674397650000,
        "environment": "PRODUCTION",
        "entitlement_ids": [
            "premium"
        ],
        "presented_offering_id": "standard",
        "transaction_id": "123456789012345",
        "original_transaction_id": "123456789012345",
        "is_family_share": false,
        "country_code": "US",
        "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
        "aliases": [
            "12abc345d67e890fgh12j3lm456n7890"
        ],
        "original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
        "currency": "USD",
        "price": 0.0,
        "price_in_purchased_currency": 0.0,
        "subscriber_attributes": {
            "$ip": {
                "value": "123.45.67.89",
                "updated_at_ms": 1642861599292
            },
            "$idfa": {
                "value": "00000000-0000-0000-0000-000000000000",
                "updated_at_ms": 1642861599292
            },
            "$idfv": {
                "value": "12345A6B-C789-0D1E-FG23-456H6I7J890K",
                "updated_at_ms": 1642861529624
            },
            "$amplitudeDeviceId": {
                "value": "12345A6B-C789-0D1E-FG23-456H6I7J890K",
                "updated_at_ms": 1662591626817
            }
        },
        "store": "APP_STORE",
        "takehome_percentage": 0.7,
        "offer_code": null,
        "tax_percentage": 0.0,
        "commission_percentage": 0.3,
        "type": "UNCANCELLATION",
        "id": "12345678-1234-1234-1234-123456789012",
        "app_id": "1234567890"
    },
    "api_version": "1.0"
}
{
    "event": {
        "event_timestamp_ms": 1642005085499,
        "product_id": "400_tokens",
        "period_type": "NORMAL",
        "purchased_at_ms": 1642005085444,
        "expiration_at_ms": 1644683485444,
        "environment": "PRODUCTION",
        "entitlement_ids": [
            "premium"
        ],
        "presented_offering_id": null,
        "transaction_id": "123456789012345",
        "original_transaction_id": "123456789012345",
        "is_family_share": null,
        "country_code": "US",
        "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
        "aliases": [
            "12abc345d67e890fgh12j3lm456n7890"
        ],
        "original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
        "currency": "USD",
        "price": 3.99,
        "price_in_purchased_currency": 3.99,
        "subscriber_attributes": {
            "$ip": {
                "value": "123.45.67.89",
                "updated_at_ms": 1605515259156
            },
            "$idfa": {
                "value": "00000000-0000-0000-0000-000000000000",
                "updated_at_ms": 1605515259155
            },
            "$idfv": {
                "value": "12345A6B-C789-0D1E-FG23-456H6I7J890K",
                "updated_at_ms": 1605515259156
            },
            "$email": {
                "value": "[email protected]",
                "updated_at_ms": 1608329355624
            },
            "$appsflyerId": {
                "value": "1234567890123-1234567890123456789",
                "updated_at_ms": 1578134994616
            },
            "$displayName": {
                "value": "FirstLast",   
                "updated_at_ms": 1608329355625
            }
        },
        "store": "APP_STORE",
        "takehome_percentage": 1.0,
        "offer_code": null,
        "type": "NON_RENEWING_PURCHASE",
        "id": "12345678-1234-1234-1234-123456789012",
    },
    "api_version": "1.0"
}
{
    "event": {
        "event_timestamp_ms": 1663972580977,
        "product_id": "monthly",
        "period_type": "NORMAL",
        "purchased_at_ms": 1663950641060,
        "expiration_at_ms": 1666549841060,
        "environment": "PRODUCTION",
        "entitlement_ids": null,
        "presented_offering_id": null,
        "transaction_id": "GPA.1234-5678-9012-34567",
        "original_transaction_id": "GPA.1234-5678-9012-34567",
        "is_family_share": false,
        "country_code": null,
        "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
        "aliases": [
            "12abc345d67e890fgh12j3lm456n7890"
        ],
        "original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
        "auto_resume_at_ms": 1674491441060,
        "currency": "USD",
        "price": 0.0,
        "price_in_purchased_currency": 0.0,
        "subscriber_attributes": {},
        "store": "PLAY_STORE",
        "takehome_percentage": 0.85,
        "offer_code": null,
        "tax_percentage": 0.0,
        "commission_percentage": 0.15,
        "type": "SUBSCRIPTION_PAUSED",
        "id": "12345678-1234-1234-1234-123456789012",
        "app_id": "1234567890"
    },
    "api_version": "1.0"
}
{
    "event": {
        "event_timestamp_ms": 1641979680052,
        "product_id": "annual",
        "period_type": "NORMAL",
        "purchased_at_ms": 1610443458000,
        "expiration_at_ms": 1641979458000,
        "environment": "PRODUCTION",
        "entitlement_ids": [
            "premium"
        ],
        "presented_offering_id": null,
        "transaction_id": "123456789012345",
        "original_transaction_id": "123456789012345",
        "is_family_share": false,
        "country_code": "AU",
        "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
        "aliases": [
            "12abc345d67e890fgh12j3lm456n7890"
        ],
        "original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
        "expiration_reason": "UNSUBSCRIBE",
        "currency": "AUD",
        "price": 0.0,
        "price_in_purchased_currency": 0.0,
        "subscriber_attributes": {
            "$ip": {
                "value": "123.45.67.89",
                "updated_at_ms": 1625546407475
            },
            "$idfa": {
                "value": "00000000-0000-0000-0000-000000000000",
                "updated_at_ms": 1625546407473
            },
            "$idfv": {
                "value": "12345A6B-C789-0D1E-FG23-456H6I7J890K",
                "updated_at_ms": 1625466331505
            },
            "$email": {
                "value": "[email protected]",
                "updated_at_ms": 1625466352128
            },
            "$appsflyerId": {
                "value": "1234567890123-1234567890123456789",
                "updated_at_ms": 1625466331510
            },
            "$displayName": {
                "value": "FirstLast",   
                "updated_at_ms": 1625466352133
            }
        },
        "store": "APP_STORE",
        "takehome_percentage": 0.85,
        "offer_code": null,
        "type": "EXPIRATION",
        "id": "12345678-1234-1234-1234-123456789012",
        "app_id": "1234567890"
    },
    "api_version": "1.0"
}
{
    "event": {
        "event_timestamp_ms": 1641989467593,
        "product_id": "monthly",
        "period_type": "NORMAL",
        "purchased_at_ms": 1641985292000,
        "expiration_at_ms": 1673521292000,
        "environment": "PRODUCTION",
        "entitlement_ids": [
            "premium"
        ],
        "presented_offering_id": null,
        "transaction_id": "123456789012345",
        "original_transaction_id": "123456789012345",
        "is_family_share": false,
        "country_code": "ZA",
        "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
        "aliases": [
            "12abc345d67e890fgh12j3lm456n7890"
        ],
        "original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
        "grace_period_expiration_at_ms": null,
        "currency": "USD",
        "price": 0.0,
        "price_in_purchased_currency": 0.0,
        "subscriber_attributes": {
            "$ip": {
                "value": "123.45.67.89",
                "updated_at_ms": 1641380990137
            },
            "$idfa": {
                "value": "00000000-0000-0000-0000-000000000000",
                "updated_at_ms": 1641380990136
            },
            "$idfv": {
                "value": "12345A6B-C789-0D1E-FG23-456H6I7J890K",
                "updated_at_ms": 1641380990136
            },
            "$email": {
                "value": "[email protected]",
                "updated_at_ms": 1641380601324
            },
            "$appsflyerId": {
                "value": "1234567890123-1234567890123456789",
                "updated_at_ms": 1641380990138
            },
            "$displayName": {
                "value": "FirstLast",   
                "updated_at_ms": 1641449423479
            }
        },
        "store": "APP_STORE",
        "takehome_percentage": 1.0,
        "offer_code": null,
        "type": "BILLING_ISSUE",
        "id": "12345678-1234-1234-1234-123456789012",
        "app_id": "1234567890"
    },
    "api_version": "1.0"
}
{
    "event": {
        "event_timestamp_ms": 1642108701236,
        "product_id": "monthly",
        "period_type": "NORMAL",
        "purchased_at_ms": 1639087828000,
        "expiration_at_ms": 1641766228000,
        "environment": "PRODUCTION",
        "entitlement_ids": [
            "premium"
        ],
        "presented_offering_id": null,
        "transaction_id": "123456789012345",
        "original_transaction_id": "123456789012345",
        "is_family_share": false,
        "country_code": "CA",
        "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
        "aliases": [
            "12abc345d67e890fgh12j3lm456n7890"
        ],
        "original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c",
        "new_product_id": "annual",
        "currency": "CAD",
        "price": 0.0,
        "price_in_purchased_currency": 0.0,
        "subscriber_attributes": {
            "$ip": {
                "value": "123.45.67.89",
                "updated_at_ms": 1607426876996
            },
            "$idfa": {
                "value": "00000000-0000-0000-0000-000000000000",
                "updated_at_ms": 1607426876996
            },
            "$idfv": {
                "value": "12345A6B-C789-0D1E-FG23-456H6I7J890K",
                "updated_at_ms": 1607426876996
            },
            "$email": {
                "value": "[email protected]",
                "updated_at_ms": 1608040666659
            },
            "$appsflyerId": {
                "value": "1234567890123-1234567890123456789",
                "updated_at_ms": 1582818527279
            },
            "$displayName": {
                "value": "FirstLast",   
                "updated_at_ms": 1608040666660
            }
        },
        "store": "APP_STORE",
        "takehome_percentage": 0.7,
        "offer_code": null,
        "type": "PRODUCT_CHANGE",
        "id": "12345678-1234-1234-1234-123456789012",
        "app_id": "1234567890"
    },
    "api_version": "1.0"
}

👍

You've done it!

You should start seeing subscription data from RevenueCat appear in Superwall.