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:
Parameter | Description |
---|---|
hs_title
| The name of the quote. |
hs_expiration_date
| The date that the quote expires. |
crm/v3/properties/quotes
.
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_order
field to reorder objects of the same type. Discounts, fees, and taxes can be specified as fixed values or percentages by setting thehs_type
field to eitherFIXED
orPERCENT
.
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
).
associationTypeId
, make a GET
request to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels
. Learn more about the associations API.
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 toDRAFT
, 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 toPENDING_APPROVAL
orREJECTED
. - Published: a quote will be published at a publicly accessible URL once the
hs_status
field is set toAPPROVAL_NOT_NEEDED
orAPPROVED
. Note thatAPPROVED
is only for use in quote approval workflows.
For example, the following request would update a quote to a Published state:
Please note: by default, HubSpot will set the quote's hs_template_type
property to CUSTOMIZABLE_QUOTE_TEMPLATE
after you update the quote's state. This template type is supported by the v3 API, whereas the following template types are legacy templates that are no longer supported:
QUOTE
PROPOSAL
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 thehs_status
of the quote back toDRAFT
,PENDING_APPROVAL
, orREJECTED
.
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
Thank you for your feedback, it means a lot to us.