Docs are being personalised for new programs
SaaSquatch Help Center

Percent Discount Integration Guide

Give your users 10% for a year for referring a friend. Follow this guide to setup a 'Give 10%, Get 10% Referral Program' using the SaaSquatch REST API and Squatch.js

Alternatively to the API, you can create this type of program using the Stripe, Recurly, Braintree or Zuora connectors.
Install squatch.js

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

Connect the REST API at signup

When new friends click through on a referral link and signup. You're in charge of making sure that any discount is applied on their first bill.

Connect the REST API during billing runs

Referral credit can increase and decrease as people refer more friends, so make sure you lookup referral information during bill runs.

Connect the REST API for upgrades, downgrades and cancels

When someone upgrades or downgrades, you might need to look up referral information again. Make sure you send us the new state of an account anytime it changes.

Test mode vs. live mode - We let you test your referral program using a test account and before deploying to your production environment. You will not be charged for any users or referrals made using your test account.

How to use the REST API at signup

When new friends click through on a referral link and signup. You're in charge of making sure that any discount is applied on their first bill.

Validate the discount

To get the coupon/referral code value from the tracking cookie, use the squatch.js autofill function and include the value during payment submission. Use the Get Account Reward method to look up the discount percentage for the new paying user. If a couponCode doesn't exist or is invalid, we will return an HTTP 404 status.

Looking up discount value does not change the state of an account, so you can also use this call to update the price of plans on the payment page. For example, using the example response below, you could include a message on your checkout page that says "You’ve got 20% off, 10% off from being referred, and 10% off from referring one of your friends"

Example Request Example Response 
$ curl https://app.referralsaasquatch.com/api/v1/{TENANT_ALIAS}/account/{ACCOUNTID}/reward?couponCode={CODE} \
-u {API_KEY}: \
-H "Content-Type: application/json"
 
{
    "accountId":"SV0TYE5OWI11120144",
    "discountPercentage":20,
    "referrerDiscountPercent":10,
    "referredDiscountPercent":10
}
Apply the Discount

You can use any method to apply the discount, but we recommend line items so that your customers can clearly see the referral discount on their invoices. When you create your first invoice, create an invoice line item for the discount.

Notify SaaSquatch of the new account
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
    },
    "referral": {
        "code": "3j033r"
    }
}'
 
{
    "id": "SV0TYE5OWI11120144",
    "currency": "USD",
    "subscription": {
        "status": "PAID", 
        "value"": 99.99,
        "billingIntervalType": "DAY",
        "billingIntervalValue": 30
    },
    "referral": {
        "code": "3j033r"
    }
}

How to use the REST API during billing runs

Referral credit can increase and decrease as people refer more friends, so make sure to lookup the latest referral information during bill runs.

Lookup referral credit

Use the Get Account Reward to look up the discount percentage. You don't need to set coupon_code every time you make this call, you only need to do this during first signup and we'll keep track of it from then on.

Example Request Example Response 
$ curl https://app.referralsaasquatch.com/api/v1/{TENANT_ALIAS}/account/{ACCOUNTID}/reward \
-u {API_KEY}: \
-H "Content-Type: application/json"

{
    "accountId":"SV0TYE5OWI11120144",
    "discountPercentage":20,
    "referrerDiscountPercent":10,
    "referredDiscountPercent":10
}
Apply the Discount

Whenever an invoice is created for your customers, make sure that you're applying the referral discount. As previously described for new signups, you can use any method to apply the discount, but we recommend invoice line items so that your customers can clearly see the referral discount on their invoices.

How to use the REST API for upgrades, downgrades and cancels

When someone upgrades or downgrades, you might need to look up referral information again. Make sure to send us the new state of an account anytime it changes.

Notify SaaSquatch of the account change

When someone cancels, notify SaaSquatch of the change so we can automatically reduce the referral discount for the person 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": "CANCELLED",
        "value": 99.99,
        "billingIntervalType": "DAY",
        "billingIntervalValue": 30
    },
    "referral": {
        "code": "3j033r"
    }
}'
 
{
    "id": "SV0TYE5OWI11120144",
    "currency": "USD",
    "subscription": {
        "status": "CANCELLED",
        "value": 99.99,
        "billingIntervalType": "DAY",
        "billingIntervalValue": 30
    },
    "referral": {
        "code": "3j033r"
    }
}