# Users
> A user represents an individual who interacts with your app.
export const components = {
pre: CodeSnippet,
};
To complete integration, you must register users of your app in WinWinKit via our SDK or REST API..
## User Properties
### Configurable
These are the properties that you can use to update your user entities in WinWinKit.
#### App User Id (Required)
The only mandatory property that uniquely identifies a user within your app and in WinWinKit.
Normally it is a universally unique identifier (UUID).
#### Is Premium
Flag determining the premium status of a user.
The `is_premium` flag serves an important purpose of tracking:
- [Amount per Conversion](/docs/affiliates/introduction/#amount-per-conversion) in affiliate rewards;
- [Activation on Conversion](/docs/referrals/introduction/#activation) configuration in referral programs;
- [Stats](/docs/users/introduction/#stats) of referring users.
We recommend updating it whenever user's premium status changes.
To handle trial users properly, read more about [Is Trial](/docs/users/introduction/#is-trial) flag below.
For automatic updates of the `is_premium` flag, enable integration with
[RevenueCat](https://revenuecat.com/). To do this, go to your project in
WinWinKit and navigate to Settings -> Integrations page.
#### Is Trial
Flag determining the trial status of a user. Helps to improve conversion tracking accuracy by filtering out users who are still in trial.
We recommend updating it whenever user's trial status changes.
When both `is_premium` and `is_trial` are set to `true`, the user is considered a trial user, and no conversion is tracked.
For automatic updates of the `is_trial` flag, enable integration with
[RevenueCat](https://revenuecat.com/). To do this, go to your project in
WinWinKit and navigate to Settings -> Integrations page.
#### First Seen At
Date when the user was first seen in your app.
Used to determine user's eligibility to claim a referral code. Learn more about [Claim Code Elibigility](/docs/users/introduction/#claim-code-eligibility)
#### Metadata
A metadata object.
This allows you to provide extra configuration and metadata making it flexible to meet your specific needs.
Must be a valid JSON object.
#### Stripe Customer ID
Stripe customer ID.
Used in tracking revenue with Stripe for the [Affiliates](/docs/affiliates/introduction/) feature.
Example: **cus_1234567890**
### Provided by WinWinKit
These are the properties provided by WinWinKit that reflect user's referral data, active and expired rewards, and stats.
#### Referral Code
Unique referral code for the user.
A referral code is always 6 characters long and consists of a combination of letters and numbers.
The code is unique within your app.
Is assigned once and never changes.
Example: **XYZ123**
#### Referral Code Link
A web url to the referral code and its rewards which your app users can share with friends.
Learn more about how to set up [Code Link](/docs/pages/code-link/).
**Example**: `https://appname.wwk.link/XYZ123`
#### Referral Program
An object containing complete information about the referral program assigned to the user.
Can be used to create dynamic user interface based on the program configurations.
#### Claim Code Eligibility
An object providing information about user's eligibility to claim a referral code.
**An eligible user is allowed to claim a referral code.**
**Eligibility Rules**
Currently, WinWinKit implements a few simple rules for limiting the types of users eligible to claim a referral code.
- A user must not be older than the configured time constraints for claiming a code (by default it is 7 days).
The reference date used is the [First Seen At](/docs/users/introduction/#first-seen-at), if provided; otherwise, the date when the user was created in WinWinKit is used.
This is a configurable setting and can be set between 0 and 365 days, where 0 allows unlimited time for claiming a code. To change the setting, open your project dashboard → Settings → General → Configurations → Claim Code Constraint in Days.
- The limit for claiming a code has not been reached.
The limit is defined by the [referral program](/docs/referrals/introduction/)'s or [promo code](/docs/promos/introduction/)'s limit.
By default there is no limit, and it must be specified for this rule to
apply.
- A user can claim a code only once.
- A user cannot claim own code.
You can impose further limitations on a user's ability to claim a
code by building own logic and user experience.
If a user attempts to claim a code when not eligible, WinWinKit
provides an error code and a descriptive message explaining the reason for the decline.
Learn more about [Handling Errors](/developers/api/errors/) for more details.
**Example**
The `eligible` field indicates whether the user can claim a code, while `eligible_until` specifies the expiration date.
```json
"claim_code_eligibility": {
"eligible": true,
"eligible_until": "2025-02-10T10:28:18.104Z"
}
```
Until date can be null if the user is not eligible or when there is no time constraint for claiming a code.
#### Referred By
An object with the claimed code, and a type, which can be one of `affiliate`, `promo`, or `referral`.
**Example**
```json
"referred_by": {
"code": "XYZ123",
"type": "affiliate"
}
```
Code value can be null if the entity (e.g. affiliate campaign) of claimed code has been deleted.
#### Stats
An object with information about referral statistics for the user.
Provides three values:
- Claims - how many invited users claimed the user's referral code.
- Conversions - how many of those who claimed the user's referral code became premium users.
- Churns - how many of those who claimed the user's referral code became premium users and then churned.
Correct tracking of Conversions and Churns requires updating [Is
Premium](/docs/users/introduction/#is-premium) flag.
**Example**
```json
"stats": {
"claims": 10,
"conversions": 8,
"churns": 1
}
```
#### Rewards
A list of active and expired rewards for the user.
Remember to unlock access to the active rewards in your app.
```json
"rewards": {
"active": {
"basic": [
{
"reward": {
"key": "app-icon-neon",
"name": "App Icon Neon",
"description": "Access to an exclusive app icon",
"metadata": null,
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
},
"expires_at": null,
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
}
],
"credit": [
{
"reward": {
"key": "20-ai-requests",
"credits": 20,
"name": "20 AI Requests",
"description": "Access to extra AI requests",
"metadata": null,
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
},
"credits": 20,
"expires_at": "2021-01-01T00:00:00.000Z",
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
}
],
"offer_code": [
{
"reward": {
"key": "free-month",
"offer_code_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Free Month",
"description": "Receive a free month of a subscription",
"metadata": null,
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
},
"value": {
"value": "ABCDEFGHIJKLMNOPQR",
"link": "https://apps.apple.com/redeem?ctx=offercodes&id=1234567890&code=ABCDEFGHIJKLMNOPQR",
"expires_at": "2021-01-01T00:00:00.000Z"
},
"expires_at": "2021-01-01T00:00:00.000Z",
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
}
]
},
"expired": {
"basic": [],
"credit": [],
"offer_code": []
}
}
```
## Example
Below is an example of a full referral user object returned by the REST API.
```json
{
"data": {
"user": {
"app_user_id": "821fae4b5-1a2d-4c1e-9152-5297086a161c",
"referral_code": "XYZ123",
"referral_code_link": "https://appname.wwk.link/XYZ123",
"is_premium": false,
"first_seen_at": "2024-11-10T10:28:18.104Z",
"metadata": {},
"stripe_customer_id": "cus_1234567890",
"claim_code_eligibility": {
"eligible": true,
"eligible_until": "2024-11-10T10:28:18.104Z"
},
"referred_by": {
"code": "XYZ123",
"type": "affiliate"
},
"stats": {
"claims": 0,
"conversions": 0,
"churns": 0
},
"rewards": {
"active": {
"basic": [
{
"reward": {
"key": "basic-reward",
"name": "Basic Reward",
"description": "This is a basic reward",
"metadata": {},
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
},
"expires_at": "2021-01-01T00:00:00.000Z",
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
}
],
"credit": [
{
"reward": {
"key": "credit-reward",
"credits": 100,
"name": "Credit Reward",
"description": "This is a credit reward",
"metadata": {},
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
},
"credits": 100,
"expires_at": "2021-01-01T00:00:00.000Z",
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
}
],
"offer_code": [
{
"reward": {
"key": "offer-code-reward",
"offer_code_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Offer Code Reward",
"description": "This is an offer code reward",
"metadata": {},
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
},
"value": {
"value": "ABCDEFGHIJKLMNOPQR",
"link": "https://apps.apple.com/redeem?ctx=offercodes&id=1234567890&code=ABCDEFGHIJKLMNOPQR",
"expires_at": "2021-01-01T00:00:00.000Z"
},
"expires_at": "2021-01-01T00:00:00.000Z",
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
}
]
},
"expired": {
"basic": [
{
"reward": {
"key": "basic-reward",
"name": "Basic Reward",
"description": "This is a basic reward",
"metadata": {},
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
},
"expired_at": "2021-01-01T00:00:00.000Z",
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
}
],
"credit": [
{
"reward": {
"key": "credit-reward",
"credits": 100,
"name": "Credit Reward",
"description": "This is a credit reward",
"metadata": {},
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
},
"expired_at": "2021-01-01T00:00:00.000Z",
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
}
],
"offer_code": [
{
"reward": {
"key": "offer-code-reward",
"offer_code_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Offer Code Reward",
"description": "This is an offer code reward",
"metadata": {},
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
},
"expired_at": "2021-01-01T00:00:00.000Z",
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
}
]
}
},
"referral_program": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Referral Program #1",
"description": "This is a referral program",
"metadata": {},
"distribution_percentage": 100,
"limit": 0,
"rewards": {
"sender": {
"basic": [
{
"reward": {
"key": "basic-reward",
"name": "Basic Reward",
"description": "This is a basic reward",
"metadata": {},
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
},
"activation": {
"variant": "claim",
"amount": 1
},
"deactivation": {
"variant": "never"
}
}
],
"credit": [
{
"reward": {
"key": "credit-reward",
"credits": 100,
"name": "Credit Reward",
"description": "This is a credit reward",
"metadata": {},
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
},
"activation": {
"variant": "claim",
"amount": 1,
"limit": 1
},
"deactivation": {
"variant": "never"
}
}
],
"offer_code": [
{
"reward": {
"key": "offer-code-reward",
"offer_code_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Offer Code Reward",
"description": "This is an offer code reward",
"metadata": {},
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
},
"activation": {
"variant": "claim",
"amount": 1,
"limit": 1
},
"deactivation": {
"variant": "never"
}
}
]
},
"receiver": {
"basic": [
{
"reward": {
"key": "basic-reward",
"name": "Basic Reward",
"description": "This is a basic reward",
"metadata": {},
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
},
"activation": {
"variant": "claim"
},
"deactivation": {
"variant": "never"
}
}
],
"credit": [
{
"reward": {
"key": "credit-reward",
"credits": 100,
"name": "Credit Reward",
"description": "This is a credit reward",
"metadata": {},
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
},
"activation": {
"variant": "claim"
},
"deactivation": {
"variant": "never"
}
}
],
"offer_code": [
{
"reward": {
"key": "offer-code-reward",
"offer_code_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "Offer Code Reward",
"description": "This is an offer code reward",
"metadata": {},
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
},
"activation": {
"variant": "claim"
},
"deactivation": {
"variant": "never"
}
}
]
}
},
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-01T00:00:00.000Z"
}
}
}
}
```