FirstPromoter allows you to set any type of rewards for your promoters, depending on what motivates them. For example if you have a credit based pricing, you can give 10 credits for each customer they bring in.
With the exception of monetary rewards, you need to make the rewards your promoters earned visible in your application and attributed to their user accounts on your system.
To achieve this you need to use our Campaign Webhooks feature, which will send notifications to your server each time a promoter is created, gets rewards or payment/fulfilment is made.
Step 1) Add webhook URL to the campaign
Create a webhook POST route for FirstPromoter in your application, like https://mywebsite.com/firstpromoter-webhook-url and add the URL in the Webhook URL field in the Campaign Settings tab(see below).
Step 2) Assign a customer/user ID to the promoter when he/she signs up to the referral program
Note: This step can be skipped if you use the API to create promoters. More details here.
Grab the promoter page link from FirstPromoter campaigns section(which may look like "https://mysubdomain.firstpromoter.com")
Create a function to append your logged in user/customer ID from your system to that link as "cust_id" query parameter.
Here's an example of passing parameters to promoter sign up page, including "cust_id"(customer ID) parameter:
https://mysubdomain.firstpromoter.com?email=john%40email.com&referral_id=john&promo_code=JOHN30&first_name=John&cust_id=34254
You can see that you can append multiple fields to that url which will pre-fill the promoter sign up fields - a good way to reduce friction. The most important is "cust_id" parameter though.
Use that function to generate a link and place it on your app dashboard or other places visible to your users. You can call it "Refer a friend and get 1 free month" or whatever feels appropriate.
When your users sign up to the referral program, the "cust_id" parameter will be passed along and we'll have a way to match the promoter details from webhooks to your customer.
Step 3) Create the logic to handle the webhooks
You will need to handle 1 or 2 types of webhooks, depending on your campaign settings:
If you set only rewards per referred sale when you created/edited the campaign, follow a).
If you also set an "offer" for promoter's friends and followers, follow b).
a) One-side, non-monetary rewards, only to promoter
Only the "fulfilment_pending" webhook is necessary for this:
Check the payload format of fulfilment_pending webhook.
Create the procedure in your system to handle the webhook call with a condition to execute only if the event type from the payload is "fulfilment_pending"
Use the "cust_id"(which was passed on promoter sign up) value from the webhook to find the user/customer to reward and apply the reward. You also have an "amount" value in case you set different rewards for different campaigns or promotions.
It's up to you how you apply the rewards to the users, for example, for Stripe you can apply a negative invoice item or a 100% discount code to the Stripe invoice in order to give a free month.
Return a 200 status code if everything is successful. Return 2xx(except 200), to skip the fulfilment(it will remain in pending state) and other status in case of error/you want the webhook to be retried later.
b) Two-sided, non-monetary rewards, to both promoter and person referred
For this, you need "lead_signup" and "fulfilment_pending" webhooks.
First we will handle "lead_signup" to apply the offer to promoter "friend", the person referred by the promoter:
Check the payload format for lead_signup webhook.
Create a procedure in your system to handle the webhook call with a condition to execute only if the event type from the payload is "lead_signup".
Check if promotion['status'] is equal to "offer_running", otherwise exit/return(skip to step 6)
Use the "uid" or "email" value to find the user in your system.
Apply the offer to your user. promotion['current_offer'] JSON can give you more information about the offer to apply, including amount and unit/type.
Return a 2xx status code if the everything is successful. Something else to retry the webhook later.
Now we will handle "fulfilment_pending" to apply the reward to the promoter:
Check the payload format for fulfilment_pending webhook.
Create the procedure in your system to handle the webhook call with a condition to execute only if the event type from the payload is "fulfilment_pending"
Use the "cust_id"(which was passed on promoter sign up) value from the webhook to find the user/customer to reward and apply the reward. You also have an "amount" value in case you set different rewards for different campaigns or promotions.
It's up to you how you apply the rewards to the users, for example, for Stripe you can apply a negative invoice item or a 100% discount code to the Stripe invoice in order to give a free month.
Return a 200 status code if everything is successful. Return 2xx(except 200), to skip the fulfilment(it will remain in pending state) and other status in case of error/you want the webhook to be retried later.
There are some other notifications you can use for different use cases:
when a promoter signs up and is accepted to a campaign, it sends a promoter_accepted notification.
when a lead signs up for trial, it sends a lead_signup notification. This is mostly used when you give and offer like free credits to the user who was referred by a promoter.
when a reward is attributed to a promoter, it sends a reward_created notification.
when a reward is approved and sent to fulfilments, it sends a fulfilment_pending notification.
when a fulfilment is marked as completed, it sends a fulfilment_completed notification.
If some of the webhooks are not fired, it means they are probably disabled for your account and you need to contact us to enable them.