> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

---
id: 6e4de761-98cd-4525-adbd-ba4d029a7c28
---

# Invoices

> Use the invoices API to create, manage, retrieve, and delete the invoices used for billing your customers.

export const PostmanCard = ({title, collectionId}) => {
  return <div className="card-condensed-cta">
      <Card title={title ? title : "Postman collection"} href={`https://app.getpostman.com/run-collection/${collectionId}`} horizontal={true} cta="Run in Postman" icon={<svg xmlns="http://www.w3.org/2000/svg" width={25} height={25} preserveAspectRatio="xMidYMid" viewBox="0 0 256 256">
              <path fill="#FF6C37" d="M254.953 144.253c8.959-70.131-40.569-134.248-110.572-143.206C74.378-7.912 10.005 41.616 1.047 111.619c-8.959 70.003 40.569 134.248 110.572 143.334 70.131 8.959 134.248-40.569 143.334-110.7Z" />
              <path fill="#FFF" d="m174.2 82.184-54.007 54.007-15.229-15.23c53.11-53.11 58.358-48.503 69.236-38.777Z" />
              <path fill="#FF6C37" d="M120.193 137.47c-.384 0-.64-.128-.895-.384l-15.358-15.229a1.237 1.237 0 0 1 0-1.792c54.007-54.006 59.638-48.887 71.028-38.649.255.256.383.512.383.896s-.128.64-.383.896l-54.007 53.878c-.128.256-.512.384-.768.384Zm-13.437-16.509 13.437 13.438 52.087-52.087c-9.47-8.446-15.87-11.006-65.524 38.65Z" />
              <path fill="#FFF" d="m135.679 151.676-14.718-14.718 54.007-54.006c14.46 14.59-7.167 38.265-39.29 68.724Z" />
              <path fill="#FF6C37" d="M135.679 152.956c-.384 0-.64-.128-.896-.384l-14.718-14.718c-.256-.256-.256-.512-.256-.896s.128-.64.384-.895L174.2 82.056a1.237 1.237 0 0 1 1.791 0 15.58 15.58 0 0 1 4.991 11.902c-.256 14.206-16.38 32.25-44.28 58.614-.383.256-.767.384-1.023.384Zm-12.926-15.998c8.19 8.319 11.646 11.646 12.926 12.926 21.5-20.476 42.36-41.464 42.488-55.926.128-3.327-1.152-6.655-3.327-9.214l-52.087 52.214Z" />
              <path fill="#FFF" d="m105.22 121.345 10.878 10.878c.256.256.256.512 0 .768-.128.128-.128.128-.256.128l-22.524 4.863c-1.152.128-2.175-.64-2.431-1.791-.128-.64.128-1.28.512-1.664l13.053-13.054c.256-.256.64-.384.768-.128Z" />
              <path fill="#FF6C37" d="M92.934 139.262c-1.92 0-3.327-1.536-3.327-3.455 0-.896.384-1.792 1.024-2.432l13.053-13.054c.768-.64 1.792-.64 2.56 0l10.878 10.878c.768.64.768 1.792 0 2.56-.256.256-.512.384-.896.512l-22.524 4.863c-.256 0-.512.128-.768.128Zm11.902-16.51-12.542 12.543c-.256.256-.383.64-.128 1.024.128.383.512.511.896.383l21.116-4.607-9.342-9.342Z" />
              <path fill="#FFF" d="M202.739 52.238c-8.191-7.935-21.373-7.679-29.307.64-7.935 8.318-7.679 21.372.64 29.306A20.678 20.678 0 0 0 199.155 85l-14.59-14.59 18.174-18.172Z" />
              <path fill="#FF6C37" d="M188.405 89.223c-12.158 0-22.012-9.854-22.012-22.012 0-12.158 9.854-22.012 22.012-22.012 5.631 0 11.134 2.176 15.23 6.143.255.256.383.512.383.896s-.128.64-.384.895L186.357 70.41l13.566 13.566c.512.512.512 1.28 0 1.792l-.256.256c-3.327 2.047-7.295 3.199-11.262 3.199Zm0-41.337c-10.75 0-19.452 8.703-19.324 19.453 0 10.75 8.702 19.452 19.452 19.324 2.944 0 5.887-.64 8.575-2.047l-13.438-13.31c-.256-.256-.384-.512-.384-.896s.128-.64.384-.895l17.149-17.15c-3.456-2.943-7.807-4.479-12.414-4.479Z" />
              <path fill="#FFF" d="m203.122 52.622-.255-.256-18.301 18.044 14.461 14.462c1.408-.896 2.816-1.92 3.967-3.072a20.51 20.51 0 0 0 .128-29.178Z" />
              <path fill="#FF6C37" d="M199.155 86.28c-.384 0-.64-.128-.896-.384l-14.589-14.59c-.256-.256-.384-.512-.384-.896s.128-.64.384-.895l18.173-18.173a1.237 1.237 0 0 1 1.791 0l.384.256c8.575 8.574 8.575 22.396.128 31.098-1.28 1.28-2.687 2.432-4.223 3.328-.384.128-.64.256-.768.256Zm-12.798-15.87 12.926 12.926c1.024-.64 2.048-1.536 2.816-2.304 7.294-7.294 7.678-19.196.64-26.875L186.357 70.41Z" />
              <path fill="#FFF" d="M176.375 84.488a7.879 7.879 0 0 0-11.134 0l-48.247 48.247 8.063 8.063 51.062-44.792c3.328-2.816 3.584-7.807.768-11.134-.256-.128-.384-.256-.512-.384Z" />
              <path fill="#FF6C37" d="M124.929 142.077c-.384 0-.64-.128-.896-.383l-8.063-8.063a1.237 1.237 0 0 1 0-1.792l48.247-48.247a9.115 9.115 0 0 1 12.926 0 9.115 9.115 0 0 1 0 12.926l-.384.384-51.063 44.792c-.128.255-.384.383-.767.383Zm-6.143-9.342 6.27 6.271 50.167-44.024c2.816-2.304 3.072-6.527.768-9.342-2.303-2.816-6.526-3.072-9.342-.768-.128.128-.256.256-.512.384l-47.351 47.48Z" />
              <path fill="#FFF" d="M80.009 187.637c-.512.256-.768.768-.64 1.28l2.175 9.214c.512 1.28-.256 2.816-1.663 3.2-1.024.384-2.176 0-2.816-.768l-14.077-13.95 45.943-45.943 15.87.256 10.75 10.75c-2.56 2.175-18.045 17.149-55.542 35.961Z" />
              <path fill="#FF6C37" d="M78.985 202.61c-1.024 0-2.048-.383-2.688-1.151l-13.95-13.95c-.255-.256-.383-.512-.383-.896 0-.383.128-.64.384-.895l45.944-45.944c.256-.256.64-.384.895-.384l15.87.256c.383 0 .64.128.895.384l10.75 10.75c.256.256.384.64.384 1.024s-.128.64-.512.896l-.895.767c-13.566 11.902-31.995 23.804-54.902 35.194l2.175 9.086c.384 1.664-.384 3.456-1.92 4.352-.767.384-1.407.512-2.047.512Zm-14.078-15.997 13.182 13.054c.384.64 1.152.896 1.792.512.64-.384.896-1.152.512-1.792l-2.176-9.214c-.256-1.152.256-2.176 1.28-2.688 22.652-11.39 40.952-23.163 54.39-34.81l-9.47-9.47-14.718-.256-44.792 44.664Z" />
              <path fill="#FFF" d="m52.11 197.62 11.006-11.007 16.38 16.381-26.107-1.791c-1.151-.128-1.92-1.152-1.791-2.304 0-.512.128-1.024.512-1.28Z" />
              <path fill="#FF6C37" d="m79.497 204.146-26.236-1.791c-1.92-.128-3.199-1.792-3.071-3.712.128-.768.384-1.535 1.024-2.047L62.22 185.59a1.237 1.237 0 0 1 1.792 0l16.38 16.38c.385.385.512.897.257 1.408-.256.512-.64.768-1.152.768Zm-16.381-15.74-10.11 10.11c-.384.255-.384.895 0 1.151.127.128.255.256.511.256l22.652 1.536-13.053-13.054ZM104.452 146.557c-.768 0-1.28-.64-1.28-1.28 0-.384.128-.64.384-.896l12.414-12.414a1.237 1.237 0 0 1 1.792 0l8.062 8.063c.384.384.512.768.384 1.28-.128.384-.512.767-1.023.895l-20.477 4.352h-.256Zm12.414-11.902-8.446 8.446 13.821-2.943-5.375-5.503Z" />
              <path fill="#FFF" d="m124.8 140.926-14.077 3.071c-1.024.256-2.048-.384-2.303-1.408-.128-.64 0-1.28.511-1.791l7.807-7.807 8.063 7.935Z" />
              <path fill="#FF6C37" d="M110.467 145.277a3.168 3.168 0 0 1-3.2-3.2c0-.895.385-1.663.897-2.303l7.806-7.807a1.237 1.237 0 0 1 1.792 0l8.062 8.063c.384.384.512.768.384 1.28-.128.384-.512.767-1.023.895l-14.078 3.072h-.64Zm6.399-10.622-6.91 6.91c-.257.257-.257.512-.129.768s.384.384.768.384l11.774-2.56-5.503-5.502ZM203.25 64.907c-.256-.767-1.151-1.151-1.92-.895-.767.255-1.151 1.151-.895 1.92 0 .127.128.255.128.383.768 1.536.512 3.455-.512 4.863-.512.64-.384 1.536.128 2.048.64.512 1.536.384 2.048-.256 1.92-2.432 2.303-5.503 1.023-8.063Z" />
            </svg>} />
    </div>;
};

export const ScopesList = ({scopes = [], description = "This API requires one of the following scopes:"}) => {
  if (!scopes || scopes.length === 0) {
    return null;
  }
  const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
  return <div>
      <div className="text-sm mb-2">{description}</div>
      <div>
        {sortedScopes.map((scope, index) => <div key={index}>
            <code>
              <span className="text-xs">{scope}</span>
            </code>
          </div>)}
      </div>
    </div>;
};

<PostmanCard collectionId="26126890-8847b317-8dad-44b6-8cc5-d879f653f1d5" />

<Accordion title="Scope requirements">
  <ScopesList
    scopes={[
  'crm.objects.invoices.read',
  'crm.objects.invoices.write'
]}
  />
</Accordion>

Use the invoices API to create, update, fetch, and delete [invoices](https://knowledge.hubspot.com/invoices/create-invoices). Once configured, an invoice can be shared with a buyer at a specified URL. Users can also [create and manage invoices in HubSpot](https://knowledge.hubspot.com/invoices/create-invoices#manage-invoices) to add details, update associations, and more. If you’ve set up either [HubSpot payments](https://knowledge.hubspot.com/payment-processing/set-up-payments) or [Stripe payment processing](https://knowledge.hubspot.com/payment-processing/connect-your-stripe-account-as-a-payment-processor-in-hubspot), you can configure an invoice to be payable through this API.

For example, use this API to [create a new invoice](#create-invoices) or [fetch all currently open invoices](#search-for-invoices-by-properties).

## Create invoices

The invoice creation process can be broken up into the following steps:

1. **Create an invoice:** create a draft invoice and set the currency.
2. **Configure the invoice:** add associations to CRM records, such as a contact and line items to the invoice, properties, and configure payment settings.
3. **Move the invoice status to open:** move the invoice status from `draft` to `open`.
4. **Share the invoice:** share the invoice with the buyer.

To create an invoice, you'll first configure its basic details by making a `POST` request to `/crm/v3/objects/invoices`.

In the post body, include a `properties` object to store basic invoice information.

* The only property required for creating a draft invoice is `hs_currency`, which accepts a string value of a currency code (e.g., `USD`).
* You can modify a drafted invoice’s properties any time by [updating the invoice](#update-invoice-properties).
* The invoice will inherit other property values when you later associate a contact with it, such as contact and company details, which will be required before you can set the invoice to the *Open* state. [Learn more about updating properties and adding associations](#invoice-configuration).

<Info>
  Depending on your preferred workflow, you can instead [create a draft invoice with associations through one POST request](#create-a-draft-with-associations-single-request), rather than making two separate requests.
</Info>

```json theme={null}
{
  "properties": {
    "hs_currency": "USD"
  }
}
```

The response will include an `id`, which you'll use to continue configuring the invoice. You can update invoice properties at any time by making a `PATCH` request to `/crm/v3/objects/invoices/{invoiceId}`.

### Invoice configuration

To move the invoice to the `open` status so that it can be shared and paid, you’ll need to set a few required properties and associate it with other CRM records, such as line items and a contact. If you’ve set up [HubSpot payments](https://knowledge.hubspot.com/payment-processing/set-up-payments) or [Stripe payment processing](https://knowledge.hubspot.com/payment-processing/connect-your-stripe-account-as-a-payment-processor-in-hubspot), you can also configure the invoice’s payment settings.

#### Update invoice properties

To update an invoice’s properties, make a `PATCH` request to `/crm/v3/objects/invoices/{invoiceId}`. In the request body, include a properties object with fields for the [properties](#common-properties) you want to update.

```json theme={null}
{
  "properties": {
    "hs_currency": "USD",
    "hs_invoice_date": "2025-12-05T17:29:08.788Z",
    "hs_due_date": "2026-01-05T17:29:08.000Z",
    "hs_tax_id": "US EIN 12-3456789"
  }
}
```

| Property          | Description |                                                                                                                                                                                                                                                                                                            |
| ----------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hs_currency`     | String      | Currency of the invoice (e.g., `USD`).                                                                                                                                                                                                                                                                     |
| `hs_invoice_date` | Datetime    | Date of the invoice. Can be formatted as ISO 8601 or UNIX timestamp in milliseconds. If no value is provided, this property will be set automatically to the current datetime.                                                                                                                             |
| `hs_due_date`     | Datetime    | Due date of the invoice. Can be formatted as ISO 8601 or UNIX timestamp in milliseconds. If no value is provided, this property will be set automatically to the current datetime.                                                                                                                         |
| `hs_tax_id`       | String      | The account tax ID listed on the invoice, which includes a tax ID type and a tax ID number. If the account has a configured [default tax ID for invoices](https://knowledge.hubspot.com/invoices/set-up-the-hubspot-invoices-tool#customization), this property will be set automatically if not provided. |

#### Add associations

To associate other CRM records with the invoice, make a `PUT` request to `/crm/v4/objects/invoices/{fromObjectId}/associations/default/{toObjectType}/{toObjectId}`.

The table below show which CRM record associations are required to move the invoice to the Open state, and which are optional. [View a full list of the objects can be associated with invoices](/api-reference/legacy/crm/associations/v3/associate-records#invoice-to-object).

<Warning>
  **Please note:**

  A *Draft* invoice can be created without any associations.
</Warning>

| Object type                                                                                                                                                                      | Required | Description                                                                                                                                                                                                                                                                                                                                   |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Line items](/api-reference/legacy/crm/objects/line-items/guide)                                                                                                                 | Yes      | The goods and/or services being sold through the invoice. You can create line items from [products in your product library](/api-reference/legacy/crm/objects/products/guide) or create custom standalone line items.                                                                                                                         |
| [Contact](/api-reference/legacy/crm/objects/contacts/guide)                                                                                                                      | Yes      | Specific buyers that you're addressing in the invoice.                                                                                                                                                                                                                                                                                        |
| [Company](/api-reference/legacy/crm/objects/companies/guide)                                                                                                                     | No       | A specific company that you're addressing in the invoice.                                                                                                                                                                                                                                                                                     |
| [Discounts](/api-reference/legacy/crm/objects/discounts/guide), [fees](/api-reference/legacy/crm/objects/fees/guide), and [taxes](/api-reference/legacy/crm/objects/taxes/guide) | No       | Any discounts, fees, and taxes to be applied at checkout. When determining the total invoice amount, HubSpot first applies discounts, followed by fees, then taxes. You can use the `hs_sort_order` field to reorder objects of the same type. Can be set to fixed values or percentages by setting `hs_type` to either `FIXED` or `PERCENT`. |

To make each association, you'll first need to retrieve the ID of each object you want to associate. To retrieve each ID, you'll make a `GET` request to the relevant object endpoint, which follows the same pattern across each CRM object.

```shell theme={null}
#GET request for line items
curl --request GET \
  --url 'https://api.hubapi.com/crm/v3/objects/line_items?archived=false' \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN'

#GET request for contacts
curl --request GET \
  --url 'https://api.hubapi.com/crm/v3/objects/contacts?archived=false' \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN'

#GET request for companies
curl --request GET \
  --url 'https://api.hubapi.com/crm/v3/objects/companies?archived=false' \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN'

#GET request for discounts
curl --request GET \
  --url 'https://api.hubapi.com/crm/v3/objects/discounts?archived=false' \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN'

#GET request for fees
curl --request GET \
  --url 'https://api.hubapi.com/crm/v3/objects/fees?archived=false' \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN'

#GET request for taxes
curl --request GET \
  --url 'https://api.hubapi.com/crm/v3/objects/taxes?archived=false' \
  --header 'authorization: Bearer YOUR_ACCESS_TOKEN'
```

Each successful call will return a `200` response with details for each fetched object type. You'll use the value in the `id` field to set associations in the next step.

```json theme={null}
{
  "results": [
    {
      "id": "54486102441",
      "properties": {
        "hs_createdate": "2024-03-18T07:34:29.586Z",
        "hs_lastmodifieddate": "2024-03-18T07:34:29.586Z",
        "hs_object_id": "54486102441",
        "hs_type": "PERCENT",
        "hs_value": "20.0000"
      },
      "createdAt": "2024-03-18T07:34:29.586Z",
      "updatedAt": "2024-03-18T07:34:29.586Z",
      "archived": false
    }
  ]
}
```

#### Make an invoice non-billable

A non-billable invoice won't render, meaning an invoice document won't be created, and other invoice functionalities, such as validation, email, and notifications, will not be included. This could be useful if you want to track invoice data in HubSpot, but manage or bill the invoices outside of HubSpot.

To make an invoice non-billable, create an invoice, making a `POST` request to `/crm/v3/objects/invoices` and include the `hs_invoice_billable` property.

```json theme={null}
{
  "properties": {
    "hs_currency": "USD",
    "hs_invoice_billable": "false"
  }
}
```

#### Configure payment settings

<Warning>
  **Please note:**

  * Recording payments manually is not possible via the API but is [possible in the platform](https://knowledge.hubspot.com/invoices/create-invoices#manage-finalized-invoices).
  * The HubSpot account must have either [HubSpot payments](https://knowledge.hubspot.com/payment-processing/set-up-payments) or [Stripe payment processing](https://knowledge.hubspot.com/payment-processing/connect-your-stripe-account-as-a-payment-processor-in-hubspot) set up before using this capability.
</Warning>

If your account is set up to collect digital payments using HubSpot payments or Stripe payment processing, and the currency of the invoice is set to a [currency that is valid for transacting](https://knowledge.hubspot.com/payment-processing/configure-currencies-for-commerce-hub#available-currencies), the invoice will automatically be configured to collect payments. In addition, other properties will automatically be set based on the account [payment settings](https://knowledge.hubspot.com/payment-processing/configure-your-buyer-checkout-experience#set-the-default-payment-method-and-shipping-information).

The properties below can be amended if required. This is not an exhaustive list. To get a list of all available properties, make a `GET` request to `/crm/v3/objects/invoices`.

| Parameter                              | Type        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `hs_allowed_payment_methods`           | Enumeration | The payment methods to be used. For example, `credit_or_debit_card`, `ach`. <ul><li>[Accepted payment methods when using HubSpot payments](https://knowledge.hubspot.com/payment-processing/set-up-payments).</li><li>[Accepted payment methods when using Stripe as a payment processor](https://knowledge.hubspot.com/payment-processing/connect-your-stripe-account-as-a-payment-processor-in-hubspot#configure-currencies-and-payment-methods).</li></ul>If no value is provided, this property will be set automatically based on the account [payment settings](https://knowledge.hubspot.com/payment-processing/configure-your-buyer-checkout-experience#set-the-default-payment-method-and-shipping-information).[](https://knowledge.hubspot.com/payment-processing/configure-your-buyer-checkout-experience#set-the-default-payment-method-and-shipping-information) |
| `hs_invoice_payment_collection_method` | Enumeration | Set to `manual` if you want the invoice to have digital payment capability. Set to `none` if you don't want digital payment capability. If no value is provided, this property will be set automatically based on the account [payment settings](https://knowledge.hubspot.com/payment-processing/configure-your-buyer-checkout-experience#set-the-default-payment-method-and-shipping-information).[](https://knowledge.hubspot.com/payment-processing/configure-your-buyer-checkout-experience#set-the-default-payment-method-and-shipping-information)                                                                                                                                                                                                                                                                                                                      |
| `hs_collect_address_types`             | Boolean     | The types of addresses that are collected while paying the invoice. Value can be `billing_address` and/or `shipping_address`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `hs_recipient_shipping_address`        | String      | The shipping address of the recipient.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `hs_recipient_shipping_city`           | String      | The shipping city of the recipient.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `hs_recipient_shipping_state`          | String      | The shipping state or region of the recipient.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `hs_recipient_shipping_zip`            | String      | The shipping postal or zip code of the recipient.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

### Add taxes to an invoice

You can add taxes to an invoice in two different ways depending on your use case:

* Add taxes to individual line items by setting the `hs_tax_rate_group_id` property when you create an invoice. You'll first need to [set up tax rates](https://knowledge.hubspot.com/payments/create-and-use-discount-codes#add-a-tax-rate-to-the-tax-library) in your account before associating them with line items. You'll need to authorize the `tax_rates.read` scope for your app to fetch tax rates and the `crm.objects.line_items.write` scope to update or create a line item.
* Use the [tax object](/api-reference/legacy/crm/objects/taxes/guide) to add taxes to the entire invoice, applying taxes to the total amount of the invoice.

#### Add taxes to line items

To associate a tax rate with a line item of an invoice, first make a `GET` request to `/tax-rates/v1/tax-rates` to fetch all tax rates. The resulting response will resemble the following:

```json theme={null}
{
  "results": [
    {
      "name": "state-sales-tax",
      "percentageRate": 1,
      "label": "State sales tax 2025",
      "active": true,
      "id": "15970230",
      "createdAt": "2025-02-25T21:57:20.703Z",
      "updatedAt": "2025-02-25T21:57:20.703Z"
    }
  ],
  "paging": {
    "next": {
      "after": "MTU5NzAyMzA%3D",
      "link": "https://api.hubspot.com/tax-rates/v1/tax-rates?after=MTU5NzAyMzA%3D"
    }
  }
}
```

You can then use the `id` of one of your tax rates as the `hs_tax_rate_group_id` when creating or updating a line item. Learn more about setting up tax rates in the [line items API guide](/api-reference/legacy/crm/objects/line-items/guide#create-a-line-item).

#### Add taxes to the entire invoice order

Rather than apply an existing tax rate to individual line items, you can instead apply a tax to the [entire invoice order](https://knowledge.hubspot.com/products/edit-products-and-terms-in-the-line-items-editor#add-discounts-fees-and-taxes-to-an-invoice). An invoice-level tax has a 1:1 relationship with the invoice, meaning the tax must be unique to the invoice. However, an invoice can include multiple taxes.

To add taxes to an entire invoice order:

* [Create a tax](https://developers.hubspot.com/docs/reference/api/crm/objects/taxes#post-%2Fcrm%2Fv3%2Fobjects%2Ftaxes).
* [Create an invoice](#create-an-invoice).
* Use the [associations API to associate the invoice to the tax](/api-reference/legacy/crm/associations/v3/associate-records).

### Move the invoice to the Open status

An invoice can be set to one of four statuses, as set by the `hs_invoice_status` property:

| Status   | Description                                                                        |
| -------- | ---------------------------------------------------------------------------------- |
| `draft`  | The invoice is being edited and is not yet ready to be sent.                       |
| `open`   | The invoice has all of the details needed to be sent to the buyer, and is payable. |
| `paid`   | The buyer has paid the invoice.                                                    |
| `voided` | The invoice has been voided.                                                       |

When creating an invoice, you may want to set its status to `draft` until it's ready to be sent to the buyer. Once all of the [required properties and associations](#invoice-configuration) are added to the invoice, you can update its status to `open`, meaning the invoice can be shared and is payable.

To move the invoice to the `open` status, make a `PATCH` request to `/crm/v3/objects/invoices` and set the `hs_invoice_status` property to `open`.

<Warning>
  **Please note:**

  To move an invoice to the *Open* status (open invoice that is payable), one contact and at least one line item must be associated.
</Warning>

```json theme={null}
{
  "properties": {
    "hs_invoice_status": "open"
  }
}
```

## 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](#search-for-invoices-by-properties).

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

```json theme={null}
{
  "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
}
```

For reference, review the [list of common properties](#common-properties) below. To view all available invoice properties, make a `GET` request to `crm/v3/properties/invoices`. Learn more about using the [properties API](/api-reference/legacy/crm/properties/guide).

### Search for invoices by properties

You can use the search [endpoint](/api-reference/legacy/crm/search-the-crm) to retrieve invoices that meet a specific set of [filter criteria](/api-reference/legacy/crm/search-the-crm#filter-search-results). 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:

```json theme={null}
{
  "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.

#### Retrieve associations

To retrieve association information for an invoice,make a `GET` request to the following URL:

``crm/v3/objects/invoice/{`hs_object_id}`/associations/{associatedObjectName}``

Associated objects can include [contacts](/api-reference/legacy/crm/objects/contacts/guide), [companies](/api-reference/legacy/crm/objects/companies/guide), [deals](/api-reference/legacy/crm/objects/deals/guide), [line items](/api-reference/legacy/crm/objects/line-items/guide), [discounts](/api-reference/legacy/crm/objects/discounts/guide), **[fees](/api-reference/legacy/crm/objects/fees/guide)**, and **[taxes](/api-reference/legacy/crm/objects/taxes/guide)**.

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

`crm/v3/objects/invoice/{invoiceId}/associations/line_items`

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

```json theme={null}
{
  "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](/api-reference/legacy/crm/objects/line-items/guide). For example, you could batch retrieve line items by ID by making a `POST` request to the following URL with the request body below:

`crm/v3/objects/line_items/batch/read`

```json theme={null}
{
  "inputs": [
    {
      "id": "1526712436"
    },
    {
      "id": "1526712437"
    }
  ],
  "properties": ["name", "amount"]
}
```

The response would be formatted as follows:

```json theme={null}
{
  "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"
}
```

<Warning>
  **Please note:**

  Line items belong to one single parent object. For example, if retrieving line items from an invoice, the line item IDs will be different to those on a deal, or a quote.
</Warning>

## Delete invoices

You can delete invoices with a `hs_invoice_status` of `draft` and `open` (if [enabled in your account settings](https://knowledge.hubspot.com/invoices/set-up-the-hubspot-invoices-tool#turn-on-the-ability-to-delete-unpaid-invoices)).

* To [delete one invoice](/api-reference/legacy/crm/objects/invoices/guide#delete-%2Fcrm%2Fv3%2Fobjects%2Finvoices%2F%7Binvoiceid%7D) by ID, make a `DELETE` request to `/crm/v3/objects/invoices/{invoiceId}`.
* To [delete a batch](/api-reference/legacy/crm/objects/invoices/guide#post-%2Fcrm%2Fv3%2Fobjects%2Finvoices%2Fbatch%2Farchive) of invoices by ID, make a `POST` request to `/crm/v3/objects/invoices/batch/archive` with the invoice IDs specified in the request body:

```json theme={null}
{
  "inputs": [
    {
      "id": "1234567"
    },
    {
      "id": "8675309"
    }
  ]
}
```

## Reference

### Common properties

Below is a list of properties commonly used. This is not an exhaustive list. To get a list of all available properties, make a `GET` request to `/crm/v3/objects/invoices`.

| Parameter                              | Type        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| -------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hs_currency`                          | String      | Currency of the invoice.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `hs_invoice_date`                      | Datetime    | Date of the invoice. Can be formatted as ISO 8601 or UNIX timestamp in milliseconds. If no value is provided, this property will be set automatically to the current datetime.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `hs_due_date`                          | Datetime    | Due date of the invoice. Can be formatted as ISO 8601 or UNIX timestamp in milliseconds. If no value is provided, this property will be set automatically to the current datetime.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `hs_purchase_order_number`             | String      | Add an associated PO number.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `hs_comments`                          | String      | Add comments to the invoice for the buyer to see.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `hs_tax_id`                            | String      | The account tax ID listed on the invoice, which includes a tax ID type and a tax ID number (e.g., `US EIN 12-3456789`). If the account has a configured [default tax ID for invoices](https://knowledge.hubspot.com/invoices/set-up-the-hubspot-invoices-tool#customization), this property will be set automatically if not provided.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `hs_allowed_payment_methods`           | Enumeration | The payment methods to be used. For example, `credit_or_debit_card`, `ach`. <ul><li>[Accepted payment methods when using HubSpot payments](https://knowledge.hubspot.com/payment-processing/set-up-payments).</li><li>[Accepted payment methods when using Stripe as a payment processor](https://knowledge.hubspot.com/payment-processing/connect-your-stripe-account-as-a-payment-processor-in-hubspot#configure-currencies-and-payment-methods).</li></ul>If no value is provided, this property will set automatically based on the account [payment settings](https://knowledge.hubspot.com/payment-processing/configure-your-buyer-checkout-experience#set-the-default-payment-method-and-shipping-information).[](https://knowledge.hubspot.com/payment-processing/configure-your-buyer-checkout-experience#set-the-default-payment-method-and-shipping-information) |
| `hs_invoice_payment_collection_method` | Enumeration | Set to `manual` if you want the invoice to have digital payment capability. Set to `none` if you don't want digital payment capability. If no value is provided, this property will be set automatically based on the account [payment settings](https://knowledge.hubspot.com/payment-processing/configure-your-buyer-checkout-experience#set-the-default-payment-method-and-shipping-information).[](https://knowledge.hubspot.com/payment-processing/configure-your-buyer-checkout-experience#set-the-default-payment-method-and-shipping-information)                                                                                                                                                                                                                                                                                                                   |
| `hs_allow_partial_payments`            | Boolean     | Allow your customer to pay less than the balance due.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `hs_collect_address_types`             | Boolean     | The types of addresses that are collected while paying the invoice. Value can be `billing_address` and/or `shipping_address`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `hs_recipient_shipping_address`        | String      | The shipping address of the recipient. This address is used as the billing address.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `hs_recipient_shipping_address2`       | String      | The second line of the shipping address of the recipient. This address is used as the billing address.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `hs_recipient_shipping_city`           | String      | The shipping city of the recipient.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `hs_recipient_shipping_state`          | String      | The shipping state or region of the recipient.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `hs_recipient_shipping_zip`            | String      | The shipping postal or zip code of the recipient. This postal or zip code is used as the billing postal or zip code.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `hs_recipient_shipping_country`        | String      | The shipping country of the recipient.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `hs_recipient_company_address`         | String      | The address of the recipient's company.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `hs_recipient_company_address2`        | String      | The second line of the address of the recipient's company.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `hs_recipient_company_city`            | String      | The city of the recipient's company.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `hs_recipient_company_state`           | String      | The state or region of the recipient's company.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `hs_recipient_company_zip`             | String      | The postal or zip code of the recipient's company.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `hs_custom_fields`                     | Enumeration | The custom fields that have been added to the invoice. [Learn more about the configuration of this setting](https://knowledge.hubspot.com/invoices/set-up-the-hubspot-invoices-tool#add-or-remove-custom-fields).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `hs_invoice_link`                      | String      | The URL of the invoice.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `hs_language`                          | String      | Language of the invoice.<br /><br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `hs_locale`                            | String      | Locale of the invoice.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `hs_pdf_download_link`                 | String      | PDF download link.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `hs_invoice_billable`                  | Boolean     | Whether the invoice is billable or not.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

### Create a draft with associations (single request)

The following request body will create a new draft invoice with an association to a contact.

`POST` `/crm/v3/objects/invoices/batch/create`

```json theme={null}
{
  "inputs": [
    {
      "properties": {
        "hs_currency": "USD",
        "hs_invoice_date": "1729859279",
        "hs_due_date": "1732537679"
      },
      "associations": [
        {
          "to": {
            "id": "2171512734"
          },
          "types": [
            {
              "associationCategory": "HUBSPOT_DEFINED",
              "associationTypeId": 177
            }
          ]
        }
      ]
    }
  ]
}
```

| Parameter         | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `hs_currency`     | String   | Currency of the invoice.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `hs_invoice_date` | Datetime | Date of the invoice. Can be formatted as ISO 8601 or UNIX timestamp in milliseconds. If no value is provided, this property will be set automatically to the current datetime.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `hs_due_date`     | Datetime | Due date of the invoice. Can be formatted as ISO 8601 or UNIX timestamp in milliseconds. If no value is provided, this property will be set automatically to the current datetime.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `associations`    | Array    | The invoice’s associated records. To set each association, include a separate object in the associations array with the following fields:<ul><li>to: the ID of the record to associate with the invoice.</li><li>associationCategory: the [<u>type of association</u>](/api-reference/legacy/crm/associations/v3/associate-records#retrieve-association-types). Can be HUBSPOT\_DEFINED or USER\_DEFINED.</li><li>associationTypeId: the ID of the type of association being made:<ul><li>177: invoice to contact</li></ul></li></ul>[Learn more about association type IDs](/api-reference/legacy/crm/associations/v3/associate-records#association-type-id-values). |
