Overview
The HubSpot 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 HubSpot 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 HubSpot Deals and Line Items
Support for one or many products per contract
Sync forecast, closed, terminated, and historical subscription information
Support for custom stage names to indicate Booked, Lost, or Forecasted revenue
Safety protocols ensure records in your HubSpot CRM are NOT deleted
Terminology
The HubSpot Deals object is used to track deals through to a Closed stage. The Contract module is the ClientSuccess version of the HubSpot Deals object.
HubSpot Line Items can be used to track which products are added to a particular Deal. Products are tracked as Contract Line Items in ClientSuccess
HubSpot Object | ClientSuccess Module | Purpose | CS Module Required |
Deal | Contract | Track and manage deals. Details include assigned account, stage, and relationships. | Yes |
Line Item | Contract Line Item | Track and manage multiple products associated with a particular contract. Details include types of products and respective prices. | No |
Here is an example of a HubSpot Deals with Line Items (in red square).
Prerequisites
Authenticated to HubSpot via ClientSuccess
Connect to the HubSpot Deals object or Deals and Line Items
Deals must be associated with a HubSpot Company
Required HubSpot fields
Associated Client
Contract term start date: must be named cs_startdate if on the Line Item
Contract term end date: must be named cs_enddate if on the Line Item
Revenue amount for the entire contract term (not ARR or MRR) in your master currency
Product(s)
Quantity for each product
Close date
Stage
If multiple products per contract are required, you will need to use both the Deals and Line Item objects. These line-item objects are separate, child objects for product line items.
Your product list in HubSpot must be entered in ClientSuccess before contracts are imported. Please see the step “Product List and Product External IDs” for more information.
Matching data between HubSpot and ClientSuccess (data parity) prior to enabling the sync. Please see this article for more information.
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 HubSpot Revenue Integration and import one sample contract for your review.
Note that there are two sheets in the survey to support both a Deal+Line Item or Deal-only implementation model. Please complete the sheet that supports your implementation.
Product Catalog
The Products listed on your HubSpot Deals 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/HubSpot ID | No | HubSpot Product 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 not using Line Items, ClientSuccess can look up product information by HubSpot 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 in Global Settings > Field Settings > Stage Name
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 sync’d deals into ClientSuccess
Once you have mapped the stages, you will need to do another import of your contracts 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 deal belongs to which parent contract. This relationship mapping can be done either in ClientSuccess or HubSpot.
If this mapping is to be done in HubSpot, simply populate the “Renewed by” field with the Deal ID of the child Deal OR the “Renews” field with the parent Deal ID. If you automatically create a renewal deal after the original deal closes, this may be a simple adjustment to your HubSpot deal creation process.
As an example, here are the steps to create a renewal linkage using HubSpot workflow:
Create a new field on the Company object: "Last Deal Won ID"
When a new deal is won, copy the HubSpot ID of this deal into the Company field: "Last Deal Won ID"
Copy the "Last Deal Won ID" to any new deals created in HubSpot
Map the HubSpot Deal field “Last Deal Won ID” to the “Renews ID - CRM ID” field in ClientSuccess
When a new deal is closed-won, repeat step 2 above
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 contract that can add or remove products and revenue from the original contract.
ClientSuccess must know which adjustment belongs to which parent contract. This relationship mapping can be configured either in ClientSuccess or HubSpot.
If this mapping is to be done in HubSpot, simply populate the “Amended by” field with the deal ID of the child deal (e.g. an up-sell) and/or the “Amends” field with the parent deal 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.
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.
Do I need to setup 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 HubSpot Deals. What can I do?
Start date and end dates are required for any recurring subscriptions. Close date is likely populated on your Deals and may be similar to Start date.
What is the difference if I map start dates and end dates to the Deals object vs. the Line Item object?
If start and end dates are on the Deals object the line items for the deal 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 Line Item object. Start and end dates on the Deal object override dates on the 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 HubSpot for any record updates. How can I reflect these in ClientSuccess?
ClientSuccess is NOT a mirror of your HubSpot instance. You may need to bypass validation rules to update fields in HubSpot from ClientSuccess.
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 start date and end dates. An end-date CAN NOT come before a start-date.
However, if the linkages come from a HubSpot import than ClientSuccess does not perform this validation check and will accept both Contracts.
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.
What do I need to send over to ClientSuccess to indicate that a booked contract has 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 is required.
Another option is to mark the forecasted renewal deal linked to the booked contract as "Lost". 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.
Is it possible to require HubSpot line items before closing a deal?
At this time, it is our understanding that it is not possible to require line items before closing a deal. You can use HubSpot workflows to push notifications if there is a recently closed deal that has no line items.