Users

To integrate referral program, you must register users of your app in WinWinKit. Learn more about supported integrations.

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 premium status of a user. Used with the Activation on Conversion configuration and for tracking referring user’s Stats. We recommend updating it whenever user’s premium status changes.

For automatic updates of the is_premium flag, enable integration with RevenueCat. 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

Last Seen At

Date when the user was last seen in your app. Tracked automatically if integrated via Swift SDK.

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.

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. 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 7 days. Because referral is for inviting new users, this restricts users from getting rewards without referring new users. The reference date used is the First Seen At, if provided; otherwise, the date when the user was created in WinWinKit is used.
Does this rule seem reasonable? If not, we would love to hear your feedback.
The program limit has not been reached. The reference program here is referring user’s program. Read more about Programs Limit configuration.
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 referral code, but cannot prolong elibility conditions imposed by WinWinKit. Once a user is not eligible according to WinWinKit, there is no override.

If a user attempts to claim a referral code when not eligible, WinWinKit provides a descriptive message explaining the reason for the decline.

Example The eligible field indicates whether the user can claim the referral code, while eligible_until specifies the expiration date.

"claim_code_eligibility": {
  "eligible": true,
  "eligible_until": "2025-02-10T10:28:18.104Z"
}

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 flag.

Example

"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.

"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 API.

{
  "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",
      "last_seen_at": null,
      "metadata": {},
      "claim_code_eligibility": {
        "eligible": true,
        "eligible_until": "2024-11-10T10:28:18.104Z"
      },
      "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"
      }
    }
  }
}

General

Features

Integrations

Misc

User Properties

Configurable

App User Id (Required)

Is Premium

First Seen At

Last Seen At

Metadata

Provided by WinWinKit

Referral Code

Referral Code Link

Referral Program

Claim Code Eligibility

Stats

Rewards

Example

General

Features

Integrations

Misc

​User Properties

​Configurable

​App User Id (Required)

​Is Premium

​First Seen At

​Last Seen At

​Metadata

​Provided by WinWinKit

​Referral Code

​Referral Code Link

​Referral Program

​Claim Code Eligibility

​Stats

​Rewards

​Example

User Properties

Configurable

App User Id (Required)

Is Premium

First Seen At

Last Seen At

Metadata

Provided by WinWinKit

Referral Code

Referral Code Link

Referral Program

Claim Code Eligibility

Stats

Rewards

Example