Skip to main content

In HubSpot, line items are individual instances of products. When a product is attached to a deal, it becomes a line item. You can create line items that are unique to an individual quote, but they will not be added to your product library. The line items endpoints allow you to manage this data and sync it between HubSpot and other systems.

Example use case: when creating a set of quotes for sales reps to send to potential buyers, you can use this API to create standalone line items per quote, as well as line items that are attached to existing products.

To create a line item, make a POST request to /crm/v3/objects/line_items. In the post body, include the line item's details, such as name, quantity, and price. You may also want to include additional data in the request body:

  • To create a line item based on an existing product (created through the products API or in HubSpot), include hs_product_id in the post body.
  • To include the tax rate for your line item, include its ID as the hs_tax_rate_group_id within the properties field of the request body.
  • You can also associate the line item with deals, quotes, invoices, payment links or subscriptions, by including an associations array in the post body. For example, the post body below would create a line item named "New standalone line item" that's associated with a deal (ID: 12345).

You can retrieve line items individually or in bulk.

  • To retrieve a specific line item, make a GET request to /crm/v3/objects/line_items/{lineItemId} where lineItemId is the ID of the line item.
  • To retrieve all line items, make a GET request to /crm/v3/objects/line_items.

In the request URL, you can include the following parameters:

ParameterDescription
propertiesA comma separated list of the properties to be returned in the response. If any of the specified properties are not present on the requested object(s), they will be ignored.
propertiesWithHistoryA comma separated list of the properties to be returned along with their history of previous values. If any of the specified properties are not present on the requested object(s), they will be ignored.

To update a line item, make a PATCH request to /crm/v3/objects/line_items/{lineItemId}, where lineItemId is the ID of the line item.

In the post body, include the property values that you want to update. You cannot update associations through this method. Instead you'll need to use the associations API.

For example, your request body might look similar to the following:

To delete a line item, make a DELETE request to /crm/v3/objects/line_items/{lineItemId}, where lineItemId is the ID of the line item.

When managing your line item data, you may want to use some of the common properties in the table below. To get all line item properties, make a GET request to /crm/v3/properties/line_item. Learn more about using the properties API.

Property nameLabel in UIDescription
nameNameThe name of the line item.
descriptionDescriptionFull description of the product
hs_skuSKUUnique product identifier
hs_recurring_billing_start_dateBilling start dateRecurring billing start date for a line item
hs_recurring_billing_end_dateBilling end dateRecurring billing end date for a line item
recurringbillingfrequencyBilling frequencyHow often a line item with recurring billing is billed. It informs the pricing calculation for deals and quotes. Line items with one-time billing aren't included.
quantityQuantityHow many units of a product are included in this line item
priceUnit priceThe cost of the product
amountNet priceThe total cost of the line item (i.e., the quantity times the unit price).
currencyCurrencyCurrency code for the line item

You can apply a tax rate to individual line items (e.g., a MA Sales tax of 6.26%). Once you configure your tax rate library in your HubSpot account, you can then make a GET request to /tax-rates/v1/tax-rates to fetch all tax rates, or /tax-rates/v1/tax-rates/{taxRateId} to fetch a tax rate by its ID. Your app will need to authorize the tax_rates.read to make this request.

The resulting response will resemble the following:

Each tax rate object will include the following properties:

Property nameDescription
nameThe internal descriptor for the tax rate.
percentageRateThe value of the tax rate, expressed as a percentage.
labelThe buyer-facing descriptor of the tax rate, shown on the quote, invoice, or other parent objects.
activeA boolean that denotes whether the tax rate can be applied to a new quote or invoice. You might set this to false for a previous year's tax rate that's no longer applicable.
idThe ID of the tax rate.
createdAtAn ISO 8601 timestamp denoting when the tax rate was created.
updatedAtAn ISO 8601 timestamp denoting when the tax rate was last updated.

Once you have the ID of the tax rate you want to apply, provide that id for the hs_tax_rate_group_id within the properties field when creating a line item. Learn more about creating line items in the section above.