Recurly Integration Install Guide
Referral SaaSquatch's Recurly integration uses Recurly’s Push Notifications and Recurly's API to automatically track subscriptions and apply referral rewards. This guide will walk you through how to set up this integration.
Test mode vs. live mode - Your Referral 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 lets us automatically apply discounts to people’s accounts.
- Login to Recurly and click on "Developer-> API Credentials".
- Copy the "PRIVATE API KEY".
- Login to Referral SaaSquatch, on your Test Tenant go to "Install" and click "Authorize".
- 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
Referral 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 Referral SaaSquatch. In order to add Referral SaaSquatch as a webhook endpoint you will need to add our URL into your Recurly portal.
- Login to Referral SaaSquatch and navigate to "Install".
- Copy the URL labelled Push Notification URL. (it should look like
- Login to Recurly and navigate to Developer -> Webhooks -> Configure.
- Click New Endpoint
- Select a name for your SaaSquatch Webhook endpoint.
- Paste the URL you copied from the SaaSquatch Install page into the field labeled Endpoint URL.
- 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.
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.
In order to utilize the Referral 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 Referral SaaSquatch Recurly integration flow is:
- Register the Referred User in Recurly
- Make sure to include the referral code from referrer as a coupon on the referred user's subscription.
- Register the Referred User in Referral SaaSquatch.
- Make sure to include
payment_provider_idparameter from their Recurly account.
- Make sure to include
- Convert the referral through Recurly.
- This conversion happens when a non-zero, non-trial subscription is applied to the Referred User’s invoice.
- Wait for the conversion to propagate from Recurly to Referral SaaSquatch (this process may be instantaneous but also may take longer depending on the load on Recurly and the frequency of them sending out webhooks).
- The conversion process may take time to propagate from Recurly to Referral 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.
Dollar Credit Rewards
Looking to run a referral program with Recurly as your payment provider and Dollar Credit rewards?
This reward type is currently in Beta for our integration with Recurly. If you are interested in using this type of reward with your Recurly Referral SaaSquatch program please contact support 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. Please checkout our docs on API programs and our guides for each of these reward types.
- Recurly API Keys - We connect to the Recurly API using your Recurly API key. This lets us automatically apply discounts to people’s accounts. While this makes setting up our integration extremely powerful, easy and fast, sharing API keys is not officially supported by Recurly.
Check out our Common Pitfalls Guide