Quote migration property reference

Which quote and line item properties to set when you import quotes through the HubSpot API, including the hidden bundle fields Quotivity relies on.

Overview

This is the field guide for the import itself. It lists the quote and line item properties that change how Quotivity reads a migrated quote, what to put in each, and which ones Quotivity recalculates no matter what you import. Use the internal name in your API calls.

Properties not listed here are ordinary HubSpot data. Import them as you normally would. For the full list of what Quotivity adds to your portal, see Quotivity custom properties. For the planning side (statuses, import order, testing), start with Migrating quotes into Quotivity.

Quote properties

These live on the HubSpot quote record. The ones near the top decide whether the quote opens cleanly at all.

Field	Internal name	What to import
Status	`hs_status`	Create every quote as `DRAFT`. For anything final, set `APPROVAL_NOT_NEEDED` or `APPROVED` in a last update, after its line items and associations are attached, because HubSpot locks a published quote. Avoid `PENDING_APPROVAL` (see Choose a status for each quote). An empty status counts as a draft, so don’t leave it off historical quotes.
Currency	`hs_currency`	The same currency as the deal’s Deal Currency. If they differ, Quote Builder locks the quote and publishing is blocked.
Price Book	`hapily_price_book`	The price book’s ID. The dropdown’s internal values are your Quotivity price book IDs, kept in sync with Quotivity Studio. When your account has price books, a draft without one opens with the price book picker, and reps can’t add line items or publish until they choose one.
Title	`hs_title`	Required before a draft can be published.
Language and locale	`hs_language`, `hs_locale`	Import the original values. Quote Builder fills in the rep’s browser locale when the locale is empty.
Quotivity Template ID	`quotivity_template_id`	For accounts on Quotivity Templates: the ID of a published, active template. Quotivity adopts it the first time the quote opens in Quote Builder. Leave it empty for quotes that use a HubSpot quote template, and associate that template instead.
E-Signature Enabled	`quotivity_esign_enabled`	`true` or `false`. Quotivity reads it only when it adopts the template above. `true` turns on e-signature and takes signers from the quote’s signer associations. `false` sets no signature.
Expiration Period Option	`expiration_period_option`	`custom_date` keeps the expiration date you import. Any of the day presets (for example `30_days`) resets the expiration date when the quote is submitted, whether for approval or to publish.
Domain	`hs_domain`	Needed only for drafts on HubSpot templates when your account has no default quote domain in Settings.
Quote Type	`quotivity_quote_type`	Match the original quote: `NEW_BUSINESS`, `CHANGE`, or `RENEWAL`. Quotivity creates this property and only reports and rule conditions read it, so a migrated renewal shows up in renewal reporting from day one. It doesn’t change how the quote behaves: whether Quotivity treats a quote as a change or renewal comes from its contract links. Rules with a Quote Type condition do apply, so a rule that checks for Renewal runs on migrated renewal drafts the first time they open.
Created by Quotivity	`quote_hapily_created_by_quote_hapily`	Leave it empty. Quotivity doesn’t use it to decide how a quote behaves, and Yes would mislabel the quote in reports.

Revenue and margin properties behave differently by status. That covers TCV, ACV, ARR, MRR, the starting and ending ARR and MRR fields, Gross Margin, Margin Percentage, Sales Tax Amount, and your roll-up fields (Pro and Enterprise). On a published quote they stay exactly as imported, so fill them in if you want historical reporting. On a draft, Quotivity recalculates them from the line items. Your values are overwritten the first time a rep opens or saves it.

A few signature and acceptance fields are worth a second look:

Accepted By and Accepted Date (quotivity_accepted_by, quotivity_accepted_date): import them on won quotes. A value in Accepted By is what puts a quote in the accepted group on the deal card.
E-Signature Status (quotivity_esign_status): never pair Completed with a DRAFT status. Quotivity can treat that as someone recalling a signed quote, sets it back to Approval not needed, and creates a high-priority task for the quote owner.

Line item properties

Line items carry most of the pricing. HubSpot line items inherit every custom Product property, so the fields below are valid on line items even though some of them are defined on Product.

Field	Internal name	What to import
Product	`hs_product_id`	The HubSpot product ID for every catalog line. A line without one is treated as a custom line: Quotivity never reprices it and keeps it when a rep changes price books.
Unit price, quantity	`price`, `quantity`	The original values. On a draft, the price may be reset on save (see Pricing when a draft is saved).
Discount	`discount` or `hs_discount_percentage`	Set one or the other. HubSpot rejects a line item that has both.
Cost	`hs_cost_of_goods_sold`	Unit cost. Feeds margin.
Billing frequency and term	`recurringbillingfrequency`, `hs_recurring_billing_period`	Needed for recurring lines to count toward ARR, MRR, and ACV.
Position	`hs_position_on_quote`	The only thing that orders lines. Number them in order starting at `0`, and put each bundle header directly before its members.
List Price	`quote_hapily_list_price`	The catalog price at the time of the original quote, which discount columns compare against. Your value stays on published quotes, on Cost Plus lines (Enterprise), and on lines whose price book entry allows unit price editing. Elsewhere on a draft, Quotivity re-reads it from the price book on save. A Cost Plus line without it gets repriced from the product’s current cost.
Optional?	`quote_hapily_is_optional`	`true` for optional lines (Enterprise). Optional lines stay out of revenue totals and out of the deal’s line items.
Selected Product Variant	`quote_hapily_selected_product_variant`	Only for products with variants (Enterprise). On a draft, it has to match a variant in today’s price book. With no match, the line’s price, list price, and variant are cleared on the next save.
Pricing-table value	Your pricing-table property	Only for products priced by a pricing table. On a draft, it has to match a row in today’s table. With no match, the line’s price is set to `0` on the next save.
Calculated Unit Price	`quotivity_calculated_unit_price`	Leave it empty. Quotivity fills it in when a pricing formula (Enterprise) runs.

Ramped deals (Enterprise) come in as separate line items, one per period. Ramp groups live in Quotivity and can’t be imported, so each period counts toward ARR and MRR on its own and the starting and ending values match.

Bundle properties

Bundles are on Pro and Enterprise. A migrated bundle is a header line item plus one member line item per selected product, tied together by the hidden properties below. When every included option has a member, the first open adds nothing.

Field	Internal name	Header line	Member line
Is Bundle Header?	`quotivity_is_bundle_header`	`true`	`false`
Quotivity Bundle ID	`quote_hapily_bundle_id`	The bundle’s ID	The same bundle ID
Quotivity Bundle Option ID	`quote_hapily_bundle_option_id`	Empty	The ID of the option this product fills
Bundle Header Line Item ID	`quote_hapily_bundle_header_line_item_id`	Empty	The HubSpot line item ID of its header
Bundle Base Quantity	`quote_hapily_base_quantity`	Empty	The quantity for one bundle (see below)
Quantity	`quantity`	Number of bundles	Base quantity × header quantity

On drafts, leave Quotivity Bundle Option Name and Bundle Net Price empty. Quotivity fills the option name from the option and recalculates the net price on every update. Quotivity doesn’t fill Included Products Subtotal, Add-on Products Subtotal, or Original Bundle Header Cost on a migrated quote, and nothing recalculates any of these on a published quote, so import the ones your reports or templates use. Line Item Type is calculated by HubSpot from the fields above.

Three details decide whether a migrated bundle survives its first open, and a fourth matters the first time a rep changes a header’s quantity.

Members point at a HubSpot ID. Bundle Header Line Item ID holds the header’s HubSpot line item ID, which only exists after you create the header. Create headers first, read back their IDs, then create members.

Every included option needs a member. An included option is one with a minimum quantity above zero and a default product. If a header has no member for one of its included options, Quotivity adds a product for that option the first time the draft opens: the default product, or the lowest-priced eligible product when the default can’t be priced. Options that already have a member are left alone.

Included options need a product they can price. Each option is priced from its own price book, or from the quote’s price book when the bundle inherits quote pricing (Enterprise). If an included option has no product in that book, or a bundle that inherits quote pricing sits on a quote with no price book, Quotivity can’t build the bundle. It removes the header line item and shows an error. This check runs even when the members are already there.

Set the base quantity when the header quantity is above 1. Members scale as base quantity × header quantity. If a member has no Bundle Base Quantity and a rep later changes the header quantity, Quotivity uses the member’s current quantity as the base. An imported member that was already multiplied gets multiplied again.

Option IDs that don’t exist in Quotivity Studio (for example, an option you deleted) aren’t fatal. When the draft opens, Quotivity turns that member into a normal line item and shows “Bundle line items were repaired so this quote could be opened.”

A bundle from your old system that has no match in Quotivity Studio can’t be imported as a bundle. Import its products as ordinary line items with the bundle fields empty.

Finding the IDs you need

ID	Where to find it
Price book ID	The end of the URL when you open the price book in Quotivity Studio, or the Price Book property’s internal values in HubSpot property settings
Bundle ID	The end of the URL when you open the bundle in Quotivity Studio. The bundle’s header product in HubSpot also carries it in Quotivity Bundle ID.
Bundle option ID	Build one quote with the bundle in Quote Builder and read Quotivity Bundle Option ID off its member line items, or call List Bundle Options in the Quotivity API
Quotivity template ID	The end of the URL when you open the template in Quotivity Studio

These IDs belong to one HubSpot portal’s Quotivity account. A sandbox portal has its own.

Example

A distributor sells a “Field Starter Kit” bundle. In their old system, a draft quote has 3 kits, and each kit includes 2 mounting brackets and 1 sensor.

They create the header first: the kit’s header product, quantity 3, Is Bundle Header? true, and Quotivity Bundle ID set to the kit’s bundle ID. HubSpot returns line item ID 41022881990.

Then they create two members. Each has the same bundle ID, Is Bundle Header? false, and Bundle Header Line Item ID 41022881990:

Member	Option ID	Bundle Base Quantity	`quantity`	Position
Mounting bracket	The bracket option’s ID	2	6	1
Sensor	The sensor option’s ID	1	3	2

The header sits at position 0. When a rep opens the draft, Quotivity sees both included options filled and adds nothing. If the rep changes the kit quantity to 4, the brackets go to 8 and the sensors to 4.