Dollar Credit Integration Guide

How to use the REST API at checkout

When your customers checkout, use the SaaSquatch API to lookup referral credit, apply the credit internally and then update SaaSquatch with the new account balance.

Step 1 - Lookup referral credit

When a new user creates an account in your app, make sure they get identified in a call to squatch.js init. This will complete the referral tracking by SaaSquatch to automatically link them to the account that referred them and give them a credit off their first order.

Lookup credits by checking the balance on an account. This will include both credit from being referred, and from referring friends. It is possible to explore the individual credits that have been earned by an account (see List Rewards), but for most cases it is simpler during checkout to just lookup the full reward balance.

Looking up the credit value does not change the state of an account, so you can also use this call to update the price of plans on the checkout page. For example, using the example response below, you could include a message on your checkout page that says "You have $20 of referral credit"

$ 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": 2000,
        "totalRedeemedCredit" : 0,
        "unit": "cents"
    }
]

Step 2 - Apply the Credit Internally

You can use any method to apply the credit, but we recommend line items so that your customers can clearly see the referral credit on their invoices. Add a line item to the invoice for the discount or use an internal code to identify the referral credit.

Step 3 - Mark credit as used

Update the accounts' balance in SaaSquatch once credit has been used. This lets SaaSquatch display a users' up-to-date account balance and lets us track referral credit usage.

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

$ curl https://app.referralsaasquatch.com/api/v1/TENANT_ALIAS/credit/bulkredeem \
-u API_KEY: \
-H "Content-Type: application/json" \
-d '{
    "accountId" : "SV0TYE5OWI11120144",
    "amount" : 2000, 
    "unit" : "cents"
}'

{
    "creditRedeemed": 2000,
    "creditAvailable": 0,
    "unit": "cents"
}

Step 4 - 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 a referral credit into the account of the friend that referred them.

$ 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"
    }
}