The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Recurly for Salesforce

To improve process efficiency and eliminate duplicate data entry, 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.

Salesforce users are able to manage customer account and subscription information from within Salesforce, and the changes can be synced to Recurly.


This page describes the Recurly for Salesforce Integration This feature is available in the Professional and Enterprise plans of Recurly.

  • We recommend that before integrating either Recurly or Salesforce production instances, that you open a Recurly site in sandbox mode and test with non-production data synced to a Salesforce sandbox site.
  • The integration is compatible with Salesforce Lightning and Classic UI.
  • The integration works with Salesforce sandbox or production sites.
  • The integration works with Recurly sites in sandbox or production mode.
  • The integration does not work with Salesforce Professional edition or SalesforceIQ.
  • The integration currently does not support linking Recurly data with Salesforce Contact or Opportunity objects.
  • Salesforce custom code, workflows, or triggers cannot be supported by Recurly.
  • The Salesforce integration does not currently support Recurly custom fields.

Installing the integration

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

  • Recurly Accounts
  • Recurly Subscriptions
  • Recurly Plans
  • Recurly Add-Ons
  • Recurly Invoices
  • Recurly Line Items (each individual charge on an invoice)
  • Recurly Transactions (payments)
  • Recurly Logs (for troubleshooting and audit trail)
  • Recurly Admin (for system administrators)

For explicit instructions on installing the integration, see Recurly for Salesforce Set Up page.

Recurly data on Salesforce Accounts

Recurly supports the ability to link the Recurly Accounts object with the Salesforce standard object. This allows you to do reporting on the linked objects in your org. Recurly creates the following fields on the Salesforce standard 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 Invoices Outstanding: the total amount of invoices outstanding against linked Recurly accounts.
  • Average Last 3 Invoices: contains an average of the last 3 invoices from Recurly.
  • Recurly Plan Name: contains 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 which is past due.
  • In trial: boolean field will be populated if the account has a subscription which 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 account to Salesforce account. If you enable this option, the billing address from Recurly account that is linked to a Salesforce account will be populated on the Salesforce account. 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.

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 Subscriptions, Invoices, and Transactions related to each one of these accounts once they have been synced from Recurly.

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 fields can be only 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.

Using the Edit button the Recurly account and editing the Payment information fields will not be synced back to Recurly. You need to use the method above as it is compliant with Payment Card Industry (PCI) standards.

Deleted Accounts

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

Deactivate / Reactivate Accounts

“Deactivate” and “Reactivate” buttons have been provided on the account page. The buttons allow a user to deactivate an active Recurly account, or reactivate a deactivated Recurly account.

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

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

Also on the plan page, you can view the Subscriptions, Invoices, and Transactions related to each one of these plans once they have been synced from Recurly.

Edits to plans from within Salesforce will not be synced with Recurly.

Recurly Add-Ons

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

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

Edits to add-ons from within Salesforce will not be synced with Recurly.

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)

There are multiple actions that can be taken to edit a subscription from within Salesforce and integrate the changes back to Recurly. These can be accessed using the Manage Subscription Plan button on the Recurly Subscription page.

Adding a new subscription

From a record in the Recurly Accounts custom 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 with a single action within Salesforce.

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.

If you use the Salesforce standard Edit button on the Recurly Subscription, any changes you make will not be synced 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 in Recurly, follow the instructions to edit a subscription, and click "Terminate." You will be presented with options to terminate with a full refund, partial refund, or no refund.

Pausing a subscription

To pause a Recurly Subscription, click the "Manage Subscription Plan" button on an active subscription and click the Pause button. 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 in Recurly. 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 Changes

Subscriptions that have the Pending Changes box checked have changes pending at their next renewal date in Recurly. Note that any changes (subscription change, cancellation, or termination) will delete any pending changes within 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 a field to estimate the monthly recurring revenue of subscriptions 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
  • Terms
  • Customer Notes
  • VAT Number
  • Total Amount Outstanding: the invoice balance for invoices before the credit invoices feature was enabled. Type = legacy
  • Balance: the invoice balance for invoices after the credit invoices feature was enabled. Type = charge or credit.

Editing an Invoice in Recurly

Beginning in version 2.24, Recurly is pleased to support the syncing of invoice updates from Salesforce to Recurly. If you edit the following fields in Salesforce, the update will be reflected in Recurly:

  • PO Number
  • Net Terms: Enter a number to change the Due At date. This will represent the number of days after the invoice was issued that the invoice is due. For example, if the invoice was issued on January 1 and you enter 10, the invoice will be due on January 11. See this page for more info on the Due At date.
  • Customer Notes

Recurly Line Items

Recurly 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

Edits to invoice line items from within Salesforce will not be integrated with Recurly. If you disable the syncing of line items, no line items will be synced with Salesforce.

Recurly Transactions

Recurly synchronizes your 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

Edits to invoice transactions from within Salesforce will not be integrated with Recurly. If you disable the syncing of transactions, no transactions will be synced with Salesforce.

What doesn't sync back to Recurly?

The main objects that are available to be edited from within Salesforce are accounts and subscriptions. The following objects are editable in Salesforce (depending on your configuration) but will not have changes synced back to Recurly:

  • Line Items
  • Plans
  • Add-Ons
  • Transactions

Roles & Permissions

To control who can access the application, and what they have access to, 4 custom profiles and permission sets have been created. The custom profiles should be mapped to existing org profiles during the installation process while the 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 also has access to an Admin tab that allows application controls to be set. An additional tab that the admin can access is the Recurly log tab, this 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 only has read and view access to all of the objects.
  • Sales / Marketing Manager - The Recurly Sales user only has read and view access to all of the objects.


If you are having any issues with your Salesforce integration, the first place to investigate is within the "Recurly Logs" object within the Salesforce managed package. This section includes information about which API calls were made to Recurly, whether they were successful or unsuccessful, and more detailed information about failed calls.

Recurly to Salesforce Sync Errors

When there are errors with the Recurly to Salesforce sync, the API will attempt to re-sync the failed data automatically. For example, if an invoice is unable to be synced, the integration will attempt to re-sync when it runs next. These messages will appear in the Recurly Logs tab in the Recurly for Salesforce application.

To run a report about these errors, a folder called "Recurly Reports" has been created in Reports and Dashboards within Salesforce. The report called "Recurly Error Logs" within this folder provides reporting on errors from Recurly to Salesforce. This is the first place to check when you find errors in your sync process.

Salesforce to Recurly Sync Errors

When data fails to sync between Salesforce and Recurly, the user who edited the record inside of Salesforce will receive an email with information on why the sync failed.

Workflow, Triggers, and Customization

You are able to add customization on top of Recurly custom objects within Salesforce. However, these customizations will not be supported by Recurly as every merchant will require different triggers, workflows, and customizations in order to integrate Recurly data into their business process.


Below you will find some common issues and the solutions for them.

Troubleshooting Steps

Recurly accounts are not being linked to Salesforce standard accounts.

Check the Recurly Admin tab and make sure that you have linking to Salesforce accounts enabled.

If you are still experiencing issues, ensure that the field on which you link Salesforce and Recurly accounts is populating correctly on Recurly accounts.

Salesforce accounts are not being created in my org when Recurly accounts are created.

Check the Recurly Admin tab to make sure that you have the option to create Salesforce accounts enabled.

I am missing Recurly data in my Salesforce org.

There could be a number of reasons for this. Follow these steps:

  1. Check the Recurly Logs tab and ensure that there are no errors being experienced.
  2. If there are no logs, navigate to Setup > Apex Jobs and ensure that there are no Apex jobs which experienced an error.
  3. Check your email to ensure that your Recurly API key has not errored. If there is an API key failure, Recurly for Salesforce will send you an email.
  4. Ensure that the user the integration is running as has the permission necessary to insert records.

My users can't see data.

This is either due to:

  1. Page layouts
  2. Permissions

I can't uninstall the package.

  1. Deactivate the sync by going to the admin page and hitting the "Deactivate sync" button.

  2. Ensure there are no custom fields, workflow rules, or apex code referencing any objects/fields in the package. Due to the amount of potential complexity in Salesforce complexity, the easiest way to see if there are custom fields or rules referencing the package is to attempt to uninstall and see if there is an error. duplicate management and Recurly for Salesforce

Salesforce offers duplicate management through functionality. While the ability to report on and block duplicates is great for your users, it can cause issues for API integrations. In order to ensure that your data can sync and update properly from Recurly, we urge you to take the following steps:

  1. Fully exclude the user running the sync, including the "Recurly for Salesforce" user and any updates from our system, from triggering the rules
  2. Manually excluding any updates to fields related to the Recurly sync
  3. For your initial sync, deactivate your rules completely. Since Recurly needs to access your standard accounts for linking, deactivating your rules is the best way to ensure that all of the data is synchronized properly.

If you do not follow these steps Recurly cannot guarantee that all of your data will be synced to Salesforce or linked correctly to your Salesforce accounts.

Further Support

If you require further support, please contact Recurly Support and we will be happy to assist you.

Please be sure to mention which version of the package you are using (this is available on the Recurly Admin screen).