Skip to content

pctDiscountGuide.md

Latest commit

 

History

History
248 lines (214 loc) · 11.2 KB

pctDiscountGuide.md

File metadata and controls

248 lines (214 loc) · 11.2 KB
Raw
title Percent Discount
highlights 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
slug guides/percent-discount
sectionType guide
template article.html
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.

  • Install squatch.js on your page
  • Replace the init variables with real user data
  • Add a button to your page with class="squatchpop"
  • Testing Click the button. Make sure the popup shows. (Make sure you are using the right account_id and user_id)
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.

  • Add a hidden input to your checkout page
  • Use squatch.js autofill to read the tracking cookie and set the active referral code in your form
  • Validate the referral code to ensure the discount is valid
  • Apply a discount or credit to the first bill
  • Use accountsync REST endpoint to update SaaSquatch about the new account
  • Testing Click a referral link and signup for a new account. Login to your SaaSquatch account to see the new referral in the news feed.
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.

  • Use the accountsync REST endpoint to update SaaSquatch about upgrades, downgrades or cancels
  • Lookup an account's reward if you need to apply any proration during upgrades or downgrades
  • Testing Cancel an account that was previously referred. Login to your SaaSquatch account to verify that referral credit was properly adjusted.
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"
    }
}