Quotes

Please note: HubSpot has recently released several new features to the Quotes API. These features are currently in beta. They are under development, and are subject to change based on testing and feedback. By using these features, you agree to adhere to HubSpot's Developer Terms Developer Beta Terms.

The new features currently in beta include:

  • Creating and updating quotes
  • Managing discounts, fees, and taxes
  • Associating discounts, fees, and taxes with a quote
  • OAuth access and the new scopes listed below
The previously released endpoints to retrieve existing quotes are still fully supported, and will not be receiving breaking changes without advanced notice.

In HubSpot, quotes are used to share pricing information with potential buyers. The quotes endpoints allow you to create, retrieve, and sync quotes between HubSpot and other systems.

Structure of a quote

A fully defined quote consists of a core quote object, a quote template, along with several other associated objects. The core object includes several metadata fields such as name and status. You can then associate contact, company, or deal records with the quote, as well as line items, fee, tax, or discount data.

The following CRM objects and fields are required to create a full quote that you can publish and edit within your HubSpot account:

  • Core quote object: an object that stores metadata such as the quote's name, status, and domain.
  • Quote template: the CMS template used to render a quote, along with default configuration settings for the quote such as language.
  • Line items: individual records of items or services being sold as part of the quote.
  • Deal: a full quote inherits certain values from the associated deal, including the currency. 

You can also associate the following optional properties when building out a full quote:

  • Fee: any applicable fees
  • Tax: any applicable taxes
  • Discount: any applicable discounts
  • Contact: specific customers that you're addressing in the quote
  • Company: a specific company that you're addressing in the quote

Quote state

A quote's state is derived from the hs_status field within the core quote object. Certain quote states allow you to edit, publish, automate, or report the quote using the quotes tool in your HubSpot account.

  • Minimal: if no value is provided for the hs_status field of the core quote object, the quote will be in a Minimal state. The quote will appear on the index page of the quotes tool, but cannot be edited directly. Quotes in a Minimal state can still be used in automation, such as the sequences tool, and are also available to analyze within the reporting tool.
  • Editable: when you set the hs_status field to DRAFT, the quote's will be in an Editable state, which allows you to edit the quote directly in the quotes tool.
  • Publishable: a quote will shift to a Publishable state once you update the hs_status field to PENDING_APPROVAL or REJECTED.
  • Published: a quote will be published at a publicly accessible URL once the hs_status field is set to PUBLISHED.

Limitations

The following functionality is not currently supported when using the v3 quotes API:

  • Creation of legacy or proposal quotes through the v3 API
  • Creation or modification of quote templates. Quote templates must be created or customized within your HubSpot account before they can be referenced using the v3 quotes API.
  • Usage of Esign, Stripe payments, or HubSpot payments
  • Usage of recurring quote-level discounts, fees, or taxes

Take note of the following limitations when creating a quote:

  • Quotes templates must be created in your HubSpot account before they can be associated with a quote using the API.
  • Quotes with a Publishable or Published status must have an associated deal.

Scopes

The following scopes are required to create a valid publishable quote:

  • crm.objects.quotes.write, crm.objects.quotes.read, crm.objects.line_items.write, crm.objects.line_items.read, crm.objects.owners.read, crm.objects.contacts.write, crm.objects.contacts.read, crm.objects.deals.write, crm.objects.deals.read, crm.objects.companies.write, crm.objects.companies.read
  • crm.schemas.quote.read, crm.schemas.line_items.read, crm.schemas.contacts.read, crm.schemas.deals.read, crm.schemas.companies.read

Create a quote

To create a quote via the v3 API, you'll first create the core quote object, then associate a deal, quote template, and any line items. You can optionally associate a company or contacts with the quote, along with configuring any discounts, fees, or taxes. Based on how you plan to edit and use the quote, you can then update the quote's status.

Create a core quote object

To begin, create a quote in Minimal state by making a POST request to /crm/v3/objects/quote and provide a name and expiration date:

// POST request to https://api.hubapi.com/crm/v3/objects/quote { "properties": { "hs_title": "A new quote", "hs_expiration_date": "2022-04-02" } }

Associate a deal

Once you've created the core quote object, you can associate a deal by making a PUT request to /crm/v3/objects/deal/{DEAL_ID}/associations/quote/{QUOTE_ID}/deal_to_quote:

  • To get the DEAL_ID, you can make a GET request to /crm/v3/objects/deals. Learn more about the deals API here.
  • After you associate the deal, the quote will inherit its owner and team details.
  • Only one deal can be associated with a quote.

Associate a quote template

Next, associate an existing quote template with your quote by making a PUT request to /crm/v3/objects/quote_template/{QUOTE_TEMPLATE_ID}/associations/quote/{QUOTE_ID}/quote_template_to_quote

  • To get the QUOTE_TEMPLATE_ID, make a GET request to /crm/v3/objects?properties=hs_name,hs_active to get a list of active quote templates you can associate.
  • Only one quote template can be associated with a quote.

Create and associate line items

You can use the line items API to create line items that you can associate with your quote. To create a standalone line item, make a POST request to /crm/v3/objects/line_item:

// POST request to https://api.hubapi.com/crm/v3/objects/line_item { "properties": { "price": 10, "quantity": 1, "name": "New standalone line item" } }

You can also create a line item based on an existing product, by providing the hs_product_id in the properties field of your request, along with any other product fields that you want your new line item to inherit:

// POST request to https://api.hubapi.com/crm/v3/objects/line_item { "properties": { "hs_product_id": "1360404657", "hs_line_item_currency_code": "EUR", "name": "Product-derived line item" } }

Once you've created your line items, you can associate them with your quote by making a PUT request to /crm/v3/objects/line_item/{LINE_ITEM_ID}/associations/quote/{QUOTE_ID}/line_item_to_quote

If you need to look up the ID of a line item, you can make a GET request to /crm/v3/objects/line_item. The ID will also be returned in the response when you create a line item.

Associate a company and contacts

You can optionally associate a company or individual contacts with your quote. Only one company can be associated with a quote, but you can associate multiple contacts.

  • To associate a company with your quote, make a PUT request to /crm/v3/objects/company/{COMPANY_ID}/associations/quote/{QUOTE_ID}/company_to_quote
  • To associate a contact, make a PUT request to /crm/v3/objects/contact/{CONTACT_ID}/associations/quote/{QUOTE_ID}/contact_to_quote.

Create and associate discounts, fees, and taxes

The final step of building out your quote is to create and associate any discounts, fees, and taxes. When making these associations, keep the following in mind:

  • When HubSpot determines the total quote amount, discounts will be applied first, then fees, followed by taxes. You can use the hs_sort_order field to reorder objects of the same type.
  • Discounts, fees, and taxes can be specified as fixed values or percentages by setting the hs_type field to either FIXED or PERCENT.

To create a discount:

// POST request to https://api.hubspi.com/crm/v3/objects/discount { "properties": { "hs_label": "A fixed, one-time discount", "hs_duration": "ONCE", "hs_type": "PERCENT", "hs_value": "50", "hs_sort_order": "2" } }

To create a percentage fee:

// POST request to https://api.hubspi.com/crm/v3/objects/fee { "properties": { "hs_label": "A percentage-based fee of 10%", "hs_type": "PERCENT", "hs_value": "10", } }

To create a percentage tax:

// POST request to https://api.hubspi.com/crm/v3/objects/tax { "properties": { "hs_label": "A percentage-based tax of 6.5%", "hs_type": "PERCENT", "hs_value": "6.5" } }

After you've created any discounts, taxes, and fees, associate them to your quote:

  • To associate a discount, make a PUT request to /crm/v3/objects/discount/{DISCOUNT_ID}/associations/quote/{QUOTE_ID}/discount_to_quote.
  • To associate a fee, make a PUT request to /crm/v3/objects/fee/{FEE_ID}/associations/quote/{QUOTE_ID}/fee_to_quote.
  • To associate a tax, make a PUT request to /crm/v3/objects/tax/{TAX_ID}/associations/quote/{QUOTE_ID}/tax_to_quote.

Update quote state

When you're done configuring your quote, you can update its state by making a PATCH request to /crm/v3/objects/quote/{QUOTE_ID}. Learn more about the different quote states in the section above. 

For example, the following request would update a quote to a Published state:

// PATCH request to https://api.hubapi.com/crm/v3/objects/quote/{QUOTE_ID} { "properties" { "hs_status": "APPROVAL_NOT_NEEDED" } }

Based on the new state of the quote, some derived properties will be automatically updated on the quote object.

If you update a quote to a EditablePublishable, or Published state, the following properties will be derived as follows:

  • hs_quote_amount: calculated based on any associated line items, taxes, discounts, and fees.
  • hs_domain: set from the associated quote template.
  • hs_slug: randomly generated if one is not explicitly provided.
  • hs_quote_total_preference: set based on your account settings. If you haven't configured this setting, it will default to the value of the total_first_payment field.
  • hs_timezone: defaults to your HubSpot account's timezone.
  • hs_locale: set from the associated quote template.
  • hs_quote_number: set based on the current date and time, unless one is provided.
  • hs_language: set from the associated quote template.
  • hs_currency: set based on the associated deal. If you haven't associated a deal with the quote, it will default to your HubSpot account's default currency.

Additionally, the properties below will be calculated when the quote switches to a Published state:

  • hs_pdf_download_link: populated with a URL of a PDF for the quote.
  • hs_locked: set to true. To modify any properties after you've published a quote, you must first update the hs_status of the quote back to DRAFT, PENDING_APPROVAL, or REJECTED.

Once a quote is published, you can view the URL of the publicly accessible quote by concatenating the hs_domain and hs_slug fields.


Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.