Migrate contracts to HubSpot

Last updated: July 23, 2026

Available with any of the following subscriptions, except where noted:

Revenue Hub Professional, Enterprise

Seats required

Subscription required A Revenue Hub subscription is required to migrate contracts.

Seats required A Revenue Hub seat is required to migrate contracts.

Permissions required Super Admin permissions are required to perform the migration.

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

Please note: 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.
After activation, you can update Billing Start Date Override and Payment Method ID only if the contract has no paid invoices or payments.

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., upgrades or expansions).

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., upgrades, expansions, downgrades) in the MRR waterfall in HubSpot. 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.

Ramps

Ramp keys

Ramp keys group multiple line item rows into phases. Rows with the same ramp key are treated as one continuous ramp.

In HubSpot, each ramp phase generates MRR events (e.g., new business, upgrade, expansion) as each phase begins. The ramp key can be any text string (e.g., ramp-a). The same string must be shared across all rows of that ramp.

Structuring a ramp

To migrate ramps successfully, structure them as follows:

Non-overlapping date ranges: each row's terms must not overlap with another row's terms. If the ramp phases must be continuous, each phase should start when the previous phase ends.
Terms per phase: each row's term covers only that phase of the contract, not the full contract term.
Total quantity on each row: enter the total quantity for the line item during that phase
Ramp key import ID: groups the line items under the same ramp. Learn more about creating a custom ramp property.

Please note:

A contract can include ramped and non-ramped line items. For non-ramped line items, leave the ramp_key_import_id blank and use the same import_unique_id as the related contract rows.
A contract can have multiple products that ramp independently. Each product must have its own ramp_key_import_id. Each ramp generates its own MRR events.

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

Line item	Unit price	Quantity	Term	Start date	ramp_key_import_id
Monthly service	$100	1	3 months	Jan. 1, 2026	`ramp-a`
Monthly service	$100	2	9 months	April 1, 2026	`ramp-a`

Possible migration formats

Migration format	Collection process	Revenue continuity
Manual payments with no revenue continuity	Manual payments	Not included
Manual payments with revenue continuity	Manual payments	Includes
Automatic payments with no revenue continuity	Automatic payments	Not included
Automatic payments with revenue continuity	Automatic payments	Included

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.

Migration format	Object	Custom property name	Custom property type	Validation rules	Used for
All options	Contracts	`import_unique_id`	Single-line text	Require unique values	Groups all rows that belong to the same contract.
Manual payments with revenue continuity or Automatic payments with revenue continuity	Line items	`ramp_key_import_id`	Single-line text	None	Groups multiple line item rows into phases.

Configure the CSV file

Configure the CSV file to use with the import tool to migrate contracts to HubSpot.

CSV sample files

Use the sample CSV files below, depending on the migration format you're using.

Migration format	CSV link
Manual payments, no revenue continuity	Download
Manual payments with revenue continuity	Download
Automatic payments, no revenue continuity	Download
Automatic payments with revenue continuity	Download
Mixed: one ramped product and one flat-fee product (with no ramp key)	Download
Multiple independent ramps: Product A (`ramp-a`) and Product B (`ramp-b`) ramp separately	Download

CSV format

Your CSV should include the following columns and HubSpot properties.

Column name	Object	Property	Details
Contract effective date	Contract	`hs_contract_effective_date`	The date when the contract becomes legally effective.
Currency code	Contract	`hs_currency_code`	Currency code, such as USD.
Name	Contract	`hs_name`	Contract name.
HubSpot billing enabled	Contract	`hs_hubspot_billing_enabled`	Must be `TRUE` for all contracts being migrated.
Collection process	Contract	`hs_collection_process`	Manual or automatic. Must align with the migration format.
Billing start date override	Contract	`hs_billing_start_date_override`	The date HubSpot begins billing. This must be a future date when migrating. Required for all migration formats.
Payment method ID	Contract	`hs_external_payment_method_reference_id`	Leave blank for manual payments. Required for automatic payments.
Email	Contact	`email`	The billing contact's email address.
First name	Contact	`firstname`	First name of the billing contact.
Last name	Contact	`lastname`	Last name of the billing contact.
Product	Line item	`hs_product_id`	Record ID of the product. The migration references an existing product record and doesn’t create a new product
Line item name	Line item	`name`	Line item name.
Unit price	Line item	`price`	Per-unit price in the contract currency.
Quantity	Line item	`quantity`	The line item quantity during a phase.
import_unique_id	Line item	Custom property	Shared ID for all rows in the same contract.
Term	Line item	`hs_recurring_billing_period`	The line item term. When using ramps, enter the term for each segment.
Recurring billing frequency	Line item	`recurringbillingfrequency`	Billing frequency (e.g., monthly).
Line item start date	Line item	`hs_recurring_billing_start_date`	Billing start date for the line item.
ramp_key_import_id	Line item	Custom property	Groups line item phases into one ramp. Required for revenue continuity. Leave this blank for migration formats without revenue continuity.

Start the migration

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

In your HubSpot account, click More, then navigate to Revenue > Contracts. If More doesn't appear in your account, navigate to Revenue > Contracts directly.
In the upper right, click Import.
In the Import a file section, click Import data.
Click Advanced imports (all objects).
Under Objects, click Contracts. The line items object will be selected automatically.
In the bottom right, click Next.
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.
In the bottom right, click Next.
Map the columns in the import file to HubSpot properties. Learn more about the CSV property mappings.
In the bottom right, click Next.
In the Import name field, enter a name for the import.
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.
Click the Date format dropdown menu and select a date format.
Click the Time zone dropdown menu and select a time zone.
Click the Number format dropdown menu and select a number format.
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.
Select the Enrich records checkbox to enrich records during import. Learn more about contact and company enrichment.
In the bottom right, click Finish import.

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.

Billing start date override in the past

The Billing start date override in the past error occurs when the billing start date of a line item in the CSV is in the past.

To resolve this error:

Update any billing dates to a future date.
Save the CSV and start the import again.

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.