Customer Lists
Cohort and export your customers
RevenueCat Customer Lists allow you to cohort and export groups of customers based on some interactions with your app and/or purchase behavior.
Lists are a segment of your customers inside RevenueCat, this can include both paying and non-paying users. Some lists are created automatically for every project (see Default lists below) and you can also create custom lists with your own defined filter logic.
If you're on a legacy Free plan and want to access custom lists or export lists, migrate to our new pricing via your billing settings.
Sandbox Customers
The Customers dashboard tab doesn't support toggling the 'View sandbox data' switch as there is no concept of a sandbox customer in RevenueCat, only sandbox transactions.
To view customers who have made sandbox transactions you can use the default Sandbox list or apply the 'Made Sandbox Purchase' filter to a list.
Find an Individual Customer
You can look up an individual customer by an exact match of their App User ID, Transaction ID, Email Attribute, or Order ID (iOS only). To find a customer via Order ID, you can follow our guide on setting up In-App Purchase Keys to unlock this feature. The transaction must show as completed in the Apple Purchase History to be considered a valid Order ID. Note that Transaction ID refers to the identifier in Google Play console and order emails of GPA.1234.1223–, and for Stripe si_abcefg, whereas Order ID refers to the identifier from Apple's order emails.
Looking up customers in RevenueCat is real-time, as soon as a customer exists in RevenueCat they will be searchable here.
Viewing a List
Choose a project
Customer lists are created on a per-project basis, you must select a project before viewing a list. Lists cannot be combined across projects inside of RevenueCat.
Default lists
RevenueCat creates some default lists for every project. Default lists should give you insight into every customer that has ever made any purchase.
| Default List | Description |
|---|---|
| Active | Any customer with an active subscription or trial. |
| Sandbox | Any customer who has any sandbox transaction associated with their App User ID. This can be useful for isolating development devices or Testflight users. |
| Non-subscription | Any customer with a non-subscription purchase associated with their App User ID. |
| Expired | Any customer with an expired subscription or trial. |
Promotionals are not considered 'Active'
If a customer has a Promotional transaction, they are not considered as 'Active'. Note that if a customer has an active subscription + Promotional, they will not be counted in the Active Customer List.
Custom lists
In addition to Default Lists, you can create new Custom Lists with any combination of AND filters. See the section below on 'Filters' for a full description of available filters.
Custom lists are shared across collaborators
Any custom lists you create will also be visible to any project collaborators with Read or Admin privileges.
Overview Metrics
For each list, RevenueCat computes overview metrics for the cohort of customers.
| Metric | Description |
|---|---|
| Customers | The total number of customers in the list. |
| Active Trials | The total number of active trials. This includes trials which are cancelled, or in their grace period, and have not yet expired. |
| Active Subscriptions | The total number of active subscriptions. This includes subscriptions which are cancelled, or in their grace period, and have not yet expired. |
| Total Revenue | The total revenue (USD) that the list of customers has generated, minus refunds. |
Active Subscribers vs. Active Subscriptions
Active "subscribers" may be lower than your count of all active "subscriptions" (e.g. in Overview or Charts) if some customers have multiple active subscriptions.
List Data
For each list, RevenueCat displays the 100 most recently seen customers in the dashboard.
The dashboard shows the App User ID, purchase status, total spent (USD) and the latest product identifier purchased. Additional columns are available when exporting data.
Customer lists are refreshed every 2 hours
For lists with the filter Only Customers with Purchases enabled (see our Filters section below), deleted users will be removed in a matter of seconds. For lists without this filter, it will take up to 30 minutes for a deleted user to be removed.
Filters
Filters allow you to choose which customers appear in your list. You can create custom lists with any combination of filters. All filters are applied as AND filters.
The first filter is a default filter applied to every customer list. You can choose whether the list should be limited to only those customers that have purchases (e.g., started a trial, started a subscription, or made a non-subscription purchase) or not. Lists that are limited to only customers with purchases typically load much faster, because there are many more customers without transactions than those with transactions.
Filtering customers by purchase is being rolled out gradually, so you may not see this option available in your lists immediately.
See the table below for additional filters you can apply to your lists.
| Filter | Type | Description |
|---|---|---|
| Ad | String | The $ad Subscriber Attribute for the customer. |
| Ad Group | String | The$adGroup Subscriber Attribute for the customer. |
| Auto Renew Intent | Bool | Whether the customer has opted out of auto-renew or not. |
| Campaign | String | The$campaign Subscriber Attribute for the customer. |
| Cancellation Date | Date | The date the customer unsubscribed from their subscription. Will be set back to null if the customer later resubscribes. |
| Creative | String | The$creative Subscriber Attribute for the customer. |
| String | The $email Subscriber Attribute for the customer. | |
| First Purchase Date | Date | The date of the customers first transaction. |
| First Seen Date | Date | The date the customer was first seen by RevenueCat. |
| GPS Ad Id | String | The$gpsAdId Subscriber Attribute for the customer. |
| Granted RC Promotional | Bool | Whether the customer has been granted a Promotional Subscription or not. |
| IDFA | String | The$idfa Subscriber Attribute for the customer. |
| IDFV | String | The$idfv Subscriber Attribute for the customer. |
| Keyword | String | The$keyword Subscriber Attribute for the customer. |
| Last Seen Country | String | The two-letter ISO 3166-1 alpha-2 code of the country where the user was last seen, determined by IP address. |
| Last Seen Date | Date | The date the customer was last seen by RevenueCat. |
| Latest Entitlement | String | The latest Entitlement unlocked by the customer. |
| Latest Expiration Date | Date | The latest expiration date of the customers Entitlement. |
| Latest Product | String | The customers latest purchased product identifier. |
| Latest Purchase Date | Date | The customers latest transaction date. |
| Latest Renewal Date | Date | The customers latest renewal date. This could be the same as Latest Purchase Date. |
| Latest Store | Multi Select | The latest store the customer purchased from. |
| Made Non-subscription Purchase | Bool | Whether the customer has made any non-subscription purchases or not. |
| Made Sandbox Purchase | Bool | Whether the customer has made any sandbox purchases or not. |
| Media Source | String | The$mediaSource Subscriber Attribute for the customer. |
| Number of Renewals | Integer | The total number of renewals the customer has had. A trial conversion is considered a renewal. |
| Phone Number | String | The $phoneNumber Subscriber Attribute for the customer. |
| Status | Multi Select | The latest status of the customer. |
| Total Spent | Integer | The total revenue (in USD) spent by the customer. |
| Trial Cancellation Date | Date | The date the customer unsubscribed from their free trial. Will be set back to null if the customer later resubscribes. |
| Trial End Date | Date | The date the customers free trial expires. |
| Trial Start Date | Date | The date the customer started their free trial. |
Date filters are start of day
Selecting any date filters will apply to the start of the day. For example,
2021-01-01will be2021-01-01T00:00:00under the hood.
Exporting Data
The complete list of customers in a list can be exported as a .csv file. Exports are processed in the background, and you'll receive an email with a link to download the file. Emails are sent to the logged in account that requested the export. The download links are shareable and available for 30 days.
Below is a description of the .csv format for the exported data.
| Column Name | Description |
|---|---|
| app_name | The name of the app in RevenueCat. |
| app_uuid | A unique identifier for the app in RevenueCat. |
| app_user_id | The customer's user identifier in RevenueCat. |
| first_seen_at | Epoch timestamp in milliseconds when the customer was first seen by RevenueCat. |
| last_seen_at | Epoch timestamp in milliseconds when the customer was last seen by RevenueCat. |
| ip_country | The two-letter ISO 3166-1 alpha-2 code of the country where the user was last seen, determined by IP address of the customer API request. |
| has_made_sandbox_purchase | Boolean indicating whether the customer has made any sandbox purchases. |
| latest_entitlement | The most recently unlocked RevenueCat Entitlement identifier. |
| latest_product | The most recently purchased product identifier. |
| is_rc_promo | Whether the most recent transaction was a RevenueCat Promotional. |
| first_purchase_at | Epoch timestamp in milliseconds of the customer's first transaction. |
| most_recent_purchase_at | Epoch timestamp in milliseconds of the customer's most recent transaction. |
| most_recent_renewal_at | Epoch timestamp in milliseconds of the customer's most recent renewal transaction. |
| trial_start_at | Epoch timestamp in milliseconds when the customer started a free trial. |
| trial_end_at | Epoch timestamp in milliseconds of the customer's free trial expiration date. |
| latest_expiration_at | Epoch timestamp in milliseconds of the customer's latest expiration date. If greater than now, then the customer has an active subscription. |
| subscription_opt_out_at | Epoch timestamp in milliseconds when a subscription or trial cancellation was detected by RevenueCat. |
| trial_opt_out_at | Epoch timestamp in milliseconds when the latest trial cancellation was detected by RevenueCat. |
| total_renewals | The total number of subscription renewals for the customer. |
| total_spent | The total amount spent by the customer in USD. |
| latest_store | The latest store that the customer purchased from. |
| latest_auto_renew_intent | Boolean indicating whether the customer has chosen to have their subscription or trial auto-renew. . Can be either t (true), or f (false). |
| all_purchased_product_ids | A comma separated list of all the product identifiers purchased by the customer. |
| most_recent_billing_issues_at | Epoch timestamp in milliseconds when a subscription billing issue was detected by RevenueCat. |
The $email Subscriber Attribute for the customer, if set. | |
| phone_number | The $phoneNumber Subscriber Attribute for the customer, if set. |
| media_source | The $mediaSource Subscriber Attribute for the customer, if set. |
| campaign | The $campaign Subscriber Attribute for the customer, if set. |
| ad_group | The$adGroup Subscriber Attribute for the customer, if set. |
| ad | The $ad Subscriber Attribute for the customer, if set. |
| keyword | The $keyword Subscriber Attribute for the customer, if set. |
| creative | The $creative Subscriber Attribute for the customer, if set. |
| idfa | The $idfa Subscriber Attribute for the customer, if set. |
| idfv | The $idfv Subscriber Attribute for the customer, if set. |
| gps_ad_id | The $gpsAdId Subscriber Attribute for the customer, if set. |
| custom_attributes | JSON representation of any custom Subscriber Attributes set for the customer. |
"The last successful export finished recently. Please, wait some minutes before submitting another export."
Note that there is a wait time of 30 minutes between each export.
Exported files
Customer List exports are CSV files compressed in a GZ file. A GZ file is a compressed file similar to a ZIP file, although it uses a different compression algorithm.
Note that the timestamps in the exports are measured in milliseconds since Unix epoch. To convert these timestamps into a readable date, the formula is (A1÷86400000)+(DATE(1970,1,1)) where A1 is the corresponding cell.
macOS
Can be opened by Archive Utility, included in macOS by default.
Windows
Can be opened with a third party utility like WinZip or 7-Zip.
Check for .csv file extension
If you're having trouble opening the exported/uncompressed file, you may need to manually add the .csv extension.
Next Steps
- Learn how to view the purchase history of a specific user and grant them promotional access via the Customer View
Updated 7 days ago