Build With RevenueCat

Build a customized mobile subscription business with RevenueCat. We do the heavy lifting of normalizing subscribers from any source and maintain a single source of truth for subscription status, so you can get back to building your app.

RevenueCat is a powerful, secure, reliable, and free to use in-app purchase server with global support. All you need to get started is an API key.

Get Started    REST API Endpoints

Subscriber Attributes

Adding custom properties to users in RevenueCat

Subscriber attributes are useful for storing additional, structured information on a user. For example, you could store your user's email address and additional system identifiers directly in RevenueCat. Attributes will not be seen by your users unless you choose to explicitly show them yourself.

πŸ“˜

Subscriber attributes are only synced with RevenueCat servers on app launch, app backgrounded, and when purchases are made or restored.

Setting Attributes

Subscriber attributes can be set through the Purchases SDK by passing a dictionary of strings to the setAttributes() method on the shared Purchases instance.

Purchases.shared.setAttributes(["age" : "24", 
                             "custom_group_id" : "abc123"])
[[RCPurchases sharedPurchases] setAttributes:@{
    @"age": @"24",
    @"custom_group_id": @"abc123"
}];
Purchases.sharedInstance.setAttributes(mapOf("age" to "24", "custom_group_id" to "abc123"))
Map<String, String> attributes = new HashMap<String, String>();
attributes.put("age", "24");
attributes.put("custom_group_id", "abc123");

Purchases.getSharedInstance().setAttributes(attributes);
Purchases.setAttributes({ "age" : "24", "custom_group_id" : "abc123" });
Purchases.setAttributes({ "age" : "24", "custom_group_id" : "abc123" });

🚧

Since subscriber attributes are writable using a public key they should not be used for managing secure or sensitive information such as subscription status, coins, etc.

Restrictions

You can specify up to 50 attributes, with key names up to 40 characters long and values up to 500 characters long. Keys cannot start with $ unless it's for one of the reserved attributes below.

Attribute key checklist:
βœ… Key does not contain whitespace
βœ… Key must start with a letter for non-reserved attributes or "$" for reserved attributes
βœ… Key does not include any non-alphanumeric characters except - and _
βœ… Key is not more than 40 characters
βœ… Value is not more than 500 characters
βœ… No more than 50 custom attributes

Reserved attributes

Attribute keys beginning with $ are reserved for RevenueCat. The current list of reserved keys are below:

General

Key

Description

$email

Email address for the user

$displayName

Name that should be used to reference the user

$phoneNumber

Phone number for the user

$apnsTokens

Apple push notification tokens for the user

$fcmTokens

Google push notification tokens for the user

Device Identifiers

Key

Description

$idfa

Apple advertising identifier

$idfv

Apple vendor identifier

$gpsAdId

Google advertising identifier

$androidId

Android device identifier

πŸ“˜

Device identifiers can't be changed once set

Once a device identifier is set for a subscriber, it can't be changed in order to keep these identifiers associated with the original installation. This allows RevenueCat to send events generated by a particular device to downstream integrations with a consistent identifier unaffected by uninstalls and reinstalls.

Third-party Identifiers

Key

Description

$adjustId

Adjust user identifier

$appsflyerId

Appsflyer user identifier

$fbAnonId

Facebook SDK anonymous user identifier

$mparticleId

mParticle user identifier

$onesignalId

OneSignal player identifier

Braze User Alias Object

Key

Description

$brazeAliasName

Braze 'alias_name' in User Alias Object

$brazeAliasLabel

Braze 'alias_label' in User Alias Object

Attribution Data

Key

$mediaSource

$campaign

$adGroup

$ad

$keyword

$creative

πŸ“˜

If you have access to install attribution data, you can set it using the reserved keys above. RevenueCat itself is not an attribution network and can not automatically populate this information.

Reserved attributes can be written directly by setting the key (don't forget the $ prefix) or with special helper methods:

Purchases.shared.setEmail("[email protected]")
Purchases.shared.setPhoneNumber("+16505551234")
Purchases.shared.setDisplayName("John Appleseed")
Purchases.sharedInstance.setEmail("[email protected]")
Purchases.sharedInstance.setPhoneNumber("+16505551234")
Purchases.sharedInstance.setDisplayName("John Appleseed")
Purchases.setEmail("[email protected]")
Purchases.setPhoneNumber("+16505551234")
Purchases.setDisplayName("John Appleseed")
Purchases.setEmail("[email protected]")
Purchases.setPhoneNumber("+16505551234")
Purchases.setDisplayName("John Appleseed")

Setting push tokens

Push tokens can be used to engage with your users through Apple apns or Google cloud messaging. These can be saved in RevenueCat through system callbacks after the user accepts the push notification permissions in your app.

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    Purchases.shared.setPushToken(deviceToken)
}
Purchases.sharedInstance.setPushToken(deviceToken)
Purchases.setPushToken(deviceToken);
Purchases.setPushToken(deviceToken)

Deleting Attributes

Any attribute can be cleared by passing null or an empty string as the key value. Individual attributes can also be cleared for a specific user in their customer view.

Purchases.shared.setAttributes(["age" : ""])
Purchases.sharedInstance.setAttributes(mapOf("age" to ""))
Purchases.setAttributes({"age" : ""});
Purchases.setAttributes({"age" : ""})

Reading Attributes

You can access subscriber attributes through the REST API using a secret key, in webhooks, and through analytics integrations (Amplitude, Mixpanel, Segment). The customer view dashboard will also show a list of attributes for the individual user that you can edit.

πŸ“˜

Subscriber attributes are write-only from the Purchases SDK. Reading attributes should only be done server-side through the webhooks or REST API.

Subscriber attributes are also included with transaction data for ETL exports.

Next Steps

Updated 3 months ago


Subscriber Attributes


Adding custom properties to users in RevenueCat

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.