Users

A user represents an individual who interacts with your app.

Users

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:

We recommend updating it whenever user’s premium status changes.

To handle trial users properly, read more about Is Trial flag below.

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.

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

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

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 the configured time constraints for claiming a code (by default it is 7 days).

    The reference date used is the 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’s or promo code’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 for more details.

Example

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

"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

"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 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 REST 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",
      "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"
      }
    }
  }
}