Percent Discount Integration Guide (No JS)
Please note: This integration is meant for non standard payment system integrations or programs that require more flexibility. Please review our easier integration option Percent Discount Integration Guide with Squatch.js and the referral wdiget
1. Identify the user
After users log into your app, we identify the users so we can enroll them into the referral program.
2. Engage the user and help them make a referral
Users can refer their friends by sharing their unique sharelink and/or referral code among their friends.
3. Attribute the newly registered user back to the user who made the referral
Identify the newly registered user and use the referral code to link them to the user that made the referral.
4. Convert the referred user when they sign up for a PAID subscription
Inform SaaSquatch when the referred user upgrades from a
TRIAL to a
5. Fulfill the earned reward for the referrer
Both users deserve a reward for the successful referral. The referred user already received their initial discount in the previous step. Next alter the invoice for the referred user for each billing cycle as long as the referred user is on a
This section provides additional info and examples on each of 5 steps laid out above.
Identify the user
Users that log into your website should be identified to SaaSquatch so they can be enrolled in the referral program. Every user needs to belong to an account, so we start by creating one using the Create or Update Account API call.
For this example the account that we're creating is for an active subscriber paying $99/mo. In this example, we're showing solo accounts, so the account and user both share the same unique id
"abc123" used in these calls. In the real world, those IDs would come from your user database.
|Example Request to Create Account||Example Response|
This call creates a new account or updates an existing one, so it's safe to run multiple times. Now that account
"abc123" has been created, we can create a user in that account using the Create or Update a User API call.
In this example, we're creating a user for someone named "Bob Testerson".
|Example Request to Create User||Example Response|
When creating a user the field
referralCode is optional. When the field is left empty the system will automatically generate a Referral Code based on the
lastName fields. You can also choose to generate your own Referral Code by filling out
referralCode, as shown above.
Engage the user and help them make a referral
When a user is created in SaaSquatch, they are automatically generated unique share links that they can share to refer their friends. Since we want our users to share these links, we're going to look them up from SaaSquatch using the Lookup Share Links API call and show them on our website when someone has logged in.
|Example Request to Lookup Share Links||Example Response|
Attribute referred users
When someone signs up after being referred, they need to be attributed as a referral and connected to the person that referred them. For this example, we're creating users in SaaSquatch the first time that they log in, and the attribution of referrals would happen as soon as they're identified.
For this example, our friend "Bob Testerson" referred his friend "Erik Squatchy" by sharing his referral link. Erik clicked on that referral link and signed up for a trial account. This new account has an account ID
"def456" and user ID that are the same.
To track Erik we use the same Create or Update an Account API call used when we identified Bob, but in this case since Erik was referred we include the field for
referral.code to connect the referral with Bob.
|Example Request to Create a Referred Account||Example Response to Create Account|
By filling out the
referral.code this account is linked to Bob, the user that made this referral. We also set the
TRIAL because Erik signed up for a Trial account. Erik will show up in the Bob's widget as a referral and a Trial user. Later if Erik completes his trial, we will need to update his account again using this API call and set the
PAID so we can complete the conversion step.
After creating the account, add the referred user to this account by using the Create or Update a User API call. Use the
account_id from our previous step to attach this new user to the account we just created.
|Example Request to Create a Referred User||Example Response|
The new user is created and linked back to its referrer through the
referral.code stored in the Account.
Convert the referred user when they sign up for a PAID subscription
When someone pays for a subscription at the end of their trial, it's vital to inform SaaSquatch about this account upgrade so the user who made the referral can receive their reward for successfully referring a friend. We call this step "Conversion".
In this example, the referral program is set up with a double-sided incentive, so the referred user that is paying for subscription also gets a discount on their first bill for being referred. To fulfill this reward use the List reward balances API call when the user upgrades to check if they have been referred and deserve any discount. This call returns all the rewards that are linked to the
To apply the reward, use the
totalDiscountPercent and use it to calculate to amount that need to be discounted from the first bill. Then, apply this amount to their bill. Every payment system has different tools for applying this credit, and it's up to you to decide the right way to do this. This is the fulfillment step for the referred user.
|Example Request to Lookup Rewards for a Referred Account||Example Response|
Note: In this scenario
referredDiscountPercent can be used, but this can cause a problem later when a user downgrades their account and later decides to upgrade again. This user would not receive the discount he or she earned by referring users if we calculated the bill based on the on
After the account upgrade is complete, update the
PAID to complete the conversion using the Update an Account API call.
|Example Request to Update Referred Account Conversion||Example Response|
Fulfill the earned reward for the referrer
The referrer successfully referred their friend who signed up to
PAID subscription. Hand out the referrer's reward by applying the percentage discount on their next bill.
Before the next billing run check the discount percentage for each user by using the List reward balances API call. This API call returns all the rewards that are linked to the
accountId that was used in the request.
|Example Request to Lookup Rewards for a Referrer's Account||Example Response|