Use the invoices API to fetch information about an account's invoices. This is a read-only API, so it cannot be used for creating new or managing existing invoices. 

For example, use this API to fetch all currently open invoices.

Retrieve invoices

Depending on the information you need, there are a few ways to retrieve invoices:

  • To retrieve all invoices, make a GET request to crm/v3/objects/invoices.
  • To retrieve a specific invoice, make a GET request to the above URL and specify an invoice ID. For example: crm/v3/objects/invoices/44446244097.
  • To retrieve invoices that meet a specific set of criteria, you can make a POST request to the search endpoint and include filters in the request body. See an example of using the search endpoint below.

The response will include a few default properties, including the create date, last modified date.

// Example response { "id":"44446244097", "properties":{ "hs_createdate":"2023-03-08T14:54:17.333Z", "hs_lastmodifieddate":"2024-03-01T22:33:09.011Z", "hs_object_id":"44446244097" }, "createdAt":"2023-03-08T14:54:17.333Z", "updatedAt":"2024-03-01T22:33:09.011Z", "archived":false }


To return specific properties, include a properties query parameter in the request URL along with comma-separated property names. For example, making a GET request to the following URL would result in the response below:


// Example response { "id":"44446244097", "properties":{ "hs_amount_billed":"20.00", "hs_createdate":"2023-03-08T14:54:17.333Z", "hs_invoice_status":"open", "hs_lastmodifieddate":"2024-03-01T22:33:09.011Z", "hs_object_id":"44446244097" }, "createdAt":"2023-03-08T14:54:17.333Z", "updatedAt":"2024-03-01T22:33:09.011Z", "archived":false }

To view all available invoice properties, make a GET request to crm/v3/properties/invoices. Learn more about using the properties API.

Below are some common invoice properties that you may want to query. 

Property name Label in UI Description

Invoice status

The current status of the invoice. Values include:

  • draft
  • open
  • paid
  • voided

Amount billed

The amount billed on the invoice.


Balance due

The balance due on the invoice.


Due date

The date the invoice is due.



The invoice number (e.g., INV_1003)

Search for invoices by properties

You can use the search endpoint to retrieve invoices that meet a specific set of filter criteria. This will be a POST request that includes your filter criteria in the request body.

For example, to search for all open invoices, you would make a POST request to crm/v3/objects/invoices/search with the following request body:

// Example search request body { "filterGroups": [ { "filters": [ { "propertyName": "hs_invoice_status", "value" : "open", "operator": "EQ" } ] } ], "properties": [ "hs_invoice_status", "hs_due_date"] }

Note that the filters array specifies the search criteria, while the properties array specifies which properties to return.


While you cannot set associations using this API, you can retrieve association information by making a GET request to the following URL:


Associated objects can include contacts, companies, dealsline items, discounts, fees, and taxes. To create associations between an invoice and these objects, you can update the invoice in HubSpot.

Below is an example of how you might use this API combined with another API to get a specific set of association information.

Please note: line items belong to one single parent object. For example, if retrieving line items from an invoice, the line item ID’s will be different to those on a deal, or a quote.

Retrieving an invoice with associated line items

To retrieve an invoice and the line items associated with it, make a GET request to:


This will return the IDs of the currently associated line items, along with meta information about the association type.

// Example response { "results":[ { "id":"1526712436", "type":"invoice_to_line_item" }, { "id":"1526712437", "type":"invoice_to_line_item" } ] }

You can then use the returned IDs to request more information about the line items through the line items API. For example, you could batch retrieve line items by ID by making a POST request to the following URL with the request body below:


// Example request body { "inputs": [ {"id": "1526712436"}, {"id": "1526712437"} ], "properties": ["name", "amount"] }

The response would be formatted as follows:

// Example response { "status":"COMPLETE", "results":[ { "id":"1359205183", "properties":{ "amount":"123.00", "createdate":"2023-04-26T14:52:35.885Z" "hs_lastmodifieddate":"2023-04-26T14:52:35.885Z", "hs_object_id":"1359205183", "name":"itemname" }, "createdAt":"2023-04-26T14:52:35.885Z", "updatedAt":"2023-04-26T14:52:35.885Z", "archived":false } ], "startedAt":"2024-03-11T20:09:44.151Z", "completedAt":"2024-03-11T20:09:44.195Z" }

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