Recurly Integration Install Guide

Classic only Before you can begin integrating Recurly into your SaaSquatch Program, you need to contact our Success Team so we can activate Recurly Support in your account. Please keep in mind this feature is currently only available for classic referral programs.

🔗 Configure Recurly

Test mode vs. Live mode - Your SaaSquatch program provides both a live and test mode. This test mode can be used in conjuction with a Recurly Sandbox account to test payments, subscriptions, and adding user before deploying to your production environment.

🔗 Add your Recurly API Key in the SaaSquatch Portal

We connect to the Recurly API using your Recurly API key. This allows us automatically apply discounts to users' accounts.

1. Login to Recurly and click on "Developer-> API Credentials".
2. Copy the "PRIVATE API KEY".
3. Head to the Install tab under Settings in your Portal and locate the section Recurly API Key.
4. Paste in your Recurly API key that you just copied, and press connect.

Repeat this process for your live tenant when you are ready to publish your referral program.

🔗 Set up Recurly to forward Webhooks to SaaSquatch

SaaSquatch uses Recurly Webhook Events as triggers to know when accounts need to be updated. Recurly supports multiple Webhook Endpoints which allows you to simultaneously receive webhooks while also sending them to SaaSquatch. In order to add SaaSquatch as a webhook endpoint you will need to add our URL into your Recurly portal.

1. Login to SaaSquatch and navigate to "Install" under Settings.
2. Copy the URL labelled Push Notification URL (it should look like https://app.referralsaasquatch.com/recurly/{tenant_alias}/webhook).
3. Login to Recurly and navigate to Developer > Webhooks > Configure.
4. Click New Endpoint
5. Select a name for your SaaSquatch Webhook endpoint.
6. Paste the URL you copied from the SaaSquatch Install page into the field labeled Endpoint URL.
7. Click Save Changes.

Repeat this process for your live tenant when you are ready to publish your referral program. This will require that you switch your Recurly account to production mode.

Be aware: The conversion of your Recurly account from test to production is not reversible.

🔗 Install squatch.js

Making use of our squatch.js library will allow you to surface a responsive Referral Widget for your users either on your desktop or mobile website or in your app. Through this widget your users will be able to seamlessly refer their friends.

To get up and running follow the squatch.js install guide to place the widget on your page.

🔗 Integration Flow

In order to utilize the SaaSquatch integration with Recurly, it is important to be mindful of the correct order of operations for successfully completing the referral flow from a trial to a paid referral.

The supported SaaSquatch Recurly integration flow is:

1. Make sure that the Referrer is registered in Recurly with a valid credit card and plan selected
2. Create an account for the Referred User in Recurly
3. Add a valid credit card and subscription plan to the Referred User’s Account in Recurly
   • Make sure to include the referral code from referrer as a coupon on the referred user's subscription.
4. Create a SaaSquatch account for the Referred User
5. Include their payment_provider_id parameter from their Recurly account (listed as "Account Code" under Account Information)
6. Attribute referral (the widget should automatically pick up the referral cookie)
7. As you have already included the coupon on the Referred User’s subscription, conversion will happen upon attribution in Referral SaaSquatch.
   

   Note: You only need to add the referral code as a coupon for the referred user's new subscription. Use squatch.js autofill to read the tracking cookie and pick up the referral code. Referrers will get credit for inviting their friends shown as both a value in a line item and a Note automatically applied to their invoices every month.

Result: Referral converted to paid, rewards fulfilled in Recurly, rewards redeemed in SaaSquatch.

🔗 Key Considerations

• The conversion process may take time to propagate from Recurly to SaaSquatch depending on the load on Recurly's system and the frequency of them sending out updates.
• Discounts or credits being applied to a user’s Recurly invoice should have an RS_ appended at the beginning.
• Attempting to convert a referral using account_status: 'PAID' in your squatch.js calls will have no effect when your program is configured for a payment provider integration. Only a non-zero, non-trial subscription applied to a customer's current or pending invoice will convert the referral and release the referrer reward.
• The reward for the referrer (generated once the referral is converted) is applied as a line item on a pending or existing invoice. This due to Recurly’s limitations on how account credits can be applied to customers. Recurly only allows account credits to be applied as line items, and line items can only be applied to invoices. In this way Recurly has designed invoices to only be used with subscriptions.
• One-Time transactions in Recurly are processed independently of other activity on the account (including existing and pending invoices). This means that there is no way for us to interact with single charge transaction to apply any account credit before it is processed.

🔗 Compatible Rewards

Looking to run a referral program with Recurly as your payment provider and Dollar or Percentage Credit rewards? If you are interested in using this type of reward with your Recurly Referral SaaSquatch program please contact our Success Team to find out more.

Looking to run a referral program with Recurly as your payment provider and an arbitrary reward type (like points, free time, foo credits)? Recurly only supports percentage discount and credits rewards in a single specified currency. Anything beyond that (arbitrary rewards) will not be recognized by Recurly.

If you are interested in running a Referral SaaSquatch referral program with arbitrary rewards (like points, free time, foo credits) please take a look at our API referral programs. API programs are extremely flexible and support a wide range of reward types, including Percentage Discount, Dollar Credit, Free Time, and Points.

🔗 More Information

Recurly API Keys - SaaSquatch connects to Recurly, through their REST API, using an API key from your Recurly account. This lets SaaSquatch automatically apply discounts to users's accounts, making the integration extremely powerful, as well as easy and fast to connect.

You can learn more about creating and managing Recurly API keys in their documentation.