{"__v":125,"_id":"570d39855c787517008168e4","category":{"__v":5,"_id":"5665e3db1b6559190020ae8c","pages":["5665e3f81b6559190020ae8e","5665e424d8a06b170063f318","5665e43cb6c0f60d00eae549","5665e4661b6559190020ae90","56d0ca6c376b040b005b30c6"],"project":"56450a342229d7170010928a","version":"56450a342229d7170010928d","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-12-07T19:54:03.798Z","from_sync":false,"order":3,"slug":"3rd-party","title":"3rd Party Integrations"},"parentDoc":null,"project":"56450a342229d7170010928a","user":"561d36988f04bf1700ac356f","version":{"__v":9,"_id":"56450a342229d7170010928d","project":"56450a342229d7170010928a","createdAt":"2015-11-12T21:52:52.685Z","releaseDate":"2015-11-12T21:52:52.684Z","categories":["56450a352229d7170010928e","56450a472c74cf1900da48ca","565def2677f0090d005819bb","5665dfa0e93ae70d00b96a2a","5665e3db1b6559190020ae8c","5665e47763109d0d0036ba5a","5690123f18c3920d00be8b1c","56944016d8c04d1700e5ae20","569447891005590d0062cace"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":["578fb3c18335ca0e006d5d20"],"createdAt":"2016-04-12T18:08:05.791Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"## Intro\n\nThis page describes the Advanced Salesforce Integration, which was released in April 2016. For the previous version of the Salesforce integration documentation, see [here](https://docs.recurly.com/docs/salesforce-integration). For information on migrating from the previous version to Recurly for salesforce, see [here](https://docs.recurly.com/docs/salesforce-migration). The original version of the integration will be deprecated on 11/30/16.\n\n####**Considerations before beginning the implementation of your integration**:\n\n* This integration is available in the Professional and Enterprise plans of Recurly.\n* The integration works with Salesforce sandbox or production sites.\n* The integration works with Recurly sites in sandbox or production mode.\n* The integration does not support the Salesforce professional edition package.\n* For multi-currency users, the integration currently does not support creating or editing subscriptions and subscriptions plans in different currencies within Salesforce.\n* The integration currently does not support linking Recurly data with Salesforce contacts, or opportunity objects.\n* We highly 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.\n\n## Integration Version\n\nThe **current version** of the integration is version 1.5. Our current release cycle is to release a new version of the Recurly for Salesforce managed package once per month. This page will be updated with a link to the new package, as well as additional information related to the new version.\n\nIn order to upgrade, merchants who are using a previous version can install the new version and additional functionality will be added to their existing version of the package. To install the new version, simply click on the link to the new package below and follow the Salesforce install process.\n\nRelease notes for the integration are located [here](https://docs.recurly.com/docs/salesforcereleasenotes).\n\n## Setup\n\n1. If you don't already have a Salesforce account, you can [create a free developer account](https://developer.salesforce.com/signup) for evaluation.\n\n2. Install the Recurly for Salesforce package ([contact support](support.recurly.com) for more info)\n  \n \n3. Within your Salesforce instance, assign the appropriate Recurly permissions. If you would like to make new profiles, clone existing Salesforce profiles that you would like to have Recurly permission sets added to and label  them \"**Recurly ______ Profile**.\" e.g. \"**Recurly Sync Profile**.\" \n\n  *It is important to do this before installing the package, as during package installation, you will assign the permission sets in the package to these profiles.*\n\n4. Click Install - grant access to the Recurly API when prompted.\n\n5. The install process will run. It may take a few minutes to complete.\n\nWe recommend you review your user profiles and ensure that your profiles have been assigned to the user roles you would like to access Recurly data.\n\nThe package installation will add the following custom objects to your Salesforce instance and can be added as tabs:\n* Recurly Accounts\n* Recurly Subscriptions\n* Recurly Plans\n* Recurly Invoices\n* Recurly Line Items\n* Recurly Transactions\n* Recurly Admin (this object is only for system administrators)\n* Recurly Logs (for troubleshooting and audit trail)\n\n## Configure Sync Settings\n\nAfter installing the app, navigate to the \"**Recurly Admin**\" tab and follow these instructions to complete the configuration:\n\n1. Set **Private API Key:** this is the field which will capture your API key to authenticate with Recurly. You can find this under \"developers\" in Recurly. We recommend you create a new API key called Salesforce.\n2. Set **Public Key**: this field will accept your public API key on your developer settings page in Recurly so that you can integrate with Recurly.js for payment information.\n3. **DO NOT** Click **Activate Recurly Sync** yet. This will be the last step after more settings are enabled.\n4. **Enable Outbound Sync**: checking this box will enable the ability to sync records from Salesforce to Recurly. \n \n_(**NOTE**: by default, the Edit buttons will not be removed from each Recurly page. We recommend that Salesforce administrators disable these buttons on Recurly custom objects within Salesforce should they choose to disable the two-way sync.)_\n\n5. **Only Sync Accounts with Subscriptions**: checking this box will only sync accounts that have active, pending, or expired subscriptions to Salesforce. Accounts without subscriptions will not be synced. This will limit the amount of data sent to Salesforce to the most relevant records.\n\n\n## Linking Recurly Accounts with Salesforce Standard Accounts\n\nThe **Account Link Settings**  on the Recurly Admin tab enables you to link the Recurly Accounts custom object with the standard account object within Salesforce. This setting is not required, and we advise you to review the documentation below before enabling it.\n\nBy clicking the checkbox, when accounts are integrated from Recurly, the app will create a link between the Recurly Account record and the Salesforce account record.\n\nWhen adding a field to the Recurly Account Link field, you need to include the Salesforce API Name of the field, rather than the field label. To find this: \n\n1. In Salesforce, navigate to **Setup** \n2. On the left navigation under the Build section, click **Installed Packages** \n3. Click **Recurly for Salesforce**\n4. Click the **View Components** button \n5. From there click on the field you want to use to get the API Name. For example, if you want to link on Recurly account code, you would not enter 'Account Code', but `Recurly_v2__Code__c`.\n\nWe recommend using the following API Names:\n\n*  **Account code** - `Recurly_v2__Code__c`\n*  **Email** - `recurly_v2__Email__c`\n* **Company** (Name field in Salesforce) - `recurly_v2__Billing_Company__c`\n\n**Note** that by using the Account Link Field as **account code**, we'll populate the **Recurly External ID** with the account code. See additional instructions under [Creating Salesforce Accounts from Recurly Accounts](https://docs.recurly.com/v1.0/docs/salesforce#section-creating-salesforce-accounts-from-recurly-accounts).\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/pYyDuOhSIa6FIcaFam3w_Screen%20Shot%202016-06-22%20at%203.14.41%20PM.png\",\n        \"Screen Shot 2016-06-22 at 3.14.41 PM.png\",\n        \"1504\",\n        \"764\",\n        \"#345075\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n##Edit Your Salesforce Page Layout\n\nYou'll need to edit your Salesforce page layout to add the **Recurly External ID** field for users who will use Recurly data.  See the steps below:\n\n1. In Salesforce, navigate to **Setup** found on the top right of the page\n2. On the left navigation, under the **Build** section, click **Customize**\n3. Click **Accounts** \n4. Click **Page Layout**\n5. Click into **Fields**\n6. Find the **Recurly External ID** field and add this to the form. This can be placed anywhere on the page layout.\n7. Click into the **Related Lists** section\n8. Drag the **Recurly Accounts** field into the related lists on the Accounts form\n9. Click **Save**\n10. Next you'll need to populate the **Recurly External ID** field on your applicable Standard Accounts using a trigger or upload to Salesforce. For example, if you use **account code**, you'll need to add the Account Code for all Salesforce accounts in your instance that you'd like to link to Recurly accounts. See instructions below.\n\n## Creating Salesforce Accounts from Recurly Accounts\n\nIf you choose to link Recurly Accounts to standard Salesforce accounts, the integration gives you the capability to create Salesforce accounts if a Recurly Account does not find a match within Salesforce.\n\nThis feature is helpful for merchants that have an online channel which generates leads for their sales team. It will create Salesforce accounts which can be edited and owned by sales and service teams.\n\n_**WARNING**: this setting is not required, and we advise you to review the documentation below before enabling the setting as it may result in a significant number of accounts being created in your Salesforce instance._\n\nSee the following instructions:\n\nOnce you've installed the package and completed first 3 steps of the set up, you will need to backfill the value into the **Recurly External ID** on all of your existing accounts.  \n\n1.  Select a value for external ID that will exist on your Recurly accounts:\n\n  * If you were using V1 of the Recurly integration, you may choose to use **Account Code** for your initial linking.  \n  * If you are starting fresh, you may want to use **Email**\n  \n\n2. Download all of your accounts and populate the value in the **Recurly External ID** field\n3.  Then re-import the data into salesforce\n4. Once you've populated the values on your existing records, you will need to go into the **admin settings**. \n\n  * If you can predict what the value will be to match on, you'll also want to create a workflow rule to populate the value in external ID on accounts going forward.\n  \n  * If you want Recurly to always create an account, ensure you've checked off Create Accounts To Link To. It's important to note that if you do **NOT** populate the external ID field, the integration will NOT match on any accounts in your salesforce org and you may see duplicates created\n  \n  * If you do not want Recurly to create accounts but want to manually link them, you'll want to create a report of Recurly Accounts where account is equal to null.  You can then manually populate the value in account so that no duplicates are created\n\nIn the **Recurly Admin** tab under **Account Link Settings**, checking the **Create Accounts to Link to** will cause standard Salesforce accounts to be created if a link is not found to associate a Recurly account to a Salesforce account. \n\n_For example, if you link Recurly accounts and Salesforce accounts based on email address. If you have a Recurly account with email address test:::at:::salesforce.com and you enable the setting, the integration will look to see if there is a Salesforce account with email test@salesforce.com. If there is no account with this email address, the integration will attempt to create a Salesforce account for it._\n\n**NOTE**: The \"Company\" field on Recurly accounts is integrated with the \"Name\" field on Salesforce accounts. As this field is mandatory on Salesforce accounts, Recurly accounts that do not have the \"Company\" field filled out will not have equivalent Salesforce accounts created.\n\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/k5YjDRVHQWSdSNd3s5dl_Screen%20Shot%202016-06-10%20at%204.10.23%20PM.png\",\n        \"Screen Shot 2016-06-10 at 4.10.23 PM.png\",\n        \"1021\",\n        \"534\",\n        \"#2c577d\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nTo illustrate how this solution works, we will create an account in Recurly called \"Test Account\" with email test@salesforce.com. There is no standard Salesforce account with an email test@salesforce.com, so the integration will create an account, and it will create a link between the Salesforce standard account and the Recurly account.\n\n**Recurly Account**:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/yh9h1iO6RxSBQRRCrYN3_Screen%20Shot%202016-06-02%20at%2012.39.13%20PM.png\",\n        \"Screen Shot 2016-06-02 at 12.39.13 PM.png\",\n        \"1069\",\n        \"398\",\n        \"#2d3d5f\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n**Salesforce Account**:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/lY9usHOkTdittWbTICGR_Screen%20Shot%202016-06-02%20at%2012.41.37%20PM.png\",\n        \"Screen Shot 2016-06-02 at 12.41.37 PM.png\",\n        \"1063\",\n        \"635\",\n        \"#31517f\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n## Begin Syncing Data\n\nOnce you've completed the setup above, click the \"Activate Recurly Sync\" button the Recurly Admin tab in order to sync data from Recurly to Salesforce. Note that the first sync process may take a long amount of time to bring your historical Recurly data to Salesforce.\n\nAfter the initial sync, records will be queried from Recurly into Salesforce every 5 minutes. Updates made to these records from within Salesforce will be sent back to Recurly immediately.\n\nIf you would like to stop Salesforce from querying Recurly every 5 minutes, click the \"Deactivate Recurly Sync\" button.\n\n## Recurly Accounts\n\nRecurly synchronizes your accounts with the following fields in the **Recurly Accounts** custom object within Salesforce:\n\n* Account Code\n* Company\n* Status\n* First Name\n* Last Name\n* Username\n* Email\n* CC Email\n* Account ID\n* VAT Number\n* Tax Exempt\n* Account Address\n* Account Payment Information\n* Card Type\n* First 6 Digits of CC\n* Last 4 Digits of CC\n* CC Valid?\n* CC Exp Month\n* CC Exp Year\n\nOn 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.\n\nOnce 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:\n\n* Company\n* First Name\n* Last Name\n* Email\n* CC Email\n* VAT Number\n* Tax Exempt\n\nPayment Information fields can be updated via the \"Add Payment Information\" button on the Recurly Account page. This form uses [Recurly.js](https://recurly.com/recurlyjs/) 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.\n\n### Deleted Accounts\n\nIf 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.\n\n### Deactivate / Reactivate Accounts\n\n“Deactivate” and “Reactivate” buttons have been provided on the account page. The buttons allow a user to deactivate an active account, or reactivate a deactivated account. \n\nNote: Deactivating an account will cause the Billing Information for the account to be deleted and any subscriptions on the account will be cancelled.\n\n## Recurly Plans\n\nRecurly synchronizes your plans with the following fields in the **Recurly Plans** object within Salesforce:\n\n* Plan Name\n* Plan ID\n* Plan Code\n* Status\n* Description\n* Interval Length\n* Recurring Charge Amount\n* Setup Fee\n* Tax Collection\n\nAlso 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.\n\nEdits to plans from within Salesforce will not be synced with Recurly. \n\n## Recurly Add-Ons\n\nRecurly synchronizes your add-ons with the following fields in the **Recurly Add-Ons** object within Salesforce:\n\n* Add-On Name\n* Add-On ID\n* Code\n* Status\n* Price\n\nEdits to add-ons from within Salesforce will not be synced with Recurly.\n\n## Recurly Subscriptions\n\nRecurly synchronizes your subscriptions with the following fields in the **Recurly Subscriptions** object within Salesforce:\n\n* Plan Name\n* Trial Length\n* Currency (custom currency field)\n* Price\n* Quantity\n* Coupon Code\n* Collection Method\n* Customer Notes (defaults to notes from account page)\n\nThere 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 Edit Subscription Plan button on the Recurly Subscription page.\n\n### Adding a new subscription\n\nFrom 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.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/56qY4jPShGgs6O0IDx5s_Screen%20Shot%202016-04-26%20at%206.38.21%20PM.png\",\n        \"Screen Shot 2016-04-26 at 6.38.21 PM.png\",\n        \"1135\",\n        \"1076\",\n        \"#2472b1\",\n        \"\"\n      ],\n      \"sizing\": \"smart\"\n    }\n  ]\n}\n[/block]\n### Editing a Subscription\n\nTo edit a subscription, click \"Manage Subscription Plan\" from the Recurly Subscription object. You will be given a number of options of fields to edit.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/YFmLDHnHTFqctfm4NRrM_Screen%20Shot%202016-04-26%20at%206.45.23%20PM.png\",\n        \"Screen Shot 2016-04-26 at 6.45.23 PM.png\",\n        \"1131\",\n        \"269\",\n        \"#2d5e99\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n### Cancelling a subscription\n\nTo 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.\n\n### Terminating a subscription\n\nTo 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.\n\n### Subscriptions Pending Changes\n\nSubscriptions 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.\n\n## Recurly Invoices\n\nRecurly synchronizes your invoices with the following fields in the **Recurly Invoices** object within Salesforce:\n\n* Invoice Number\n* Invoice ID\n* Type\n* Status\n* Currency\n* Total\n* Discount\n* Tax Amount\n* Due Date\n* Recurly Account\n* Subscription ID\n* Collection Method\n* PO Number\n* Terms\n* Customer Notes\n* VAT Number\n\nEdits to invoices from within Salesforce will not be integrated with Recurly.\n\n## Recurly Line Items\n\nRecurly synchronizes your invoice line items with the following fields in the **Recurly Line Items** object within Salesforce:\n\n* Line Item ID + Date/Time\n* Type\n* State\n* Origin\n* Description\n* Tax Code\n* Start date\n* End Date\n* Currency\n* Unit Amount\n* Quantity\n* Amount\n* Discount\n* Tax\n* Refund\n* Accounting Code\n* Plan Code\n\nEdits to invoice line items from within Salesforce will not be integrated with Recurly.\n\n## Recurly Transactions\n\nRecurly synchronizes your transactions with the following fields in the **Recurly Transactions** object within Salesforce:\n\n* Transaction Name: Recurly ID + Date/Time of Transaction\n* UUID\n* Tupe\n* Status\n* Currency\n* Amount\n* Account ID\n* Origin\n* Status\n* Recurly Invoice\n* State\n* Payment Information (address)\n* Gateway ID\n* Message\n* Approval Code\n* Gateway Reference\n\nEdits to invoice transactions from within Salesforce will not be integrated with Recurly.\n\n## What doesn't sync back to Recurly?\n\nThe 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:\n\n* Invoices\n* Line Items\n* Plans\n* Add-Ons\n* Transactions\n\n## Roles & Permissions\n\nTo 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.\n\n* **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.\n* **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.\n* **Recurly Support User** - The Recurly Support user only has read and view access to all of the objects.\n* **Sales / Marketing Manager** - The Recurly Sales user only has read and view access to all of the objects.\n\n## Support\n\nIf 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.\n\n### Recurly to Salesforce Sync Errors\n\nWhen 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.\n\nTo 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.\n\n### Salesforce to Recurly Sync Errors\n\nWhen 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.\n\n### Workflow, Triggers, and Salesforce Customization\n\nYou 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.\n\n### Further Support\n\nIf you require further support, please contact [Recurly Support](https://support.recurly.com/) 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)","excerpt":"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.\n\nSalesforce users are able to manage customer account and subscription information from within Salesforce, and the changes can be synced to Recurly.","slug":"salesforce","type":"basic","title":"Recurly for Salesforce"}

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.

## Intro This page describes the Advanced Salesforce Integration, which was released in April 2016. For the previous version of the Salesforce integration documentation, see [here](https://docs.recurly.com/docs/salesforce-integration). For information on migrating from the previous version to Recurly for salesforce, see [here](https://docs.recurly.com/docs/salesforce-migration). The original version of the integration will be deprecated on 11/30/16. ####**Considerations before beginning the implementation of your integration**: * This integration is available in the Professional and Enterprise plans of Recurly. * The integration works with Salesforce sandbox or production sites. * The integration works with Recurly sites in sandbox or production mode. * The integration does not support the Salesforce professional edition package. * 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. * We highly 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. ## Integration Version The **current version** of the integration is version 1.5. Our current release cycle is to release a new version of the Recurly for Salesforce managed package once per month. This page will be updated with a link to the new package, as well as additional information related to the new version. In order to upgrade, merchants who are using a previous version can install the new version and additional functionality will be added to their existing version of the package. To install the new version, simply click on the link to the new package below and follow the Salesforce install process. Release notes for the integration are located [here](https://docs.recurly.com/docs/salesforcereleasenotes). ## Setup 1. If you don't already have a Salesforce account, you can [create a free developer account](https://developer.salesforce.com/signup) for evaluation. 2. Install the Recurly for Salesforce package ([contact support](support.recurly.com) for more info) 3. Within your Salesforce instance, assign the appropriate Recurly permissions. If you would like to make new profiles, clone existing Salesforce profiles that you would like to have Recurly permission sets added to and label them "**Recurly ______ Profile**." e.g. "**Recurly Sync Profile**." *It is important to do this before installing the package, as during package installation, you will assign the permission sets in the package to these profiles.* 4. Click Install - grant access to the Recurly API when prompted. 5. The install process will run. It may take a few minutes to complete. We recommend you review your user profiles and ensure that your profiles have been assigned to the user roles you would like to access Recurly data. The package installation will add the following custom objects to your Salesforce instance and can be added as tabs: * Recurly Accounts * Recurly Subscriptions * Recurly Plans * Recurly Invoices * Recurly Line Items * Recurly Transactions * Recurly Admin (this object is only for system administrators) * Recurly Logs (for troubleshooting and audit trail) ## Configure Sync Settings After installing the app, navigate to the "**Recurly Admin**" tab and follow these instructions to complete the configuration: 1. Set **Private API Key:** this is the field which will capture your API key to authenticate with Recurly. You can find this under "developers" in Recurly. We recommend you create a new API key called Salesforce. 2. Set **Public Key**: this field will accept your public API key on your developer settings page in Recurly so that you can integrate with Recurly.js for payment information. 3. **DO NOT** Click **Activate Recurly Sync** yet. This will be the last step after more settings are enabled. 4. **Enable Outbound Sync**: checking this box will enable the ability to sync records from Salesforce to Recurly. _(**NOTE**: by default, the Edit buttons will not be removed from each Recurly page. We recommend that Salesforce administrators disable these buttons on Recurly custom objects within Salesforce should they choose to disable the two-way sync.)_ 5. **Only Sync Accounts with Subscriptions**: checking this box will only sync accounts that have active, pending, or expired subscriptions to Salesforce. Accounts without subscriptions will not be synced. This will limit the amount of data sent to Salesforce to the most relevant records. ## Linking Recurly Accounts with Salesforce Standard Accounts The **Account Link Settings** on the Recurly Admin tab enables you to link the Recurly Accounts custom object with the standard account object within Salesforce. This setting is not required, and we advise you to review the documentation below before enabling it. By clicking the checkbox, when accounts are integrated from Recurly, the app will create a link between the Recurly Account record and the Salesforce account record. When adding a field to the Recurly Account Link field, you need to include the Salesforce API Name of the field, rather than the field label. To find this: 1. In Salesforce, navigate to **Setup** 2. On the left navigation under the Build section, click **Installed Packages** 3. Click **Recurly for Salesforce** 4. Click the **View Components** button 5. From there click on the field you want to use to get the API Name. For example, if you want to link on Recurly account code, you would not enter 'Account Code', but `Recurly_v2__Code__c`. We recommend using the following API Names: * **Account code** - `Recurly_v2__Code__c` * **Email** - `recurly_v2__Email__c` * **Company** (Name field in Salesforce) - `recurly_v2__Billing_Company__c` **Note** that by using the Account Link Field as **account code**, we'll populate the **Recurly External ID** with the account code. See additional instructions under [Creating Salesforce Accounts from Recurly Accounts](https://docs.recurly.com/v1.0/docs/salesforce#section-creating-salesforce-accounts-from-recurly-accounts). [block:image] { "images": [ { "image": [ "https://files.readme.io/pYyDuOhSIa6FIcaFam3w_Screen%20Shot%202016-06-22%20at%203.14.41%20PM.png", "Screen Shot 2016-06-22 at 3.14.41 PM.png", "1504", "764", "#345075", "" ] } ] } [/block] ##Edit Your Salesforce Page Layout You'll need to edit your Salesforce page layout to add the **Recurly External ID** field for users who will use Recurly data. See the steps below: 1. In Salesforce, navigate to **Setup** found on the top right of the page 2. On the left navigation, under the **Build** section, click **Customize** 3. Click **Accounts** 4. Click **Page Layout** 5. Click into **Fields** 6. Find the **Recurly External ID** field and add this to the form. This can be placed anywhere on the page layout. 7. Click into the **Related Lists** section 8. Drag the **Recurly Accounts** field into the related lists on the Accounts form 9. Click **Save** 10. Next you'll need to populate the **Recurly External ID** field on your applicable Standard Accounts using a trigger or upload to Salesforce. For example, if you use **account code**, you'll need to add the Account Code for all Salesforce accounts in your instance that you'd like to link to Recurly accounts. See instructions below. ## Creating Salesforce Accounts from Recurly Accounts If you choose to link Recurly Accounts to standard Salesforce accounts, the integration gives you the capability to create Salesforce accounts if a Recurly Account does not find a match within Salesforce. This feature is helpful for merchants that have an online channel which generates leads for their sales team. It will create Salesforce accounts which can be edited and owned by sales and service teams. _**WARNING**: this setting is not required, and we advise you to review the documentation below before enabling the setting as it may result in a significant number of accounts being created in your Salesforce instance._ See the following instructions: Once you've installed the package and completed first 3 steps of the set up, you will need to backfill the value into the **Recurly External ID** on all of your existing accounts.  1. Select a value for external ID that will exist on your Recurly accounts: * If you were using V1 of the Recurly integration, you may choose to use **Account Code** for your initial linking.  * If you are starting fresh, you may want to use **Email** 2. Download all of your accounts and populate the value in the **Recurly External ID** field 3. Then re-import the data into salesforce 4. Once you've populated the values on your existing records, you will need to go into the **admin settings**.  * If you can predict what the value will be to match on, you'll also want to create a workflow rule to populate the value in external ID on accounts going forward. * If you want Recurly to always create an account, ensure you've checked off Create Accounts To Link To. It's important to note that if you do **NOT** populate the external ID field, the integration will NOT match on any accounts in your salesforce org and you may see duplicates created * If you do not want Recurly to create accounts but want to manually link them, you'll want to create a report of Recurly Accounts where account is equal to null.  You can then manually populate the value in account so that no duplicates are created In the **Recurly Admin** tab under **Account Link Settings**, checking the **Create Accounts to Link to** will cause standard Salesforce accounts to be created if a link is not found to associate a Recurly account to a Salesforce account. _For example, if you link Recurly accounts and Salesforce accounts based on email address. If you have a Recurly account with email address test@salesforce.com and you enable the setting, the integration will look to see if there is a Salesforce account with email test@salesforce.com. If there is no account with this email address, the integration will attempt to create a Salesforce account for it._ **NOTE**: The "Company" field on Recurly accounts is integrated with the "Name" field on Salesforce accounts. As this field is mandatory on Salesforce accounts, Recurly accounts that do not have the "Company" field filled out will not have equivalent Salesforce accounts created. [block:image] { "images": [ { "image": [ "https://files.readme.io/k5YjDRVHQWSdSNd3s5dl_Screen%20Shot%202016-06-10%20at%204.10.23%20PM.png", "Screen Shot 2016-06-10 at 4.10.23 PM.png", "1021", "534", "#2c577d", "" ] } ] } [/block] To illustrate how this solution works, we will create an account in Recurly called "Test Account" with email test@salesforce.com. There is no standard Salesforce account with an email test@salesforce.com, so the integration will create an account, and it will create a link between the Salesforce standard account and the Recurly account. **Recurly Account**: [block:image] { "images": [ { "image": [ "https://files.readme.io/yh9h1iO6RxSBQRRCrYN3_Screen%20Shot%202016-06-02%20at%2012.39.13%20PM.png", "Screen Shot 2016-06-02 at 12.39.13 PM.png", "1069", "398", "#2d3d5f", "" ] } ] } [/block] **Salesforce Account**: [block:image] { "images": [ { "image": [ "https://files.readme.io/lY9usHOkTdittWbTICGR_Screen%20Shot%202016-06-02%20at%2012.41.37%20PM.png", "Screen Shot 2016-06-02 at 12.41.37 PM.png", "1063", "635", "#31517f", "" ] } ] } [/block] ## Begin Syncing Data Once you've completed the setup above, click the "Activate Recurly Sync" button the Recurly Admin tab in order to sync data from Recurly to Salesforce. Note that the first sync process may take a long amount of time to bring your historical Recurly data to Salesforce. After the initial sync, records will be queried from Recurly into Salesforce every 5 minutes. Updates made to these records from within Salesforce will be sent back to Recurly immediately. If you would like to stop Salesforce from querying Recurly every 5 minutes, click the "Deactivate Recurly Sync" button. ## 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 updated via the "Add Payment Information" button on the Recurly Account page. This form uses [Recurly.js](https://recurly.com/recurlyjs/) 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. ### 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 account, or reactivate a deactivated 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 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) 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 Edit 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. [block:image] { "images": [ { "image": [ "https://files.readme.io/56qY4jPShGgs6O0IDx5s_Screen%20Shot%202016-04-26%20at%206.38.21%20PM.png", "Screen Shot 2016-04-26 at 6.38.21 PM.png", "1135", "1076", "#2472b1", "" ], "sizing": "smart" } ] } [/block] ### 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. [block:image] { "images": [ { "image": [ "https://files.readme.io/YFmLDHnHTFqctfm4NRrM_Screen%20Shot%202016-04-26%20at%206.45.23%20PM.png", "Screen Shot 2016-04-26 at 6.45.23 PM.png", "1131", "269", "#2d5e99", "" ] } ] } [/block] ### Cancelling a subscription 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. ### Terminating a subscription 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 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. NOTE: you cannot see which changes are pending in Salesforce. In order to see which changes are pending, please log into Recurly. ## 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 Edits to invoices from within Salesforce will not be integrated with Recurly. ## 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. ## 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 * Tupe * 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. ## 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: * Invoices * 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. ## Support 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” 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. ### 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 Salesforce Customization 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. ### Further Support If you require further support, please contact [Recurly Support](https://support.recurly.com/) 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)