--- id: "integrations/third-party-integrations/iterable" title: "Iterable" description: "Iterable can be a helpful integration tool in understanding what stage a customer is in and reacting accordingly. Iterable is a cross-channel platform that powers unified customer experiences and empowers marketers to create, optimize and measure every interaction taking place throughout the customer journey. With Iterable, brands create individualized marketing touch points that earn engagement, solidify trust and galvanize loyal consumer-brand relationships." permalink: "/docs/integrations/third-party-integrations/iterable" slug: "iterable" version: "current" original_source: "docs/integrations/third-party-integrations/iterable.mdx" --- > **AI agents:** This is the Markdown version of a RevenueCat documentation page. For the complete documentation index, see [llms.txt](https://www.revenuecat.com/docs/llms.txt). Iterable can be a helpful integration tool in understanding what stage a customer is in and reacting accordingly. Iterable is a cross-channel platform that powers unified customer experiences and empowers marketers to create, optimize and measure every interaction taking place throughout the customer journey. With Iterable, brands create individualized marketing touch points that earn engagement, solidify trust and galvanize loyal consumer-brand relationships. With our Iterable integration, you can: - Create an event to track unsubscribes that automatically triggers an email to users who cancel. - Start a campaign to send users who have been with you for over a certain length of time a discount code for being a loyal customer. With accurate and up-to date subscription data in Iterable, you’ll be set to turbocharge your users’ engagement ⚡️ ### Integration at a Glance | Includes Revenue | Supports Negative Revenue | Sends Sandbox Events | Includes Customer Attributes | Sends Transfer Events | Optional Event Types | | :--------------: | :-----------------------: | :------------------: | :--------------------------: | :-------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------: | | ✅ | ✅ | Requires API Key | ✅ | ❌ | `non_subscription_purchase_event` `uncancellation_event` `subscription_paused_event` `expiration_event` `billing_issue_event` `product_change_event` | ## Events The Iterable integration tracks the following events: | RevenueCat Event Type | Iterable Event Type | Default Event Name | Description | App Store | Play Store | Amazon | Stripe | Promo | | ------------------------- | ------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ---------- | ------ | ------ | ----- | | Initial Purchase | Purchase | rc\_initial\_purchase\_event | A new subscription has been purchased. | ✅ | ✅ | ✅ | ✅ | ❌ | | Trial Started | Purchase | rc\_trial\_started\_event | The start of an auto-renewing subscription product free trial. | ✅ | ✅ | ✅ | ✅ | ❌ | | Trial Converted | Purchase | rc\_trial\_converted\_event | When an auto-renewing subscription product converts from a free trial to normal paid period. | ✅ | ✅ | ✅ | ✅ | ❌ | | Trial Cancelled | Custom | rc\_trial\_cancelled\_event | When a user turns off renewals for an auto-renewing subscription product during a free trial period. | ✅ | ✅ | ✅ | ✅ | ❌ | | Renewal | Purchase | rc\_renewal\_event | An existing subscription has been renewed or a lapsed user has resubscribed. | ✅ | ✅ | ✅ | ✅ | ❌ | | Cancellation | Custom | rc\_cancellation\_event | A subscription or non-renewing purchase has been cancelled. See [cancellation reasons](https://www.revenuecat.com/docs/integrations/webhooks/event-types-and-fields#cancellation-and-expiration-reasons) for more details. | ✅ | ✅ | ✅ | ✅ | ✅ | | Uncancellation | Custom | rc\_uncancellation\_event | A non-expired cancelled subscription has been re-enabled. | ✅ | ✅ | ✅ | ❌ | ❌ | | Non Subscription Purchase | Purchase | rc\_non\_subscription\_purchase\_event | A customer has made a purchase that will not auto-renew. | ✅ | ✅ | ✅ | ✅ | ✅ | | Subscription Paused | Custom | rc\_subscription\_paused\_event | A subscription has been paused. | ❌ | ✅ | ❌ | ❌ | ❌ | | Expiration | Custom | rc\_expiration\_event | A subscription has expired and access should be removed. If you have [Platform Server Notifications](https://www.revenuecat.com/docs/platform-resources/server-notifications) configured, this event will occur as soon as we are notified (within seconds to minutes) of the expiration. | ✅ | ✅ | ✅ | ✅ | ✅ | | Billing Issue | Custom | rc\_billing\_issue\_event | There 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 Change | Custom | rc\_product\_change\_event | A subscriber has changed the product of their subscription. This does not mean the new subscription is in effect immediately. See [Managing Subscriptions](https://www.revenuecat.com/docs/subscription-guidance/managing-subscriptions) for more details on updates, downgrades, and crossgrades. | ✅ | ✅ | ❌ | ✅ | ❌ | For events that have revenue, such as trial conversions and renewals, RevenueCat will automatically record this amount along with the event in Iterable. Bear in mind that revenue will always be reported in USD. If it's been made with a different currency, we'll automatically convert it to USD. You can find the currency of the original transaction in the `currency` field of the event. ## Setup ### 1. Set Iterable User Identity In order to associate RevenueCat data with the Iterable User Profile, either the RevenueCat `$email` or `$iterableUserId` [Attribute](https://www.revenuecat.com/docs/customers/customer-attributes) should be set in RevenueCat. The preferred method is to send the `$email` attribute. If neither of these fields exist, RevenueCat will fallback to the RevenueCat app user ID. You can read more about Iterable user profiles in Iterable's [Identifying the User](https://support.iterable.com/hc/en-us/articles/360035402531-Identifying-the-User-) documentation. :::info\[`$iterableUserId` character limit] The `$iterableUserId` can be up to 52 characters long. ::: ### (optional) Set Iterable Campaign ID and/or Template ID To attribute an event to an Iterable Campaign ID and/or Template ID, set the `$iterableCampaignId` and/or `$iterableTemplateId` attributes through the RevenueCat SDK or [REST API](https://docs.revenuecat.com/reference/update-subscriber-attributes). ```swift // Configure Purchases Purchases.configure(this, "public_sdk_key", "my_app_user_id") // Initialize Iterable IterableAPI.initialize(apiKey: "", launchOptions: launchOptions, config: config) // Setting Iterable email or userId IterableAPI.email = "user@example.com" IterableAPI.userId = "user123" // Set $email or $iterableUserId, (optional) $iterableCampaignId, $iterableTemplateId Purchases.shared.attribution.setAttributes(["$email": IterableAPI.email, "$iterableUserId": IterableAPI.userId, "$iterableCampaignId": "123", "$iterableTemplateId": "123"]) ``` ```objectivec // Configure Purchases [RCPurchases configureWithAPIKey:@"public_sdk_key"]; // Initialize Iterable [IterableAPI initializeWithApiKey:@"" launchOptions:launchOptions config:config] // Setting Iterable email or userId IterableAPI.email = @"user@example.com"; IterableAPI.userId = @"user123"; // Set $email or $iterableUserId, (optional) $iterableCampaignId, $iterableTemplateId [[RCPurchases sharedPurchases] setAttributes:@{ @"$email": IterableAPI.email, @"iterableUserId": IterableAPI.userId , @"$iterableCampaignId": @"123", @"$iterableTemplateId": @"123" }]; ``` ```java // Configure Purchases Purchases.configure(new PurchasesConfiguration.Builder(this, "public_google_sdk_key").build()); // Initialize Iterable IterableApi.initialize(context, "", config); // Setting Iterable email or userId IterableApi.getInstance().setEmail("user@example.com"); IterableApi.getInstance().setUserId("user123"); // Set $email or $iterableUserId, (optional) $iterableCampaignId, $iterableTemplateId Map attributes = new HashMap(); attributes.put("$email", IterableApi.getInstance().getEmail()); attributes.put("$iterableUserId", IterableApi.getInstance().getUserId()); attributes.put("$iterableCampaignId", "123"); attributes.put("$iterableTemplateId", "123"); Purchases.getSharedInstance().setAttributes(attributes); ``` **React Native** ```jsx // Configure Purchases if (Platform.OS === 'ios') { await Purchases.configure({apiKey: }); } else if (Platform.OS === 'android') { await Purchases.configure({apiKey: }); // OR: if building for Amazon, be sure to follow the installation instructions then: await Purchases.configure({apiKey: , useAmazon: true }); } // Initialize Iterable Iterable.initialize(, config); // Setting Iterable email or userId Iterable.setEmail("user@example.com"); Iterable.setUserId("user123"); // Set $email or $iterableUserId, (optional) $iterableCampaignId, $iterableTemplateId Iterable.getEmail().then(email => { console.log("Current email: " + email); Purchases.setAttributes({ "$email" : email }); }); Iterable.getUserId().then(userId => { console.log("Current userId: " + userId); Purchases.setAttributes({ "$iterableUserId" : userId }); }); Purchases.setAttributes({ "$iterableCampaignId" : "123", "$iterableTemplateId" : "123" }); ``` ```curl curl --request POST \ --url https://api.revenuecat.com/v1/subscribers/app_user_id/attributes \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data \ '{ "attributes" : { "$iterableCampaignId": { "value": "123" }, "$iterableTemplateId": { "value": "123" } } }' ``` ### 2. Send RevenueCat Events to Iterable After you've set up the Purchase SDK and Iterable SDK to have the same user identity, you can "turn on" the integration and configure the event names from the RevenueCat dashboard. 1. Navigate to your project settings in the RevenueCat dashboard and choose 'Iterable' from the Integrations menu ![Integration setup](https://www.revenuecat.com/docs_images/integrations/setup-integrations.png) 2. Add your Iterable [Server-side API key](https://support.iterable.com/hc/en-us/articles/360043464871-API-Keys-#creating-api-keys) to the **API key** field in RevenueCat 3. Enter the event names that RevenueCat will send or choose the default event names 4. Select whether you want sales reported as gross revenue (before app store commission), or after store commission and/or estimated taxes. :::info\[Iterable sandbox environment] Iterable recommends having a production and sandbox project to separate live and testing environments. You can input both keys in the RevenueCat Iterable settings page. ::: ## Testing the Iterable 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](https://www.revenuecat.com/docs/test-and-launch/sandbox). ### Check that the Iterable event delivered successfully While still on the Customer View, select the purchase event in the [Customer History](https://www.revenuecat.com/docs/dashboard-and-metrics/customer-profile) page and make sure that the Iterable integration event exists and was delivered successfully. ![](https://www.revenuecat.com/docs_images/integrations/third-party-integrations/iterable/successful-event.png) ### Check Iterable dashboard for the delivered event Navigate to your Iterable dashboard > Insights > Logs. To find Purchase events navigate to 'Purchases' and to find Custom events navigate to 'Events'. You will see events RevenueCat has dispatched to the Iterable under 'Purchase Log' and 'Events log' respectively. ![](https://www.revenuecat.com/docs_images/integrations/third-party-integrations/iterable/iterable-purchase-log.png) ![](https://www.revenuecat.com/docs_images/integrations/third-party-integrations/iterable/iterable-events-log.png) ## Sample Events Below are sample JSONs that are delivered to Iterable for events. **Initial Purchase** ```json { "id": "12345678-1234-1234-1234-123456789012", "total": 29.99, "user": { "userId": "$RCAnonymousID:87c6049c58069238dce29853916d624c", "preferUserId": true, "dataFields": { "subscriber_attributes": {}, "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c", "original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c" } }, "items": [ { "id": "premium_freetrial", "name": "rc_initial_purchase_event", "price": 29.99, "quantity": 1, "dataFields": { "country_code": "US", "currency": "USD", "entitlement_ids": [ "premium" ], "expiration_at_ms": 1683233732021, "environment": "PRODUCTION", "is_family_share": false, "offer_code": null, "period_type": "NORMAL", "presented_offering_id": null, "store": "PLAY_STORE", "takehome_percentage": 0.85, "original_transaction_id": "GPA.1234-5678-9012-34567" } } ], "createdAt": 1651691577776 } ``` **Trial Started** ```json { "id": "12345678-1234-1234-1234-123456789012", "total": 0, "user": { "userId": "$RCAnonymousID:87c6049c58069238dce29853916d624c", "preferUserId": true, "dataFields": { "subscriber_attributes": {}, "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c", "original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c" } }, "items": [ { "id": "annual_sub_1week_trial", "name": "rc_trial_started_event", "price": 0, "quantity": 1, "dataFields": { "country_code": "US", "currency": "USD", "entitlement_ids": null, "expiration_at_ms": 1644623383000, "environment": "SANDBOX", "is_family_share": false, "offer_code": null, "period_type": "TRIAL", "presented_offering_id": "default", "store": "APP_STORE", "takehome_percentage": 0.7, "original_transaction_id": "123456789012345" } } ], "createdAt": 1644623203000 } ``` **Trial Converted** ```json { "id": "12345678-1234-1234-1234-123456789012", "total": 29.99, "user": { "userId": "$RCAnonymousID:87c6049c58069238dce29853916d624c", "preferUserId": true, "dataFields": { "subscriber_attributes": {}, "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c", "original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c" } }, "items": [ { "id": "annual_sub", "name": "rc_trial_converted_event", "price": 29.99, "quantity": 1, "dataFields": { "country_code": "US", "currency": "USD", "entitlement_ids": null, "expiration_at_ms": 1644626983000, "environment": "SANDBOX", "is_family_share": false, "offer_code": null, "period_type": "NORMAL", "presented_offering_id": "default", "store": "APP_STORE", "takehome_percentage": 0.7, "original_transaction_id": "123456789012345" } } ], "createdAt": 1644623383000 } ``` **Trial Cancelled** ```json { "createdAt": 1663964010781, "dataFields": { "app_id": "app1234567890", "event_properties": { "cancel_reason": "BILLING_ERROR", "environment": "PRODUCTION", "expiration_at_ms": 1664050410466, "original_transaction_id": "GPA.1234-5678-9012-34567", "period_type": "TRIAL", "product_id": "annual_sub_1week_trial", "store": "PLAY_STORE", "transaction_id": "GPA.1234-5678-9012-34567", } }, "email": null, "eventName": "rc_trial_cancelled_event", "id": "12345678-1234-1234-1234-123456789012", "userId": "$RCAnonymousID:87c6049c58069238dce29853916d624c", } ``` **Renewal** ```json { "id": "12345678-1234-1234-1234-123456789012", "total": 29.99, "user": { "userId": "$RCAnonymousID:87c6049c58069238dce29853916d624c", "preferUserId": true, "dataFields": { "subscriber_attributes": { "$email": { "value": "first_last@gmail.com", "updated_at_ms": 1644624942354 }, "$iterableCampaignId": { "value": "01234", "updated_at_ms": 1644634297590 }, "$iterableTemplateId": { "value": "5678", "updated_at_ms": 1644634301306 } }, "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c", "original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c" }, "email": "first_last@gmail.com" }, "items": [ { "id": "annual_sub", "name": "rc_renewal_event", "price": 29.99, "quantity": 1, "dataFields": { "country_code": "US", "currency": "USD", "entitlement_ids": null, "expiration_at_ms": 1644648719000, "environment": "SANDBOX", "is_family_share": false, "offer_code": null, "period_type": "NORMAL", "presented_offering_id": "default", "store": "APP_STORE", "takehome_percentage": 0.7, "original_transaction_id": "123456789012345" } } ], "createdAt": 1644645119000, "campaignId": "01234", "templateId": "5678" } ``` **Cancellation** ```json { "createdAt": 1663963037855, "dataFields": { "app_id": "app1234567890", "event_properties": { "cancel_reason": "UNSUBSCRIBE", "environment": "PRODUCTION", "expiration_at_ms": 1666381224082, "original_transaction_id": "GPA.1234-5678-9012-34567", "period_type": "NORMAL", "product_id": "annual_sub", "store": "PLAY_STORE", "transaction_id": "GPA.1234-5678-9012-34567", } }, "email": null, "eventName": "rc_cancellation_event", "id": "12345678-1234-1234-1234-123456789012", "userId": "$RCAnonymousID:87c6049c58069238dce29853916d624c", } ``` **Uncancellation** ```json { "id": "12345678-1234-1234-1234-123456789012", "eventName": "rc_uncancellation_event", "userId": "$RCAnonymousID:87c6049c58069238dce29853916d624c", "dataFields": { "event_properties": { "environment": "SANDBOX", "expiration_at_ms": 1646073127000, "original_transaction_id": "123456789012345", "period_type": "NORMAL", "product_id": "annual_sub", "store": "APP_STORE", "transaction_id": "123456789012345", "email": "first_last@gmail.com" } }, "createdAt": 1646069715718, "campaignId": "0123", "templateId": "4564" } ``` **Non Subscription Purchase** ```json { "id": "12345678-1234-1234-1234-123456789012", "total": 4.99, "user": { "userId": "$RCAnonymousID:87c6049c58069238dce29853916d624c", "preferUserId": true, "dataFields": { "subscriber_attributes": { "$email": { "value": "first_last@gmail.com", "updated_at_ms": 1659292070233 }, "$iterableUserId": { "value": "12345A6B-C789-0D1E-FG23-456H6I7J890K", "updated_at_ms": 1659292070233 }, }, "app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c", "original_app_user_id": "$RCAnonymousID:87c6049c58069238dce29853916d624c" }, "email": "first_last@gmail.com" }, "items": [ { "id": "100_tokens", "name": "rc_non_subscription_purchase_event", "price": 4.99, "quantity": 1, "dataFields": { "country_code": null, "currency": "USD", "entitlement_ids": [ "pro" ], "expiration_at_ms": 1659897848466, "environment": "PRODUCTION", "is_family_share": null, "offer_code": null, "period_type": "NORMAL", "presented_offering_id": null, "store": "APP_STORE", "takehome_percentage": 1.0, "original_transaction_id": "123456789012345" } } ], "createdAt": 1659293048466 } ``` **Subscription Paused** ```json { "id": "12345678-1234-1234-1234-123456789012", "email": null, "eventName": "rc_subscription_paused_event", "userId": "$RCAnonymousID:87c6049c58069238dce29853916d624c", "dataFields": { "event_properties": { "environment": "PRODUCTION", "expiration_at_ms": 1654366688509, "original_transaction_id": "GPA.1234-5678-9012-34567", "period_type": "NORMAL", "product_id": "monthly_sub_trial", "store": "PLAY_STORE", "transaction_id": "GPA.1234-5678-9012-34567", "auto_resumes_at": 1656951488509 } }, "createdAt": 1651679019206 } ``` **Expiration** ```json { "createdAt": 1663963579936, "dataFields": { "app_id": "app1234567890", "event_properties": { "environment": "PRODUCTION", "expiration_at_ms": 1663963579936, "expiration_reason": "UNSUBSCRIBE", "original_transaction_id": "GPA.1234-5678-9012-34567", "period_type": "NORMAL", "product_id": "weekly_sub", "store": "PLAY_STORE", "transaction_id": "GPA.1234-5678-9012-34567", } }, "email": null, "eventName": "rc_expiration_event", "id": "12345678-1234-1234-1234-123456789012", "userId": "$RCAnonymousID:87c6049c58069238dce29853916d624c", } ``` **Billing Issues** ```json { "createdAt": 1663964010781, "dataFields": { "app_id": "app1234567890", "event_properties": { "environment": "PRODUCTION", "expiration_at_ms": 1664050410466, "grace_period_expires_at": 1664580986800, "original_transaction_id": "GPA.1234-5678-9012-34567", "period_type": "TRIAL", "product_id": "annual_sub_one_week_trial", "store": "PLAY_STORE", "transaction_id": "GPA.1234-5678-9012-34567", } }, "email": null, "eventName": "rc_billing_issue_event", "id": "12345678-1234-1234-1234-123456789012", "userId": "$RCAnonymousID:87c6049c58069238dce29853916d624c", } ``` **Product Change** ```json { "id": "12345678-1234-1234-1234-123456789012", "email": null, "eventName": "rc_product_change_event", "userId": "$RCAnonymousID:87c6049c58069238dce29853916d624c", "dataFields": { "event_properties": { "environment": "PRODUCTION", "expiration_at_ms": 1652327468000, "original_transaction_id": "123456789012345", "period_type": "TRIAL", "product_id": "annual_sub_trial", "store": "APP_STORE", "transaction_id": "123456789012345", "new_product_id": "annual_sub_trial" } }, "createdAt": 1651722668000 } ``` ## Considerations ### Refunds Revenue for Iterable campaign reporting will not be accurate due to refund events. You can build custom workflows around a "refund" event and independently calculate the total revenue refunded for your campaigns. ### Purchase event tracking Iterable provides two event-tracking APIs: - [Track Purchase API](https://api.iterable.com/api/docs#commerce_trackPurchase): This aggregates all purchase-related events into a single purchase event for tracking overall revenue. However, it does not distinguish between the types of purchase events (like initial purchases, trials, renewals, etc.). - [Track Custom Event API](https://api.iterable.com/api/docs#events_track): While it allows for detailed tracking of individual purchase events, it doesn't support revenue tracking as that is exclusive to the Track Purchase API. You have the flexibility to use one or both APIs depending on whether you need detailed insights into specific events or an aggregate revenue perspective. Ensure [Allow new custom events into the system](https://support.iterable.com/hc/en-us/articles/115002065083-Managing-Custom-Events-#event-handling-for-newly-encountered-events) is enabled in your Iterable project settings, or manually add all the event names you want to track as custom events to the Iterable project settings. Learn more about tracking events with this integration in Iterable RevenueCat's [documentation](https://support.iterable.com/hc/en-us/articles/5167223724436-RevenueCat-Iterable-Integration-#in-iterable) or Iterable's [tracking docs](https://support.iterable.com/hc/en-us/articles/205480285-Tracking-Conversions-Purchases-and-Revenue-#step-4-track-custom-events-and-purchases).