Recurly for Salesforce

To improve process efficiency and eliminate duplicate data entry, the Recurly for Salesforce integration seamlessly links your Recurly account directly to your Salesforce Organization. The Recurly for Salesforce integration automatically updates Account, Plan, Subscription, Invoice, Transaction, and Line Item data.

Here is a demonstration of how the integration works: Recurly for Salesforce integration demo

Salesforce users are able to create and manage customer account and subscription information from within Salesforce, and the changes can be synced back to Recurly. To learn more about Salesforce, check out their best practices.

Overview

This page describes the out-of-the-box Recurly for Salesforce integration. This feature is available on the Recurly Professional and Elite plans.

Here is a demonstration of how the integration works: Recurly for Salesforce integration demo

  • Recurly for Salesforce integrates Recurly with Salesforce Sales Cloud
  • The integration is compatible with Salesforce Lightning and Classic UIs
  • Up to 10 Recurly sites can be synced with one Salesforce organization
  • The integration works with Salesforce sandbox or production sites
  • The integration works with Recurly sites in sandbox or production mode
  • We recommend that, before integrating either Recurly or Salesforce production instances, you open a Recurly site in sandbox mode and test with non-production data synced to a Salesforce sandbox site
  • The integration does not work with Salesforce Professional edition, SalesforceIQ, or Developer Orgs
  • The integration does not currently support linking Recurly data with the Salesforce Contact object

❗️

Salesforce custom code, workflows, or triggers can be used alongside the integration but will not be supported by Recurly

Integration Components

When you install the integration, the following custom objects will be added to your Salesforce organization:

Additionally, a number of custom fields and related objects will be added to the following native Salesforce objects in your Salesforce organization:

The below data model shows how your key data in Recurly is synchronized with these custom Recurly objects and data fields in Salesforce. Each of these connections is covered in more detail below. Detailed instructions for installing and configuring the integration will be provided when the feature is enabled on your Recurly account.

Recurly for Salesforce data modelRecurly for Salesforce data model

Recurly for Salesforce data model

What Does and Doesn't Sync Back to Recurly?

The main objects that are available to be edited from within Salesforce are Recurly Accounts and Recurly Subscriptions. Select fields on the Recurly Invoices object can be edited in Salesforce and synced back to Recurly, as well. In addition, new Recurly subscriptions and accounts can be created from the Recurly Account custom object or the native Opportunity object in Salesforce. More details on the complete capabilities available are captured below.

The following objects are editable in Salesforce (depending on your configuration) but will not have changes synced back to Recurly:

  • Recurly Plans
  • Recurly Add-Ons
  • Recurly Items
  • Recurly Line Items
  • Recurly Transactions

Syncing custom fields from Recurly to Salesforce

If you want to sync back custom fields from Accounts, Items, and/or Subscriptions, you can set that up in the Recurly Admin screen. It will sync back the data based on your mapping to custom fields on the respective Recurly objects in Salesforce. More details here: Sync Custom Field Documentation

Recurly Accounts

Recurly synchronizes your accounts with the following fields in the Recurly Accounts custom object within Salesforce:

  • Account Code
  • Company
  • Status
  • First Name
  • Last Name
  • Username
  • Email
  • CC Email
  • Account ID
  • VAT Number
  • Tax Exempt
  • Account Address
  • Account Payment Information
  • Card Type
  • First 6 Digits of CC
  • Last 4 Digits of CC
  • CC Valid?
  • CC Exp Month
  • CC Exp Year

On the Recurly Account page, you can view the Recurly Subscriptions, Recurly Invoices, Recurly Line Items, and Recurly Transactions related to each of these accounts once they have been synced from Recurly. If you create Recurly subscriptions directly from your Salesforce opportunities, you can also view the Opportunities related to each account. If your Recurly accounts are being linked to Salesforce accounts, you can see the associated Salesforce account in a dedicated field.

Editing an Account

Once these records are in Salesforce, users can update the following fields to be synced back to Recurly via the Edit button on the Recurly Account record:

  • Company
  • First Name
  • Last Name
  • Email
  • CC Email
  • VAT Number
  • Tax Exempt

Payment Information

Payment information fields can only be added or updated via the Add Payment Information button on the Recurly Account page. This form uses Recurly.js to securely submit credit card data from Salesforce to Recurly in a PCI-compliant manner. Once entered in Salesforce, they will be sent to Recurly and the card will be re-authorized. If payment information was already populated on the Recurly account, it will be overwritten by the newly submitted payment details.

Collecting payment information securely within SalesforceCollecting payment information securely within Salesforce

Collecting payment information securely within Salesforce

🚧

Using the Edit button on the Recurly Account and editing the Payment Information fields will not sync these changes back to Recurly. You need to use the method above as it is compliant with Payment Card Industry (PCI) standards.

Deleted Accounts

If a Recurly Account is deleted in Salesforce, its record ID is captured in a custom object labeled Deleted Accounts. When accounts are synced with Salesforce, a check is made to see whether the account ID has been captured in a Deleted Account object. If it has, the account is not synced into Salesforce.

When an account is deleted in Recurly, its status will be updated to "Inactive" in Salesforce. “Deactivate” and “Reactivate” buttons are provided on the Recurly Account page. These buttons allow a user to deactivate an active Recurly account, or reactivate an inactive Recurly account.

🚧

Deactivating an account will cause the Billing Information for the account to be deleted and any subscriptions on the account will be canceled

Recurly Plans

Recurly synchronizes your plans with the following fields in the Recurly Plans object within Salesforce:

  • Plan Name
  • Plan ID
  • Plan Code
  • Status
  • Description
  • Interval Length
  • Recurring Charge Amount
  • Setup Fee
  • Tax Collection

On the Recurly Plan page, you can also view the Add Ons and Subscriptions related to each one of these plans once they have been synced from Recurly. If your Recurly plans are being linked to Salesforce products, you can see the linked Salesforce product in a dedicated field.

This sync is one-way; plans created or edited within Salesforce will not be synced with Recurly. However, if your Recurly plans are being linked to Salesforce products, the Linked Product field can be edited within Salesforce for manual object linking. If the Linked Product field is cleared, this linkage will be reinstated during the next regular sync. If the link is edited to reflect a different Salesforce product, then that product will be updated to match the Recurly Plan during the next regular sync.

When a plan is deleted in Recurly, its status will be updated to "Inactive" in Salesforce.

Recurly Add Ons

Recurly synchronizes your plan add-ons with the following fields in the Recurly Add-Ons object within Salesforce:

  • Add-On Name
  • Add-On ID
  • Code
  • Status
  • Price
  • Tier Type

On the Recurly Add On page, you can also view the Line Items and Subscriptions related to each one of these add-ons once they have been synced from Recurly. The Plan on which each add-on resides is displayed in a dedicated field. If your Recurly add-ons are being linked to Salesforce products, you can see the linked Salesforce product in another dedicated field.

This sync is one-way; add-ons created or edited within Salesforce will not be synced with Recurly. However, if your Recurly add-ons are being linked to Salesforce products, the Linked Product field can be edited within Salesforce for manual object linking. If the Linked Product field is cleared, this linkage will be reinstated during the next regular sync. If the link is edited to reflect a different Salesforce product, then that product will be updated to match the Recurly Add On during the next regular sync.

When an add-on is deleted in Recurly, its status will be updated to "Inactive" in Salesforce.

Recurly Items

Recurly optionally synchronizes the items in your catalog with the following fields in the Recurly Items object within Salesforce:

  • Item Name
  • Item Code
  • Item ID
  • External SKU
  • Accounting Code
  • Description
  • Item State / Status
  • Unit Amount / Default Price
  • Tax Collection

On the Recurly Item page, you can also view the Add-Ons, Subscriptions, and Line Items related to each of these items once they have been synced from Recurly. If your Recurly items are being linked to Salesforce products, you can see the linked Salesforce product in a dedicated field.

This sync is one-way; items created or edited within Salesforce will not be synced with Recurly. However, if your Recurly items are being linked to Salesforce products, the Linked Product field can be edited within Salesforce for manual object linking. If the Linked Product field is cleared, this linkage will be reinstated during the next regular sync. If the link is edited to reflect a different Salesforce product, then that product will be updated to match the Recurly Item during the next regular sync.

When an item is disabled in Recurly, its status will be updated to "Inactive" in Salesforce.

If you disable the syncing of items, no items will be synced with Salesforce.

Recurly Subscriptions

Recurly synchronizes your subscriptions with the following fields in the Recurly Subscriptions object within Salesforce:

  • Plan Name
  • Trial Length
  • Currency (custom currency field)
  • Price
  • Quantity
  • Coupon Code
  • Collection Method
  • Customer Notes (defaults to notes from account page)
  • Estimated MRR
  • Current Term
  • Renewal Term (if applicable)

On the Recurly Subscription page, you can also view the Add-Ons, Invoices, Transactions, and Line Items related to each of these subscriptions once they have been synced from Recurly. You can view the Recurly and Salesforce accounts linked to the subscription in dedicated fields. If you create Recurly subscriptions directly from your Salesforce opportunities, you can also view the opportunity associated with each subscription in a dedicated field.

Creating a New Subscription From a Recurly Account

From a Recurly Account object in Salesforce, click New Recurly Subscription. You will be presented with a custom Visual Force page that will allow you to enter plan details, amount, add-ons, and dates just as you would within the Recurly UI.

You can choose whichever currency you like when creating the subscription.

You can also choose how many billing cycles you would like to include in the first subscription billing term, and how many in the renewal term. Even if the customer cancels, if they have been subscribed for a fixed number of billing periods their first term, the subscription will continue to bill until the end of the term. See here for more information on subscription terms.

📘

It is not currently possible to add multiple subscriptions to Recurly via a single action within Salesforce.

Creating a New Subscription From a Salesforce Opportunity

If enabled, the integration can create new subscriptions in Recurly from closed-won opportunities in Salesforce. See full details on this process below.

Editing a Subscription

To edit a subscription, click Manage Subscription Plan from the Recurly Subscription object. You will be given a number of options of fields to edit. Including the ability to extend the start date of a Future dated Subscription.

🚧

Using the Edit button on the Recurly Subscription and editing the subscription details will not sync these changes back to Recurly. We recommend that administrators hide this button as it is confusing to users. We are not able to remove it as this is standard Salesforce functionality.

Cancelling a Subscription

To cancel a subscription, follow the Manage Subscription Plan flow to edit a subscription and click "Cancel." This will cause the subscription to cancel within Recurly as of the next renewal date.

Terminating a Subscription

To terminate a subscription, follow the Manage Subscription Plan flow to edit a subscription and click "Terminate." You will be presented with options to terminate immediately with a full refund, partial refund, or no refund.

Pausing a Subscription

To pause a subscription, click the Manage Subscription Plan button on an active subscription and click "Pause". You will be prompted with the following dialog:

The start date is the next renewal date of the subscription. Enter the number of billing cycles you would like to skip, then click Pause to pause the subscription for that period of time. The pause time period will be defined by the billing interval in Recurly (e.g. if the billing interval is monthly and you enter 1 in the Billing Cycles to Skip box, the subscription will be paused for one month from the Pause Start Date).

For more information on pausing a subscription, see here.

Pending Subscription Changes

Subscriptions with the Pending Changes box checked have changes pending at their next renewal date in Recurly. Note that any new changes made to the subscription (subscription change, cancellation, or termination) will delete these pending changes in Recurly.

📘

You cannot see which changes are pending in Salesforce. In order to see which changes are pending, please log into Recurly and view the subscription there.

Estimated MRR

Recurly offers the option to estimate the monthly recurring revenue of a subscription through the Estimated MRR field. This field is meant to help you quickly find valuable subscribers within your Salesforce account.

Because of the complexities involved in accurately computing MRR and the fact that different businesses have different requirements for this field, we recommend that you use this field only for estimation purposes and do not rely on the field for business metric reporting. The MRR reporting within Recurly Analytics is much more accurate than in the Recurly for Salesforce package.

Recurly Invoices

Recurly synchronizes your invoices with the following fields in the Recurly Invoices object within Salesforce:

  • Invoice Number
  • Invoice ID
  • Type
  • Status
  • Currency
  • Total
  • Discount
  • Tax Amount
  • Due Date
  • Recurly Account
  • Subscription ID
  • Collection Method
  • PO Number
  • Net Terms (the number of days after an invoice is issued before the invoice is due)
  • Customer Notes
  • VAT Number
  • Total Amount Outstanding (the invoice balance for invoices before the credit invoices feature was enabled; available when Type = legacy)
  • Balance (the invoice balance for invoices after the credit invoices feature was enabled; available when Type = charge or credit)

On the Recurly Invoice page, you can also view the Transactions and Line Items related to each of these invoices once they have been synced from Recurly.

Editing an Invoice

Beginning in version 2.24, Recurly supports editing select invoice elements from within Salesforce. If you modify the following fields in Salesforce via the Edit button, the update will be reflected in Recurly:

  • PO Number
  • Net Terms (enter a number to change the Due At date; e.g. if the invoice was issued on January 1 and you enter 10, the invoice will be due on January 11)
  • Customer Notes

Recurly Line Items

Recurly optionally synchronizes your invoice line items with the following fields in the Recurly Line Items object within Salesforce:

  • Line Item ID + Date/Time
  • Type
  • State
  • Origin
  • Description
  • Tax Code
  • Start date
  • End Date
  • Currency
  • Unit Amount
  • Quantity
  • Amount
  • Discount
  • Tax
  • Refund
  • Accounting Code
  • Plan Code

On the Recurly Line Item page, you can also view the Recurly Account, Salesforce Account, Subscription, Plan, Add-On, Item, and Invoice related to each of these line items in dedicated fields.

This sync is one-way; line items created or edited within Salesforce will not be synced with Recurly. If you disable the syncing of line items, no line items will be synced with Salesforce.

Recurly Transactions

Recurly optionally synchronizes your payment transactions with the following fields in the Recurly Transactions object within Salesforce:

  • Transaction Name: Recurly ID + Date/Time of Transaction
  • UUID
  • Type
  • Status
  • Currency
  • Amount
  • Account ID
  • Origin
  • Status
  • Recurly Invoice
  • State
  • Payment Information (address)
  • Gateway ID
  • Message
  • Approval Code
  • Gateway Reference

On the Recurly Transaction page, you can also view the Recurly Account, Salesforce Account, Subscription, and Invoice related to each of these transactions in dedicated fields.

This sync is one-way; payment transactions created or edited within Salesforce will not be synced with Recurly. If you disable the syncing of transactions, no transactions will be synced with Salesforce.

Salesforce Accounts

Recurly supports the ability to link the Recurly Accounts object with the native Salesforce Accounts object. This functionality is optional and allows you to do reporting on the linked objects in your org. If enabled, Recurly creates the following fields on the Salesforce Accounts object for reporting purposes:

  • Total Payments Sum: the total amount of payments against linked Recurly accounts (Note that this will not be populated if you turn off payment syncing to Salesforce)
  • Total Invoices Sum: the total amount of invoices against linked Recurly accounts
  • Total Amount Outstanding: the total amount of invoices outstanding against linked Recurly accounts
  • Average Last 3 Invoices: the average of the last three invoices from Recurly
  • Plan Name: the name of the most recently updated plan to which the account was subscribed
  • Past Due Invoice: boolean field, will be set to TRUE if the account has an invoice that is past due
  • In Trial: boolean field, will be set to TRUE if the account has a subscription that is in trial status
  • Active Subscriber: boolean field, will be set to TRUE if a linked Recurly account has an active subscription. If the subscription is set to future or will cancel, this field will be set to FALSE.
  • Billing Address: In the integration setup, we offer the option to sync the billing address from your Recurly accounts to the linked Salesforce accounts. If you enable this option, the billing address from the Recurly account that is linked to a Salesforce account will be populated in this field. (Note that we recommend that you use a text field for the State/Province field on the Salesforce account, as opposed to a picklist)

📘

The above fields are populated with a job that runs overnight, so note that they will not be available immediately after data is synced

On the Account page, you can also view the Recurly Accounts, Recurly Subscriptions, and Recurly Invoices related to each of these Salesforce Accounts once they have been synced from Recurly.

Salesforce Products

Recurly allows you to sync Recurly Plans, Recurly Add Ons, and Recurly Items with the native Salesforce Products object. You can choose to either link your Recurly offerings with existing products in Salesforce or create a new linked product for each Recurly offering. This functionality is optional and allows you to access your Recurly offerings anywhere Products are used in your Salesforce flows, such as on Opportunities. If enabled, Recurly populates the following fields on the Salesforce Products object:

  • Product Name: populated with Plan Name, Add On Name, or Item Name as applicable
  • Product Code: populated with Plan Code, Add On Code, or Item Code as applicable, prepended with "recurly_"
  • Product Description: populated with Plan Description or Item Description as applicable
  • External ID: populated with Plan Code, Add On Code, or Item Code as applicable
  • External Data Source: not controlled by Recurly, auto-populates with Plan Name, Add On Name, or Item Name as applicable
  • Display URL: populated with direct link to source object within Recurly
  • Active: boolean field, will be set to TRUE if the linked Recurly object has an active status

On the Product page, you can also view the single Recurly Plan, Recurly Add On, or Recurly Item linked to each of these Products in a dedicated field.

This sync is one-way; products created within Salesforce will not be synced with Recurly. Any Salesforce product linked to a Recurly custom object will become read-only in Salesforce; edits must be made in Recurly and will be synced to Salesforce. If you disable the syncing of products, no Recurly custom objects will be synced with Salesforce products.

Deleting Linked Recurly Objects

If a Recurly plan or add-on that's linked to a Salesforce product is deleted in Recurly, the status of the product will be updated to "inactive". If a Recurly item is disabled in Recurly, then the status of any linked Salesforce product will similarly be updated to "inactive".

Salesforce Price Books

If you choose to sync your Recurly plans, add-ons, and items with Salesforce products, you can also elect to sync the prices of these offerings from Recurly to the Standard Price Book in Salesforce. This functionality allows you to maintain pricing in one system and perpetuate changes across both systems. If enabled, Recurly populates the following fields on the Price Book Entry object related to each linked Salesforce product:

  • Product: populated with Plan Name, Add On Name, or Item Name as applicable
  • Product Code: populated with Plan Code, Add On Code, or Item Code as applicable, prepended with "recurly_"
  • List Price: populated with plan, add-on, or item Price that matches your Salesforce default currency
  • Active: boolean field, will be set to TRUE if the linked Recurly object is active and has a price set

📘

If a plan, add-on, or item does not have a price in Recurly in the default currency of your Salesforce org, then no Price Book Entry object will be created for the associated Product

This sync is one-way; price book entries created or edited within Salesforce will not be synced with Recurly. If a price book entry is modified in Salesforce, those changes will be overwritten to match the values in Recurly during the next regular sync.

If you disable the syncing of product prices, no Recurly pricing will be synced with Salesforce price books.

Deleting Linked Recurly Objects & Prices

If a Recurly plan or add-on that's linked to a Salesforce product and price book entry is deleted in Recurly, the status of the related price book entry will be updated to "inactive". If a Recurly item is disabled in Recurly, then the status of any linked price book entry will similarly be updated to "inactive".

If the price on a Recurly item that's linked to a Salesforce product and price book entry is cleared in Recurly, the related price book entry will be deleted. This logic does not apply to Recurly plans or add-ons since those prices can not be deleted, only reduced to $0.

Salesforce Opportunities

If you choose to sync your Recurly plans, add-ons, and items with Salesforce products, you can also elect to create subscriptions in Recurly directly from closed-won Opportunities in Salesforce that contain these products. This allows you to eliminate duplicate data entry and proceed seamlessly from successful opportunity closure to subscription creation.

Adding Products to Salesforce Opportunities

Before a subscription can be created in Recurly, the appropriate Recurly-based Salesforce products must be added to the opportunity. Leverage the standard Add Product flow, making sure the desired Price Book is selected (use the Standard Price Book if you're syncing product prices from Recurly to Salesforce).

For Salesforce CPQ, you can also create quotes with Recurly products and sync them over to the primary opportunity to follow the same process.

The following rules apply when adding Recurly-based products to an opportunity:

  • Products linked to Recurly add-ons can't be added without their associated plan
  • Only one product linked to a Recurly plan can be attached to an opportunity. The integration does not currently support the creation of multiple subscriptions at once.
  • If multiple Recurly sites are connected to a single Salesforce org, all products added to an opportunity must originate from the same Recurly site. In addition, if a Salesforce account is specified on the opportunity and that account is linked to a Recurly account, all products added to the opportunity must originate from the same Recurly site as the linked Recurly account.

Salesforce products not linked to Recurly offerings can still be added to your opportunities, alone or in conjunction with Recurly-based products, and they will not be subject to these rules. These products will not be passed to Recurly in any way during subscription creation.

Creating Subscriptions From Salesforce Opportunities

A few constraints exist around creating Recurly subscriptions from Salesforce opportunities:

  • The opportunity must include at least one product that's tied to a Recurly offering
  • The opportunity must have a status of Closed Won
  • The opportunity must not already have a Recurly Subscription tied to it

From an eligible opportunity in Salesforce, click Create Subscription in Recurly. You will be presented with a custom Visual Force page that will allow you to verify the plan details, amount, and any add-ons that were attached to the opportunity. You will also be able to add invoice notes, choose the billing cycles and end-of-term behavior for the first subscription billing term, and dictate renewal term behavior.

If the Salesforce account populated on the opportunity is already linked to a Recurly account with active billing information, no account-related information will be displayed or requested. If the Salesforce account populated on the opportunity is linked to multiple Recurly accounts, the subscription creation page will prompt you to select your desired Recurly account for the subscription before it can be created.

Once the subscription creation page has been submitted, a subscription will be created from the specified Recurly-based plan and add-ons. That subscription will be linked to the opportunity for easy visibility and reference, as well as to both the Recurly Account from the subscription and the Salesforce Account from the opportunity. You will no longer have the option of creating a subscription from this opportunity.

Creating One-Time Charges from Salesforce Opportunities

If you want to charge a customer a one time charge along with your plan and/or add-ons, you can now add those specific items directly to your opportunity. As a user, you can add one time charges by themselves or with plans in the opportunity. To enable this feature for the standard Opportunity flow, you will need to add ensure the sync opportunity setting is set in your Recurly Admin and the Recurly Charge Frequency field in the Opportunity Product Multi-Line Layout. More details available here: Setting up Opportunity Product Multi-Line Layout

When leveraging the Opportunity's standard Add Product flow, you will select products as you would normally but also set the Recurly Charge Frequency respectively:

  • Recurring for plans and add-ons
  • One-Time for items
Recurly Charge Frequency in ActionRecurly Charge Frequency in Action

Recurly Charge Frequency in Action

When leveraging Salesforce CPQ, you will need to do the following to create your own twin fields between the Quote Line and Opportunity Product and then copy those values over to the Recurly field. More details available here: CPQ Configuration

Once the opportunity is in closed won, you will follow the same subscription creation process as before but there will be a section specifically for the item(s) as shown below:

One-time charge during Subscription creationOne-time charge during Subscription creation

One-time charge during Subscription creation

When you click submit, there will be a Recurly Invoice created with the configuration set on that page and synced over to Salesforce for reference. The Create Subscription in Recurly button will still be available but only to create another one-time charge if required. Along with the classification of the Recurly Charge Frequency, the item has to also belong to the same subdomain as the account.

Creating / Updating Accounts From Salesforce Opportunities

If all required account and billing information can not be pulled from the Salesforce opportunity and its related account, additional account-specific fields will be displayed on the same subscription creation page. At a minimum, an account code and billing information are required to create a subscription.

If no Salesforce account is populated on the opportunity or if the Salesforce account on the opportunity is not yet linked to a Recurly account, an account will be created in Recurly using the data entered at the same time the subscription is created.

📘

If account linking is enabled between Salesforce Accounts and Recurly Accounts, the "Recurly Account Linking" field specified in your admin settings will not be editable on the subscription creation page. This guarantees that this value can't deviate from the value on the Salesforce Account and disrupt proper linking.

Roles & Permissions

To control who can access the application, and what they have access to, four custom profiles and permission sets have been created. The custom profiles should be mapped to existing org profiles during the installation process, and permission sets can be assigned to individuals based on a specific need for them to have access to the app.

  • Recurly Admin: The Recurly Admin has read and view access to all of the objects. The admin also has create and edit permissions where the app allows. The admin has access to the Recurly Admin tab that allows application controls to be set. An additional tab that the admin can access is the Recurly Logs tab, which allows the admin to view and interpret data sync errors.
  • Recurly Sales User: The Recurly Sales user has read and view access to all of the objects. The sales user also has create and edit permissions where the app allows.
  • Recurly Support User: The Recurly Support user has read and view access to all of the objects without any create or edit permissions.
  • Recurly Sales / Marketing Manager: The Recurly Sales / Marketing Manager has read and view access to all of the objects without any create or edit permissions.