Recurly Integration Install Guide

🔗 Configure Recurly

Test tenant vs. Live tenant - Your SaaSquatch program provides both a live and test tenants. Test tenants can be used in conjuction with a Recurly Sandbox account to test payments, subscriptions, and reward automation 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 integrations page and locate the Recurly integration and press "Enable Recurly".
4. Paste in your Recurly API key that you just copied, and press save.

Repeat this process for your live tenant when you are ready to go live.

🔗 Choose which reward units to automate

The Recurly integration can automatically create credit line items in Recurly when rewards are created in SaaSquatch. By default base currency units such as USD, EUR and CAD are fulfilled. If your programs are using multiple monetary units, such as cash vs credit, you can configure Recurly to only fulfil one of those units.

1. Click "Add a reward unit"
2. Select Custom for Reward Units
3. Enter a Unit ID from your reward catalog
4. Press Save

After a reward unit is configured then any new rewards created in that unit will be automatically fulfilled.

• Only rewards with "type": "CREDIT" and a configured unit are automatically fulfilled.
• Rewards with "unit": "CENTS" are treated as USD.

🔗 Set up Recurly to forward Webhooks to SaaSquatch

SaaSquatch uses Recurly Webhook Events as triggers for your program's reward and email automation. Recurly supports multiple Webhook Endpoints which allows you to simultaneously receive webhooks in your other software while also sending them to SaaSquatch. Add SaaSquatch as a webhook endpoint by adding our URL into your Recurly portal.

1. Head to the integrations page and locate the Recurly integration.
2. Copy the URL labelled Push Notification URL (it should look like https://recurly.integrations.saasquatch.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 in step 2 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.

• The Recurly integration will attempt to create users that don't exist in SaaSquatch using the Recurly <account_code> as the user's id and accountId. This field is the Account Code field when looking at a user on the Recurly website.
• Recurly webhooks can potentially be recorded multiple times. Recurly doesn't support sending IDs along with Webhooks, so there is a chance that it will be received and logged twice

🔗 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. Make sure that the Referrer is created as a User in SaaSquatch. Use the Recurly <account_code> as the user's id and accountId.
3. Make sure that the Referred User is created as a User in SaaSquatch and attributed as a referral of the Referrer
4. Create an account for the Referred User in Recurly. Use the Recurly <account_code> as the user's id and accountId. If the Recurly account is created before the Referred User and referral are created, then the automatic reward fulfillment and tracking will not work.
5. Create a subscription in Recurly for the Referred User.

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

Assumptions:

• You have completed the Recurly setup steps.
• Your program rules are configured to trigger based on one of the supported webhooks types.
• The reward unit used in your programs is configured for automatic fulfillment.

🔗 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.
• Event tracking and reward fulfilment rely on Recurly <account_code> matching a user's id and accountId.
• The reward for are applied as a line item on a pending or existing invoice. This is 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.

🔗 Compatible Rewards

Looking to run a referral program with Recurly as your payment provider and an arbitrary reward type like points or swag? The Recurly integration only supports monetary reward fulfillment in a specified currency.

🔗 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.

🔗 Supported Webhooks

Recurly webhooks are sent as XML, but they are processed and stored in SaaSquatch as User Events as JSON.

For example, a Recurly closed_invoice_notification notification;

 <?xml version="1.0" encoding="UTF-8"?>
 <closed_invoice_notification>
   <account>
      <account_code>1</account_code>
      <username nil="true" />
      <email>verena@example.com</email>
      <first_name>Verana</first_name>
      <last_name>Example</last_name>
      <company_name nil="true" />
  </account>
  <invoice>
      <uuid>ffc64d71d4b5404e93f13aac9c63b007</uuid>
      <subscription_id nil="true" />
      <state>collected</state>
      <invoice_number_prefix />
      <invoice_number type="integer">1000</invoice_number>
      <po_number />
      <vat_number />
      <total_in_cents type="integer">1100</total_in_cents>
      <currency>USD</currency>
      <date type="datetime">2014-01-01T20:20:29Z</date>
      <closed_at type="datetime">2014-01-01T20:24:02Z</closed_at>
      <net_terms type="integer">0</net_terms>
      <collection_method>manual</collection_method>
  </invoice>
</closed_invoice_notification>

Then Recurly integration will track it as a user event in JSON format with value:

{
  "account": {
    "account_code": "1",
    "username": null,
    "email": "verena@example.com",
    "first_name": "Verana",
    "last_name": "Example",
    "company_name": null
  },
  "invoice": {
    "uuid": "ffc64d71d4b5404e93f13aac9c63b007",
    "subscription_id": null,
    "state": "collected",
    "invoice_number_prefix": "",
    "invoice_number": 1000,
    "po_number": "",
    "vat_number": "",
    "total_in_cents": 1100,
    "currency": "USD",
    "date": 1388607629000,
    "closed_at": 1388607842000,
    "net_terms": 0,
    "collection_method": "manual"
  }
}

The Recurly integration will only forward payment and invoice webhooks to SaaSquatch. These are tracked as events on the users, and can be looked up in the SaaSquatch admin portal and via the GraphQL API.

Recurly Webhook Type	Processed
new_credit_invoice_notification
processing_credit_invoice_notification
closed_credit_invoice_notification
voided_credit_invoice_notification
reopened_credit_invoice_notification
updated_credit_invoice_notification
scheduled_payment_notification
processing_payment_notification
successful_payment_notification
failed_payment_notification
void_payment_notification
new_credit_payment_notification
successful_refund_notification	ignored
new_account_notification	ignored
updated_account_notification	ignored
canceled_account_notification	ignored
billing_info_updated_notification	ignored
billing_info_update_failed_notification	ignored
new_shipping_address_notification	ignored
updated_shipping_address_notification	ignored
deleted_shipping_address_notification	ignored
new_item_notification	ignored
updated_item_notification	ignored
deactivated_item_notification	ignored
reactivated_item_notification	ignored

🔗 Classic Referral Programs

If you are using a classic referral program then you may need the classic recurly integration documentation.