Overview

The HubSpot Revenue Management Integration provides a wealth of insights to help you manage and improve the health of your business.

1. View current customer revenue, products purchased, and contract terms
2. Manage renewal and post-sales opportunities, forecasts, and workflow
3. 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
• Terminology
• Prerequisites
• Integration Survey
• Step 1: Integrations Configuration Page
• Step 2: Field Mappings
• Step 2a: Field Mappings - Contracts (Deals)
  • Renewal Relationships
  • Up-sells and Adjustments
• Step 2b: Field Mappings - Contract Line Items
  • Example Field Mapping - Deals + Line Items
  • Example Field Mapping - Deals Only
• Step 3: Product List and Product External IDs 
• Step 4: Pull One Contract from HubSpot
• Step 5: Sync Filter
• Step 6: Stage Mappings
• Step 7: Bi-Directional Sync and Sync Frequency
• FAQs

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

Here is an example of a HubSpot Deals with Line Items (in red square).

Prerequisites

• Connect to the HubSpot Deals object or Deals and Line Items
• Deals must be associated with a HubSpot Company 
• The following data elements are required on contracts brought over from HubSpot
  • Client name
  • 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)
  • Close date
  • Stage
  • Sync indicator
• 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.

Step 1: Integrations Configuration Page

In this step, you will set up the mapping between the ClientSuccess and HubSpot objects. Please review HubSpot Integrations Configuration for a general overview of how to use this page.

1. Ensure you have authenticated to HubSpot via ClientSuccess
2. Let your CSM know that you would like to use the new Revenue Management module. They will make sure your tenant is configured appropriately.
3. Decide which implementation model you will use: Deals or Deals and Line Items (as listed in the Prerequisites section above).  
4. If you use Line Items, make sure the “Use Contract Items” checkbox is checked on the main Integration Settings page. If you do NOT use Line Items then make sure the “Use Contract Items” checkbox is UNchecked.

Step 2: Field Mappings

In this step, you will configure your field level mappings. Please review the HubSpot Field Mappings Configuration Guide first for an explanation of how this page works.

1. Map your HubSpot Deal level data to ClientSuccess Contracts. 
2. Map your HubSpot Line Item level data to ClientSuccess Contract Line Items, ONLY IF you use Line Items in HubSpot. If you have one and only one product per Deal, you do NOT need to map Contract Line Items.

Step 2a: Field Mappings - Contracts (Deals)

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.

OR

As an example, here are the steps to create a renewal linkage using HubSpot workflow:

1. Create a new field on the Company object: "Last Deal Won ID"
2. When a new deal is won, copy the HubSpot ID of this deal into the Company field: "Last Deal Won ID"
3. Copy the "Last Deal Won ID" to any new deals created in HubSpot
4. Map the HubSpot Deal field “Last Deal Won ID” to the “Renews ID - CRM ID” field in ClientSuccess
5. 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

Step 2b: Field Mappings - Contract Line Items

NOTE: These field mappings enable you to have multiple products per contract.  If setting up these field mappings, make sure “Use Contract Items” checkbox is checked on the main Integration Settings page

Example Mapping for Deals w/Line Items:

Contracts (Deals) 

Contract Line Items (HubSpot Line Items)

Example Mapping WITHOUT Line Items (Contract only)

Step 3: Product List and Product External IDs 

1. 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:

2. 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.
3. A unique SKU/Product Code must be present for each product. This will be used in future reporting
4. If you are not using Line Items, ClientSuccess can look up product information by HubSpot ID, code, or description

Step 4: Pull One Contract from HubSpot

1. Once your fields are mapped and your products are in ClientSuccess, please work with your CSM to pull over one deal to test.  
2. Ensure the one deal you want to import matches the sync filter.
3. Review the Integration History for any errors. You can filter for “400” in the Result column, “Contract” in the Resource column and review the Error Message column for a description of any errors. 

4. Review the “Revenue” module for the sample account to ensure the contract came over as expected. You may need to configure your stages – please see “Step 6: Stage Mappings” section

Step 5: Sync Filter

1. Once the sample deal comes over to ClientSuccess as expected, you can now set the sync filter on all applicable deals.
2. In order to establish renewal linkage, you want to ensure that the first new deal for a client and all renewal deals including forecasted, renewed, and churned/terminated renewals are brought over. Any deal that has been created after the initial sale should be brought over.

3. We strongly recommend utilizing the "Sync Preview" Report before enabling the sync. This report will show you how many deals will be brought over. This report will also show you the values for any mapped fields and how they will be updated in ClientSuccess/HubSpot. 
   
   

4. Please work with your CSM to pull over all applicable deals

Step 6: Stage Mappings

1. Stage is required for ALL contracts 
2. Stage configuration is dynamic to meet the needs of all customers who configure their stages differently 
3. 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
4. Stage Names do NOT need to be added in advance (unlike Product Names)
5. Stages must be configured in order to display booked, forecast, and lost renewals
6. If stages are not set, all Contracts will default to a "Forecast" status
7. There are three Stage Categories found in the “Stage” field for contracts
   1. Booked = Closed Won (Cash in Hand/Paid Contracts).  No longer in a forecast stage
   2. Lost = Closed Lost. No longer in a forecast stage
   3. Not Set = Any state not Lost or Booked and indicates a Forecasted Contract.  
8. Do not configure stages until you have sync’d deals into ClientSuccess
9. Once you have mapped the stages, you will need to do another import of your contracts for the contract stages to be set correctly.

Step 7: Sync Frequency

1. After you have successfully pulled deals from HubSpot into ClientSuccess, you can turn on the scheduled sync to automatically update contracts in ClientSuccess from deals in HubSpot. 
2. Please see HubSpot Field Mappings Configuration for information on setting the applicable sync frequency

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.