BetaMigrate contracts to HubSpot

Summary

Migrate existing contracts from a legacy system to HubSpot to manage billing, invoicing, and revenue reporting. The migration preserves payment methods, contract history, and future billing schedules. After migration, you can use HubSpot as the centralized source of truth for committed revenue. Learn more about using contracts in HubSpot.

Before you get started

Before you begin working with this feature, make sure to fully understand what steps should be taken ahead of time, as well as the limitations of the feature and potential consequences of using it.

Understand requirements

• If you're a Super Admin, you can opt your account into the Billing Migrations onto Revenue Hub Contracts beta.

• Your HubSpot account must use Stripe as a payment processing option. If you're using HubSpot payments and want to migrate payment methods from an external Stripe account to HubSpot payments, fill out this form.

• Format the CSV based on the payment collection process and revenue continuity option you select. Learn more about choosing the migration format best suited for your business.

Understand limitations and considerations

• If using revenue continuity, test the import in a sandbox environment. If incorrect data is imported into your account, you can't correct historical data in MRR waterfall reports.
• Once a contract is activated, HubSpot becomes the system of record for billing. The migration can't be undone. Any contract updates must be made in HubSpot. Learn more about viewing and managing contracts.
• Migration does not stop billing in the legacy system.

Choose the migration format

Before migrating, select a migration format based on how you want HubSpot to manage contracts after migration. The migration format depends on the collection process and whether you want to include historical contract change events (e.g., expansions and contractions).

Payment collection process

• Manual payments: after migration, invoices are generated for buyers to pay manually.
• Automatic payments: after migration, invoices are automatically charged using a payment method on file.

Revenue continuity

• No revenue continuity: contracts are imported without revenue change events.
• Revenue continuity: use ramp keys to group line items into phases and display change events (e.g., expansions and contractions) in the MRR waterfall in HubSpot.
  • Revenue continuity preserves recurring-revenue change events for reporting. It does not recreate historical invoices or payments.
  • If using revenue continuity, test the import in a sandbox environment.
  • If incorrect data is imported into your account, you can only correct historical data in MRR waterfall reports by deleting the contract associated with the incorrect data and reimporting it.

Ramps

Ramp keys

Ramp keys group multiple line item rows into phases. Rows with the same ramp key represent one continuous recurring stream that changes over time.

In HubSpot, each ramp phase generates MRR events (e.g., new business, expansion, contraction) as each phase begins. The ramp key can be any text string (e.g., ramp-a). Use the same string for every phase of the same ramp.

Structuring a ramp

To migrate ramps successfully, structure them as follows:

• Use one ramp key for each recurring stream: assign the same ramp key to all phases of a single product or service.
• Use the same key for sequential phases: if one phase follows another for the same product or service, use the same ramp key for both phases.
• Use different keys for concurrent products: if multiple products or services ramp independently during the same period, assign each one a different ramp_key_import_id.
• Leave the key blank for flat products: if a product or service doesn't change during the contract, leave the ramp_key_import_id field blank.
• Use non-overlapping date ranges: date ranges for rows with the same ramp key can't overlap. For continuous phases, start each phase when the previous phase ends.
• Enter the total state for each phase: each phase row must include the total quantity or value for that phase, not the change from the previous phase. For example, if the quantity increases from one to two, enter 2 for the second phase, not 1.
• Use the ramp key import ID to group phases: enter the same value in ramp_key_import_id for all line items in the same ramp. Learn more about creating a custom ramp property.

For example, for a 12-month contract with a price change after three months:

Possible migration formats

Monthly and quarterly billing import examples

Understand how monthly and quarterly contracts are billed after import, based on the contract effective date, line item start date, term, and billing start date override.

Property definitions

Monthly and quarterly examples

When the billing start date override falls between two cadence dates, HubSpot skips to the next scheduled cadence date after the override. The cadence anchor (line item start date) is never moved.

Lifecycle of a migration

Review the full lifecycle of a contract migration below:

Prepare for the migration

Before beginning the migration, set up your account and prepare your CSV file based on the selected migration format.

Create custom properties

Create the required custom properties before importing your CSV. The properties you need to create depend on the selected migration format. Learn more about creating custom properties.

Configure the CSV file

Configure the CSV file to use with the import tool to migrate contracts to HubSpot. Below, review import behaviors of specific CSV fields, download sample CSV files, and reference how a contract import CSV should be formatted.

Line item types

When importing contracts, each row in your CSV is treated as one of two line item types, depending on whether the Product field is populated.

• Product-backed: the Product field contains the record ID of an existing HubSpot product. If any supported fields (such as pricing model, tiers, price, term, billing frequency, or tax category) are left blank in the CSV, the row inherits those values from the linked product.

• Standalone: the Product field is left blank. The row uses only the values supplied in the CSV and the line item isn't linked to any product in your catalog.

Please note: if a product-backed row references a recurring product but leaves recurrence fields blank, it may inherit the product's recurring billing frequency configuration, even if the charge was intended as one-time.

Evergreen contracts

An evergreen recurring line item has a recurring billing frequency and no term. It automatically renews until canceled and has no recurring billing end date. While the contract is active, billing continues per the billing frequency cadence until the contract is canceled or terminated. Contract end date, TCV, and ACV may remain blank, while Current MRR and Current ARR are still calculated.

Pricing models

When importing contracts, existing pricing models and tiers may be applied, depending on whether the Unit price field is populated.

• If the Product field contains a valid HubSpot product record ID and the Unit price is blank, the imported product uses the existing pricing model and tiers.
• If the Product field contains a valid HubSpot product record ID and the Unit price field is populated, the row keeps its product association and uses the entered amount as a flat-rate price. The existing pricing models and tiers of the product are not amended.

Payment terms

When importing contracts, if you don't add the hs_net_payment_terms invoice property to your CSV, the net payment term defaults to 0 (Due on receipt), regardless of your account's invoice default settings. To use different payment terms, include the property in your CSV with the desired value (e.g., a value of 0 sets invoices to be due on receipt. A value of 30 would set invoices to have net 30 payment terms).

Automated sales tax

If you're based in the U.S. or Canada and want to calculate sales taxes automatically, configure automated sales tax in your account settings before importing contracts.

CSV sample files

Use the sample CSV files below to guide your migration.

Please note: CSV files are for illustrative purposes only. Replace sample dates, identifiers, Product IDs, contacts, amounts, currencies, and any import_unique_id entries in the CSV. Verify the mapped properties and drafts before proceeding with migration.

CSV format

Your CSV should include the following columns and HubSpot properties.

Migrate contracts

Begin migrating contracts, including testing localization before commencing the final migration.

Localization testing before migration

If you serve customers in different languages and regions, it's recommended to carry out a pilot migration per language, region, and currency. You can void invoices and terminate contracts after confirming a successful migration.

1. Add the contracts to a CSV file. Learn more about configuring a CSV for import.
2. Start and complete the migration.
3. Wait for invoices to be generated for the contract.
4. Check the invoice for accuracy. Learn more about managing invoices:
   • View the invoice in a new browser tab.
   • Download a PDF of the invoice.
   • Send the invoice to an internal email address.
5. For each, verify translated labels, dates, numbers, currency symbols, character rendering, sender, recipient, and links. 

Please note: this is an end-to-end pilot, not a pre-activation preview feature.

Start the migration

After you've configured your CSV, you can start migrating contracts to HubSpot. 

1. In your HubSpot account, click More, then navigate to Revenue > Contracts. If More doesn't appear in your account, navigate to Revenue > Contracts directly.
2. In the upper right, click Import.
3. In the Import a file section, click Import data.
4. Click Advanced imports (all objects).
5. Under Objects, click Contracts. The contacts and line items objects are selected automatically. You can also import other objects (e.g., companies and deals) at the same time. Learn more about importing multiple objects.
6. In the bottom right, click Next.
7. Click the Choose how to import Contacts dropdown menu and select an option:
   • Create new contacts only: create new contact records for the imported contacts.
   • Create and update existing contacts: create new contact records when a contact doesn't exist in the CRM. Update a contact if it already exists. If you select this option, each record must have a unique identifier.
8. Click the Choose how to import Line items dropdown menu and select Create new line items only. 

Please note: selecting Create and update for line items without a unique identifier can cause identical line items from different contracts to merge, leaving some contracts without their associated products. It's recommended to select Create new line items to avoid merging.

9. Configure how you want to import your data:
   • Upload a file: drag and drop, or click choose a file, then select your import file.
   • Copy and paste: click paste directly from your spreadsheet and paste your data. Data must be copied from a spreadsheet file (e.g., Numbers, Google Sheets).
   • Language: if you're importing data in a language other than your default language, click the Select the language of the column headers in your file dropdown menu and select the language. Selecting the correct language allows HubSpot to better match your column headers to existing default properties. If there is no match in your selected language, HubSpot will search for an English property to match.
10. In the bottom right, click Next.
11. Map the columns in the import file to HubSpot properties. Learn more about the CSV property mappings.
12. In the bottom right, click Next.
13. In the Import name field, enter a name for the import.
14. Click the Select the legal basis for processing a contact's data dropdown menu and select a legal basis. Learn more about tracking legal basis of processing in HubSpot.
15. Click the Date format dropdown menu and select a date format.
16. Click the Time zone dropdown menu and select a time zone.
17. Click the Number format dropdown menu and select a number format.
18. Select the Set these contacts as marketing contacts checkbox if you want to engage the imported contacts using HubSpot's marketing tools. Learn more about marketing contacts.
19. Select the Enrich records checkbox to enrich records during import. Learn more about contact and company enrichment.
20. In the bottom right, click Finish import.
21. Continue to complete the migration.

Review formatting issues

After you click Finish import, imported contracts are created as draft contracts. Review contact formatting issues and row errors before completing the migration:

Please note: a scheduled billing row with -- as its invoice number is a projected entry. Generated invoices receive a number and are indexed with other invoice records.

1. To clean up formatting issues, under Clean up imported data click the value (e.g., 1) under [Object] formatting issues.
   
   
   
2. Under Formatting issues, click View issues.
   
   
   
3. In the table, review the issues and proposed fixes:
   • To edit the proposed fix, in the Proposed fix column, click the Edit icon, and enter a new value.
   • To accept all proposed fixes, click Accept all.
   • To reject all proposed fixes, click Reject all.
   • To accept or reject a proposed fix for an individual row, in the Actions column, click Accept or Reject.
   • To delete the record from the import, in the Actions column, click More, then select Delete this record.
4. Navigate back to your import:
   • In your HubSpot account, click More, then navigate to Data Management > Data Integration. If More doesn't appear in your account, navigate to Data Management > Data Integration directly.
   • In the Monitor your imports & syncs table, click the import name.

Complete the migration

Please note: users with View, Create, Edit, or Delete permissions for contracts can view contracts that have been imported but are not yet migrated. Users with Create, Edit, or Delete permissions for contracts can validate, edit, migrate, and delete the draft contracts created from the import.

1. Click Complete migration.
   
   
   
2. Review contracts that need attention. To download the errors as a CSV file, in the upper right, click Download errors as CSV.
3. To correct the errors, in the Error column, click Update [property]. 
   
   
   
4. In the dialog box, update the required properties, then click Re-validate contract.
5. The re-validated contract will move to the Ready to migrate tab.
6. When you have reviewed any contracts that need attention, click the Ready to migrate tab.
7. It's recommended to review the following properties of the contracts before finalizing the migration:
   • Collection process
   • Payment method
   • Dates
   • Product associations
   • Line items
   • Schedule
   • Tax configuration
8. To make changes to the billing start date or external payment method reference ID, click the Edit icon.

Please note: you can only update Billing Start Date Override and hs_external_payment_method_reference_id if the contract has no paid invoices or payments.

9. In the dialog box:
   • Under Billing start date override field, click the date picker and select a date.
   • In the Payment method ID field, enter a payment method ID.
   • Click Re-validate contract.
10. The contract will move to the Ready to migrate tab when it has re-validated.
    
    
    
11. As a final step before migration, review the following:
    1. The last invoice from the legacy contract.
    2. The first HubSpot invoice.
    3. Any open receivables.
    4. Legacy subscription cancellation where applicable.
    5. Dunning.
    6. Invoice emails.
    7. Accounting-integration verification. Learn more about connecting Quickbooks Online and Xero to HubSpot. 
12. In the upper right, click Migrate [x] contracts.
    
    
    
13. In the dialog box, review the migration terms, select the I understand and agree checkbox, then click Confirm migration.
14. Contracts will be imported and billing commences, based on the migration format chosen. Learn more about viewing and managing contracts.

Troubleshooting

Review common import errors and the steps to resolve them. If you encounter another error, review your CSV formatting and property mappings, then retry the import.

Invalid or missing Stripe payment method ID

This error occurs when the automatic payments option is selected as the collection process but a Stripe payment method ID was not added to the CSV file.

To resolve this error, either:

• Change automatic payments entries to manual payments.
• Add a Stripe payment method ID for automatic payments entries in the CSV.

Duplicate import_unique_id from a prior attempt

If an import fails, HubSpot may still register the import_unique_id values from the failed import.

To resolve this error:

1. Update your CSV file with new IDs.
2. Import the updated CSV file.

Glossary

Review the following terms before migrating contracts to HubSpot.