Recurly
Trigger referrals on new Recurly charges or automatically apply Recurly coupons or credits as rewards.
Last updated
Trigger referrals on new Recurly charges or automatically apply Recurly coupons or credits as rewards.
Last updated
Note: The Recurly integration is only available to users on the GrowSurf Business plan or higher.
When you connect your Recurly account to your GrowSurf campaign and enable Referral Trigger, GrowSurf will automatically detect and trigger referrals on new Recurly charges.
GrowSurf will check if the Recurly customer's email address matches a GrowSurf participant's email address. If a match is found, then a referral will trigger, giving referral credit to the referrer and unlocking any rewards, if applicable. If a referral has already been triggered (and referral credit already was awarded), then nothing else will happen because referral credit can only be awarded once.
Here's how to set up Recurly referral triggers:
Important Note: Unless your campaign is configured to add participants automagically (see image), you'll need to make sure you first call JavaScript growsurf.addParticipant() or REST API /POST Add Participant to add new participants.
You must first select a default currency for your GrowSurf campaign in order to use Recurly. Your default currency determines whether Recurly coupons or credits can be applied to your Recurly subscriptions. For example, if your default currency is USD, then the coupon or credit you set up can only be redeemed for Recurly subscriptions using USD.
Step 1: In Campaign Editor > 4. Options > Integrations, open the Recurly integration card and enter your Recurly API key and test API key.
For the "Enter your Recurly API Key" field, please enter an API key from your production Recurly instance
For the "Enter your Recurly Test API Key" field, you can use the same API key as above, otherwise if you have a separate Recurly instance you use just for development/testing purposes, please enter that one.
Step 2: By default, GrowSurf activates Referral Trigger upon connection. To establish a new Recurly webhook, access your Recurly dashboard and navigate to Integrations > Webhooks. Then, create a new endpoint by clicking on the Configure button and selecting New Endpoint. Input the webhook URL displayed in the GrowSurf Recurly integration as the endpoint URL. Generate a username and password for your endpoint and proceed to the GrowSurf Recurly integration to input the username and password for your Recurly webhook.
Important Note: At a minimum, the following notifications should be selected for your Recurly webhook:
account.updated
payment.refunded
payment.succeeded
To configure the event notifications for your Recurly webhook, navigate to Integrations > Webhooks > Configure, then click Options for the webhook you want to configure and select Edit. Scroll to the Notifications section, select the appropriate notification(s), then click the save button.
(Optional) Step 3: You can add a referral trigger hold period by toggling the Show advanced settings section.
Note: The referral trigger hold period is useful for preventing fraud and helps minimizes losses due to refunds and chargebacks. During this hold period, if there is a refund or chargeback, the referral trigger will be cancelled completely.
Our Recurly integration comes with a test mode that allows you to test triggering referrals without using live payments. When you toggle Test Mode on, GrowSurf will also process all test mode payments made in your Recurly account.
Important note: When you go live with your campaign, please make sure to switch back to live mode. Otherwise, referrals will not be triggered in live mode while test mode is enabled.
When testing out the Recurly Referral Trigger integration, make sure to view participants' activity logs for details that can help you troubleshoot any issues.
If you were expecting a referral to be triggered in live mode, double-check that you do not have test mode enabled.
When a GrowSurf participant unlocks a reward, apply a coupon or credit to a Recurly customer subscription.
You must first select a default currency for your GrowSurf campaign in order to use Recurly. Your default currency determines whether Recurly coupons or credits can be applied to your Recurly subscriptions. For example, if your default currency is USD, then the coupon or credit you set up can only be redeemed for Recurly subscriptions using USD.
Step 1: In Campaign Editor > 4. Options > Integrations, open the Recurly integration card and enter your Recurly API key and test API key.
For the "Enter your Recurly API Key" field, please enter an API key from your production Recurly instance
For the "Enter your Recurly Test API Key" field, you can use the same API key as above, otherwise if you have a separate Recurly instance you use just for development/testing purposes, please enter that one.
Step 2: Once connected, GrowSurf will have Referral Trigger enabled by default. You can disable it if you only want to automate rewards using Recurly Coupons/Credits.
Step 3: Click the Coupons/Credits tab and connect a reward(s) to Recurly by clicking the Connect a Reward button.
Note: When you connect to Recurly, Referral Trigger will be enabled by default. If you are triggering referrals another way, disable the toggle in the Referral Trigger tab.
Click on either Coupon or Credit. If coupon is selected, enter the details of the coupon including the name, type, and discount. You can also click Show advanced coupon settings to view more customization settings.
Advanced feature tip: Issue different reward amounts by using dynamic rewards
Dynamic rewards let you offer different reward values based on specific attributes of the referred friend (such as the pricing plan they signed up for) or referrer (such as their partner status).
For example, you can award $50 in credits to winners when their referral signs up for your base plan or $100 in credits when they sign up for a higher-costing plan.
Note: By default, coupons are recommended. However, if you want rewards to be stackable (e.g, $10 off for every referred friend), you will want to use credits.
If credit is selected, enter the details of the credit including the description and credit amount, which is applied to the customer's promotional credits every time this reward is unlocked.
Then hit Save. Now, anytime this reward is unlocked by a winning participant, a Recurly coupon or credit will also be applied to the Recurly subscription associated with the GrowSurf participant email address.
With double-sided rewards, you have full flexibility in choosing who gets the coupon or credit reward: (1) just the referrer, (2) just the referred person, (3) or both referrer and referred person.
Once you save the reward, the Recurly Coupons/Credits integration is enabled and will issue coupons or credits anytime a reward is approved.
Our Recurly integration comes with a test mode that allows you to test coupons/credits based on the test API key that you initially provided. This helps you keep development/testing separate from production. When you toggle Test Mode on, GrowSurf will apply coupons/credits only to your Recurly using your test API key.
To enable test mode, toggle the Test Mode switch at the bottom-right, then connect a reward(s).
Please note that the rewards you connect to while Test Mode is enabled are completely separate from those you connect to in live mode.
Important note: When you go live with your campaign, please make sure to switch back to live mode. Otherwise, coupons/credits will not be issued in live mode while test mode is enabled.
If there is an issue with applying Recurly coupons or credits, GrowSurf will send out a notification email to the campaign owner. The issue will also be stated in the participant's detail page when you view their reward or when you view the participant's activity logs.
Here are some common reasons why there may be failures:
The customer with the associated GrowSurf participant email address does not exist in Recurly (please make sure to check live or test mode depending on if you have toggled on Test Mode in the GrowSurf Recurly integration)
If dynamic reward rules are enabled for the Recurly reward, there may have been no matching rule found.
If you were expecting a coupon/credit to be applied in live mode, double-check that you do not have test mode enabled.
If there was a failure, you will need to manually issue the Recurly reward from your Recurly dashboard.
If you have manual reward approval enabled for your campaign: Recurly coupons/credits will only be issued to the winner(s) only after you approve the reward.
If the referral was triggered recently (or if the reward was approved recently), please allow for a few minutes of server processing before viewing the participant's reward from your GrowSurf admin dashboard. During this time, the data displayed for the participant's reward may not be accurate.
