SaaSquatch Help Center

Follow this guide to setup a "Give 50, Get 50 Points Referral Program" using the SaaSquatch REST API and Squatch.js

Install squatch.js

squatch.js will show a gorgeously rendered popup in your app so your customers can seamlessly refer their friends.

Track Conversions

When a referred user converts, typically to paid, notify Referral SaaSquatch so their rewards can be distributed.

Redeem points

When someone wants to redeem their points, adjust their point balance and give them their reward.


How to use the REST API to track conversions

Step 1 - Notify SaaSquatch of the new account status

If this is the first purchase that a customer has made, use this API call to notify SaaSquatch about the new account status. In particular, make sure to set status: PAID. You should update this status for all accounts. If a valid referral has been made, and someone has paid their first bill, then SaaSquatch will automatically add points to the account of the friend that referred them.

Example Request Example Response
$ curl https://app.referralsaasquatch.com/api/v1/TENANT_ALIAS/accountsync \
-u API_KEY: \
-H "Content-Type: application/json" \
-d '{ "id": "SV0TYE5OWI11120144",
  "currency": "USD",
  "subscription": {
    "status": "PAID", 
    "value": 99.99,
    "billingIntervalType": "DAY",
    "billingIntervalValue": 30
  }
}'
{
  "id": "SV0TYE5OWI11120144",
  "currency": "USD",
  "subscription": {
    "status": "PAID", 
    "value"": 99.99,
    "billingIntervalType": "DAY",
    "billingIntervalValue": 30
  },
  "referral": {
    "code": "BOBTESTERSON"
  }
}

How to redeem points

Step 1 - Lookup points balance

Lookup a users' points balance by checking the balance of an account. This will include both points from being referred and points from referring friends. It is possible to explore the individual points that has been earned by an account (see List Rewards), but for most cases it is simpler to just lookup the full reward balance.

Looking up the points balance does not change the state of an account, so you can also use this call to display a users' point balance on any page. For example, using the example response below, you could include a message in your app head "You've earned 50 points. Make more referrals to earn more."

Example Request Example Response
$ curl https://app.referralsaasquatch.com/api/v1/{TENANT_ALIAS}/reward/balance?accountId=SV0TYE5OWI11120144 \
-u API_KEY: \
-H "Content-Type: application/json"
[
    {
        "type": "CREDIT",
        "count": 1,
        "totalAssignedCredit": 50,
        "totalRedeemedCredit" : 0,
        "unit": "points"
    }
]
Step 2 - Fulfill Reward

You are responsible for fulfilling the reward you offer through your referral program.

Step 3 - Redeem Points with Referral SaaSquatch

Update the accounts' balance in SaaSquatch once points have been used. This lets SaaSquatch display a users' up-to-date point balance and lets us track points usage.

Use the Debit Account Balance endpoint to mark the points as used.

Example Request Example Response
$ curl https://app.referralsaasquatch.com/api/v1/TENANT_ALIAS/credit/bulkredeem \
-u API_KEY: \
-H "Content-Type: application/json" \
-d '{
    "accountId" : "SV0TYE5OWI11120144",
    "amount" : 20, 
    "unit" : "points"
}'
{
    "creditRedeemed": 20,
    "creditAvailable": 0,
    "unit": "points"
}