Overview
The Salesforce Revenue Management Integration provides a wealth of insights to help you manage and improve the health of your business.
View current customer revenue, products purchased, and contract terms
Manage renewal and post-sales opportunities, forecasts, and workflow
Gain visibility into the health of renewals across your business
This article is about integrating ClientSuccess with Salesforce to ingest revenue data. Please review the ClientSuccess Revenue Manager video for more information on general revenue setup, configuration, and reporting.
IMPORTANT: Please ensure you review the Prerequisites section below before implementing the integration
The following topics are covered in this article
Features and Functionality
Out-of-the-box support for mapping to Salesforce Opportunity and Opportunity Line Items
Support for one or many products per contract
Bi-directional sync configurable at the field level
Support for custom stage names to indicate Booked, Lost, or Forecasted revenue
Safety protocols ensure records in your Salesforce CRM are NOT deleted
Terminology
The Salesforce Opportunity object is typically used to track deals through to a Closed stage. The Contract module is the ClientSuccess version of the Salesforce Opportunity object.
The Salesforce Opportunity Line Item object can be used to track products that are added to a particular Opportunity. The Contract Line Items module in ClientSuccess is most similar to Opportunity Line Items in Salesforce.
Salesforce Object | ClientSuccess Module | Purpose | CS Module Required |
Opportunity | Contract | Track and manage contracts and deals. Details include assigned account, stage, and relationships. | Yes |
Opportunity Line Item | Contract Line Item | Track and manage multiple products associated with a particular contract. Details include types of products and respective prices. | No |
A standard Salesforce implementation has a one-to-many relationship between Accounts and Opportunities and a one-to-many relationship between Opportunity and Opportunity Line Items
Here is an example of a Salesforce Opportunity with Opportunity Line Items (in red square).
NOTE: The Salesforce Contract object is not equivalent to Contracts in ClientSuccess. The Salesforce Contract object is not typically used as part of this integration.
Prerequisites
Authenticated to Salesforce via ClientSuccess
Required Salesforce fields
Import Filter (e.g. Sync_w_ClientSuccess checkbox)
Associated Client
Contract term start date (at product line-item or contract level)
Contract term end date(at product line-item or contract level)
Revenue amount for the entire contract term (not ARR or MRR) in your master currency (at product line-item or contract level)
Product(s)
Quantity for each product
Close date
Stage
If you have multiple products per contract: the standard implementation uses both the Salesforce Opportunity object and Opportunity Line Item object. These line-item objects are separate, child objects for product line items.
Salesforce product list in ClientSuccess: Please see the step “Product List and Product External IDs” for more information.
Matching data between Salesforce and ClientSuccess (data parity) prior to enabling the sync. Please see this article for more information.
If you are interested in Pushing data from ClientSuccess to Salesforce, please see Push Requirements and Roadblocks
EXAMPLE:
Map to the standard Salesforce Opportunity object (sample below, required fields in red)
Map to both the standard Salesforce Opportunity and OpportunityLineItem (AKA OpportunityProduct) object
Integration Survey
The Revenue Management Integration Survey is provided to help facilitate a quick setup of your revenue management integration. Please attach the appropriate screenshots within the survey and provide the completed file to your CSM/Onboarding Specialist. Your Onboarding Specialist will use this information to set up your Salesforce Revenue Integration and import one sample contract for your review.
Note that there are two sheets in the survey to support both a Contract+Line Item or Contract-only implementation model. Please complete the sheet that supports your implementation.
Product Catalog
The Products listed on your Salesforce Contracts must be set up in ClientSuccess beforehand. The Product List can either be entered manually or you can send a list of products via CSV to be imported by customer support with the following required fields:
Field Name | Required? | Detail |
Product Name | Yes | |
Product Code/SKU | Yes | Must be unique |
Description | No | |
External CRM ID | Yes | SFDC 18-digit ID |
Is Active | Yes | true/false indicates if a product can be used in CS |
Is Recurring | Yes | true/false associates to total MRR/ARR(recurring) or ACV (recurring + one-time) |
Products MUST indicate if they are recurring or one-time. This enables ClientSuccess to differentiate between contracts with recurring revenue, and therefore can be renewed, vs. one-time revenue.
A unique SKU/Product Code must be present for each product. This will be used in future reporting
If you are using Salesforce Price Books (typically via the Salesforce Opportunity Line Item object) then Salesforce External IDs ("Product ID - External System ID" in field mapping) must be used for the Product Line Item mapping bi-directional sync. This is the 18 Digit ID found in the URL of each product page in Salesforce.
If you are not using Line Items, ClientSuccess can lookup product information by Salesforce ID, code, or description
Stage Mappings
Stage is required for ALL contracts
Stage configuration is dynamic to meet the needs of all customers who configure their stages differently
Stage keys are added automatically as new contract stage key names are ingested into ClientSuccess. These stages can be found and configured in Global Settings > Field Settings > Contract > Stage
Stage Names do NOT need to be added in advance (unlike Product Names)
Stages must be configured in order to display booked, forecast, and lost renewals
If stages are not set, all Contracts will default to a "Forecast" status
There are three Stage Categories found in the “Stage” field for contracts
Booked = Closed Won (Cash in Hand/Paid Contracts). No longer in a forecast stage
Lost = Closed Lost. No longer in a forecast stage
Not Set = Any state not Lost or Booked and indicates a Forecasted Contract.
Do not configure stages until you have synced opportunities into ClientSuccess
Once you have mapped the stages, you will need to do another import of your contracts from Salesforce for the contract stages to be set correctly.
Additional Field Mappings
Renewal Relationships/Process
Understanding how your renewals are progressing toward completion is critical functionality in ClientSuccess. To do this, ClientSuccess must know which renewal opportunity belongs to which parent contract. This relationship mapping can be done either in ClientSuccess or Salesforce.
If this mapping is to be done in Salesforce, simply populate the “Renewed by” field with the opportunity ID of the child opportunity OR the “Renews” field with the parent opportunity ID. If you automatically create a renewal opportunity after the original opportunity closes, this may be a simple adjustment to your Salesforce opportunity creation process.
NOTE: In order to establish renewal linkage, you want to ensure that the first new opportunity for a client and all renewal opportunities including forecasted, renewed, and churned/terminated renewals are brought over. Any opportunity that has been created after the initial sale should be brought over.
Alternatively, this mapping can be set up in ClientSuccess by simply selecting the child contract that renews (OR is renewed by) the chosen contract.
Mid-term Upsells and Contract Adjustments Relationships/Process
Having an accurate picture of revenue, including up-sells and adjustments, is critical functionality in ClientSucccess. In order to track upsell and down-sell data, an adjustment/amendment is created.
This is accomplished by a separate opportunity that can add or remove products and revenue from the original contract.
ClientSuccess must know which adjustment opportunity belongs to which parent contract. This relationship mapping can be configured either in ClientSuccess or Salesforce.
If this mapping is to be done in Salesforce, simply populate the “Amended by” field with the opportunity ID of the child opportunity (e.g. an up-sell) and/or the “Amends” field with the parent opportunity ID
ARR/MRR
ClientSuccess calculates line-item and contract level ARR and MRR. These values can be overwritten so you can use your own calculation.
Overwrite Contract-level ARR/MRR: Pass in a value to the Assigned ARR field AND the Assigned MRR field. NOTE: Both Assigned ARR and Assigned MRR must have values
Overwrite Line-Item ARR/MRR: Pass in a value to the Item Assigned ARR and/or Item Assigned MRR values.
Push Requirements and Roadblocks
After you have successfully pulled opportunities from Salesforce into ClientSuccess, you can, if necessary, enable bi-directional sync to PUSH contracts and subscriptions to Salesforce opportunities.
This will enable you to push renewals, up-sells, and cross-sells that are created and managed in ClientSuccess back to Salesforce. Note that contract or line-item deletes in ClientSuccess are NOT pushed to Salesforce.
Please be aware of the following if you want to push Contracts from ClientSuccess to Salesforce.
Salesforce formula fields are not updatable. ClientSuccess can read data from Salesforce formula fields but can not push data to formula fields. This is a key point to remember as you plan your field mapping.
Contract pushes are independent of your sync filter. If a push is enabled, ALL contracts created or updated in ClientSuccess will be pushed to Salesforce. Therefore, data parity is critical to ensuring contracts are aligned between systems. Please see this article for more information.
Custom validation rules can not be created in ClientSuccess. For example, you may have a Salesforce validation rule requiring a non-zero quantity on any Salesforce Opportunity. This rule can not be replicated in ClientSuccess.
Also, any Salesforce validation errors will not appear in the ClientSuccess UI. Only the Integrations History log indicates whether or not a push to Salesforce succeeded or failed.Contracts or line-item deletes are not replicated between ClientSuccess and Salesforce. So, if you accidentally add a line item in ClientSuccess and then delete it, you will need to immediately delete it in Salesforce as well.
Salesforce Pricebooks can not be selected from ClientSuccess. If you are doing a Contract Line Item push, we strongly recommend that your Salesforce configuration has one and only one standard default pricebook. If you have multiple active price books for your products in ClientSuccess, you may need to provide the PriceBook ID to ClientSuccess to enable a custom integration configuration (recipe).
Contracts can only be created in ClientSuccess in your tenant currency.
Many ClientSuccess users create Opportunities in Salesforce and use ClientSuccess to update the record as needed. For example, adjusting probability, stage, etc.
FAQs
Do I need to have a product on my Contracts?
Contract Imports will fail if Products are not present in ClientSuccess.
Can I have the same product on multiple line items?
Yes. This is the recommended approach if you charge different amounts for different time periods. For example, year 1 has a different price than year 2.
What happens if I delete a line item or contract in ClientSuccess?
To ensure records are not accidentally deleted in Salesforce, deletes in ClientSuccess are NOT pushed to Salesforce.
Do I need to set up renewal relationships before importing Contracts?
No, relationship mapping fields can be imported or configured after the Contracts are brought over.
I don’t have start dates on my Salesforce Opportunities. What can I do?
Start date and end dates are required for any recurring subscriptions. The Close date is likely populated on your Salesforce Opportunities and may be similar to the Start date.
What is the difference if I map start dates and end dates to the Opportunity object vs. the Opportunity Line Item object?
If the start and end dates are on the Opportunity object the line items for the Opportunity will all have the same start date and end date. If you have line items with different start dates and end dates you will want to map to start and end dates on the Opportunity Line Item object. Start and end dates on the Opportunity object override dates on the Opportunity Line Item object.
I have an Overdue Contract – what does that mean?
Contracts are active or overdue until they are either renewed, terminated, or deleted. Renewal occurs by linking a child contract to the original and marking it “Booked”
I have validation rules on my fields in Salesforce for any record updates. How can I reflect these in ClientSuccess?
ClientSuccess is NOT a mirror of your Salesforce instance. If you need to bypass Salesforce validation rules to update fields in Salesforce from ClientSuccess, consider using Salesforce Record Types.
Can Contracts be linked in ClientSuccess if there is an overlap in start-date or end-date between the contracts (e.g. can an end-date for an original contract come before the start-date of the renewal)?
ClientSuccess will only allow parent-child renewal to be linked if there is NO overlap between the start date and end dates. The end date CAN NOT come before the start date.
However, if the linkages come from a Salesforce import than ClientSuccess does not perform this validation check and will accept both Contracts.
I use a custom object for line items, how do I relate it back to the parent object (e.g. Opportunity)
The "Use Contract Items" must be checked and the "Contract Item Parent ID" key must be entered on the mapping configuration page.
To relate your line-item objects back to the parent object (e.g. Opportunity), please use a lookup field, not a master-detail relationship, for the Opportunity ID.
I see the error "query did not return a unique result" in the Transaction History when I run a sync
Typically, this error is the result of multiple products in the ClientSuccess product catalog that have the same product ID, or whichever field you use to uniquely identify products.
I see the error "Item Id: Contract Item Missing LookupKey" in the Transaction History
The value in the product ID field (e.g. product code, product CRM ID, or product name) cannot be matched to a value in your product list in ClientSuccess. In these cases, the default product will be used to import the Contract into ClientSuccess.
What do I need to send over to ClientSuccess to indicate that a booked contract has been churned?
If you send over a Terminated Effective Date and a Termination Date on the booked contract the contract will be marked as churned. No other data from Salesforce is required.
Another option is to mark the forecasted renewal opportunity linked to the booked contract as "Lost" and send over a Terminated Effective Date. This will result in the booked contract being marked as churned. Remember that both contracts will need to be linked in the "Renewals" section or else the original booked contract will not change status.
The ARR values in ClientSuccess do not match my calculation
You can use the Assigned ARR field mapping at the Contract or Contract Line Item level to overwrite the ARR/MRR values. Please note that if you use Assigned ARR at the Contract level you must also populate the Assigned MRR value.
How do I ensure my integration is working?
There are a number of proactive steps you can take to ensure the data integration continues to work as expected. Please review "Maintaining your Integration" to learn more.