Quotes

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.

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

• Creation of legacy or proposal quotes through the v3 API. Only the CUSTOMIZABLE_QUOTE_TEMPLATE template type can be used when creating quotes with the v3 API. Learn more about associating quotes with quote templates.
• 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.

To create a quote, make a POST request to /crm/v3/objects/quote.

In the post body, include the following required properties:

Along with properties, you can also specify associations in the create request. However, you can also use the associations API to associate the quote after creation.

Associations

To associate the quote with other CRM records at the time of creation, include an associations array in the create request post body. The array will contain an object for each association. 

For a quote to be fully accessible, editable, and publishable in HubSpot, it must have the following associations:

• Quote template: the CMS template used to render a quote, along with default configuration settings for the quote such as language. To get the quote template ID, make a GET request to /crm/v3/objects/quote_template?properties=hs_name,hs_active to get a list of active quote templates. Learn more about creating custom quote templates. You can only associate a quote with one quote template.
• Deal: the deal record in HubSpot for tracking revenue and lifecycle. A quote inherits certain values from the associated deal, including the owner and currency. You can only associate a quote with one deal.
• Line items: individual products or services being sold as part of the quote. Use the line items API to create standalone line items or line items based on existing products (whether created through the products API or in HubSpot). You can get a line item's ID through the line items API, and the ID will also be returned when you create a line item.

Optional associations

In addition, you can associate a quote with the following:

• Contacts: specific buyers that you're addressing in the quote.
• Companies: a specific company that you're addressing in the quote. You can only associate a quote to one company.
• Discounts, fees and taxes: any applicable discounts, fees, and taxes to charge on the quote at checkout. When HubSpot determines the total quote amount, discounts will be applied first, then fees, followed by taxes. You can use the hs_sort_orderfield 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.

For example, the following post body would create a quote with the name "New quote" and associate it with a quote template (ID: 12345) and a deal (ID: 67890).

When you're done configuring your quote, you can update its state by making a PATCH request to /crm/v3/objects/quote/{QUOTE_ID}.

A quote's state is derived from the hs_status field. 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, 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 the hs_status field is set to PENDING_APPROVAL or REJECTED.
• Published: a quote will be published at a publicly accessible URL once the hs_status field is set to APPROVAL_NOT_NEEDED or APPROVED. Note that APPROVED is only for use in quote approval workflows.

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

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 Editable, Publishable, 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.

The following scopes are required for an app 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