Define your first reward

Referrals and offers revolve around rewards. In some cases, a user will refer another user simply because they think your product is great, and that's an incredible thing to see! It's true word-of-mouth, organic growth. But oftentimes users need a little push to take the action you want them to take, whether that's sending a referral, signing up, activating, or engaging with your product in some other way. A reward can be that little push they need.

What are rewards?

A reward in the Resonance platform is a totally-customizable entity that gets sent to your system, along with a user id, whenever a user is eligible to receive that reward. Since rewards can be application-dependent, and since issuing cash rewards requires a lot of setup effort from your users (like giving us bank info to deposit a reward), Resonance does not handle reward fulfillment. (This may change in the future for some use cases). Instead, Resonance delegates reward fulfillment to your system by sending that reward notification. Upon receiving a reward notification, your system is free to issue the specified reward however it sees fit.

Rewards have one required property, a name, and then an unlimited number of optional properties that you can add. Names must be unique for each reward your organization creates. Our recommendation is to use a human-readable name, like $25 cash or $10 Visa gift card and then use your optional properties to create a reusable schema that your system can interpret and act on. (Note for developers: the reward notification will include all of your optional fields as a JSON object containing each field and value).

Examples

Let's look at a simple example to see how rewards work in practice. We'll start with our $25 cash reward. To properly parameterize this reward such that your system can issue it without having to reference the name field (since that would require a code update every time you add a new reward, which would create a bottleneck on engineering), we'll want to specify the three most important aspects of this reward: the amount, the currency (if you work with more than just USD), and the type (assuming you have more than just cash, like stock or gift cards or discounts).

The reward would look like this in the console as you're creating it:

And when the reward notification comes through to your system, the JSON would look like:

{
  "name": "$25 cash",
  "userId": "the_users_id",
  "data": {
    "amount": "25",
    "currency": "USD",
    "type": "cash" 
  }
}

Developer note: all values will be sent as strings, including numeric ones like amount. This is to avoid having to infer types or ask folks working in the console to specify types (since they may be non-technical). Please parse values in your system according to the schema you settle on.

Now let's say we want to test another reward amount, like $10 cash. We'd set up another reward the same way, but with a new name and a new value for amount. As long as your system has not hardcoded any values and can simply handle the amount that comes to it, this new reward should work just like the $25 cash reward without any additional engineering effort!

Next steps

Awesome! Now that you've defined your first reward we have one more step—creating a condition—then we can go ahead and use it to create offers and referrals. Later we will also learn how to setup webhooks to receive reward notifications, or how to use the reward pull API if you don't want to use webhooks.

Please also see the rewards API endpoints if you want to work with rewards outside of the console: