This page describes the Advanced Salesforce Integration, which was released in 2016. This feature is available in the Professional and Enterprise plans of Recurly.
The original version of the Salesforce integration reached its end of life on 3/31/17.
- 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 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.
- For multi-currency users, the integration currently does not support creating or editing subscriptions and subscriptions plans in different currencies within Salesforce.
- The integration currently does not support linking Recurly data with Salesforce contacts, or opportunity objects.
- Salesforce custom code is not supported by Recurly. Please contact us if you would like to discuss custom solutions to data manipulation and transfer within Salesforce as we can provide high-level guidance about how other merchants have solved for these use cases.
We are aware of a known issue in Salesforce regarding cloning production sites to sandbox. If the integration is installed in your production org, and the sync process is running, the cloning process will fail to migrate all of the necessary functionality for the sync to function properly in sandbox.
What we recommend doing, if you would like to perform a clone of sandbox to production, is to navigate to Recurly Admin > Deactivate Sync. Then run the cloning process. After the cloning process is complete, Navigate to Recurly Admin > Activate Sync. This will cause a successful clone to be created in sandbox.
When you install the integration, the following custom objects will be added to your Salesforce organization:
- Recurly Accounts
- Recurly Subscriptions
- Recurly Plans
- Recurly Invoices
- Recurly Line Items (the detail level of invoices)
- Recurly Transactions
- Recurly Admin (this object is only for system administrators)
- Recurly Logs (for troubleshooting and audit trail)
Release notes for the integration are located here.
Recurly supports the ability to link the Recurly Accounts custom object with the Salesforce standard object. This allows you to do reporting on the linked objects in your org. Recurly also creates the following fields on the Salesforce standard object to make reporting easier.
- 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. This numeric field contains an average of the last 3 invoices from Recurly.
- Recurly Plan Name. This field will contain the name of the most recently updated plan to which the account was subscribed.
- Past Due Invoice. This boolean field will be set to true if the account has a Recurly invoice which is past due.
- In trial. This boolean field will be populated if the account has a Recurly subscription which is in trial status.
- Active Subscriber. This 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 (notes below)
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 synchronizes your accounts with the following fields in the Recurly Accounts custom object within Salesforce:
- Account Code
- First Name
- Last Name
- 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:
- First Name
- Last Name
- 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.
NOTE that 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.
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” 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.
Note: Deactivating an account will cause the Billing Information for the account to be deleted and any subscriptions on the account will be cancelled.
Recurly synchronizes your plans with the following fields in the Recurly Plans object within Salesforce:
- Plan Name
- Plan ID
- Plan Code
- 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 synchronizes your add-ons with the following fields in the Recurly Add-Ons object within Salesforce:
- Add-On Name
- Add-On ID
Edits to add-ons from within Salesforce will not be synced with Recurly.
Recurly synchronizes your subscriptions with the following fields in the Recurly Subscriptions object within Salesforce:
- Plan Name
- Trial Length
- Currency (custom currency field)
- Coupon Code
- Collection Method
- Customer Notes (defaults to notes from account page)
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.
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.
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.
To cancel a subscription, follow the "Manage Subscription Plan" flow to edit a subscription, and click "Cancel Subscription." This will cause the subscription to not renew within Recurly as of the next renewal date.
To terminate a subscription from within Recurly, follow the instructions to edit a subscription, and click "Terminate Subscription." You will be presented with options to terminate with a full refund, partial refund, or no refund.
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.
NOTE: 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.
Recurly synchronizes your invoices with the following fields in the Recurly Invoices object within Salesforce:
- Invoice Number
- Invoice ID
- Tax Amount
- Due Date
- Recurly Account
- Subscription ID
- Collection Method
- PO Number
- Customer Notes
- VAT Number
Edits to invoices from within Salesforce will not be integrated with Recurly.
Recurly synchronizes your invoice line items with the following fields in the Recurly Line Items object within Salesforce:
- Line Item ID + Date/Time
- Tax Code
- Start date
- End Date
- Unit Amount
- 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 synchronizes your transactions with the following fields in the Recurly Transactions object within Salesforce:
- Transaction Name: Recurly ID + Date/Time of Transaction
- Account ID
- Recurly Invoice
- Payment Information (address)
- Gateway ID
- 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.
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
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.
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” section addressed above.
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.
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.
You are able to add Force.com 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.
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:
- Check the Recurly Logs tab and ensure that there are no errors being experienced.
- If there are no logs, navigate to Setup > Apex Jobs and ensure that there are no Apex jobs which experienced an error.
- 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.
- 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:
- Page layouts
I can't uninstall the package.
Deactivate the sync by going to the admin page and hitting the "Deactivate sync" button.
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.
Salesforce offers duplicate management through data.com 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:
- Fully exclude the user running the sync, including the "Recurly for Salesforce" user and any updates from our system, from triggering the data.com rules
- Manually excluding any updates to fields related to the Recurly sync
- For your initial sync, deactivate your data.com rules completely. Since Recurly needs to access your standard accounts for linking, deactivating your data.com 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.
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)