QuickBooks Online Invoice Management

Overview

Invoices are the primary billing mechanism in QuickBooks Online. For MSPs, invoices typically represent monthly managed services fees, project work, hardware procurement, or ad-hoc support. QBO supports line items with service/product references, automatic tax calculation, email delivery, payment links, and integration with online payment processing. Invoices track due dates via payment terms and automatically contribute to the customer's outstanding balance.

Key Concepts

Invoice Lifecycle

Status	Description	Balance Impact
Draft	Not yet sent	Adds to balance
Sent	Emailed to customer	Adds to balance
Partially Paid	Some payment applied	Reduced balance
Paid	Fully paid	Zero balance
Voided	Cancelled	Removed from balance
Overdue	Past due date	Adds to balance (flagged)

Line Items

Each invoice contains one or more line items. Line items reference Items (products/services) from the QBO Items list:

Line Type	Description	MSP Example
`SalesItemLineDetail`	Standard product/service line	Monthly IT services
`GroupLineDetail`	Grouped bundle of items	Managed services bundle
`DescriptionOnlyLine`	Text-only description line	Section headers
`DiscountLineDetail`	Discount applied	Multi-year contract discount
`SubTotalLineDetail`	Running subtotal	Subtotal before tax

MSP Invoice Types

Type	Frequency	Description
Recurring Monthly	Monthly	Managed services, monitoring, backup
Project-Based	One-time	Network upgrade, migration, deployment
Time & Materials	As incurred	Break-fix support, consulting hours
Hardware	One-time	Equipment procurement and markup

Field Reference

Core Fields

Field	Type	Required	Description
`Id`	string	System	Auto-generated unique identifier
`DocNumber`	string	No	Invoice number (auto-generated if blank)
`TxnDate`	date	No	Invoice date (default: today)
`DueDate`	date	No	Payment due date (calculated from terms)
`CustomerRef.value`	string	Yes	Customer ID
`Line`	array	Yes	Array of line items
`TotalAmt`	decimal	Read-only	Total invoice amount
`Balance`	decimal	Read-only	Remaining unpaid balance
`SyncToken`	string	Required for updates	Optimistic locking token

Billing Fields

Field	Type	Description
`SalesTermRef.value`	string	Payment terms ID
`BillEmail.Address`	string	Email to send invoice to
`BillAddr`	object	Billing address
`ShipAddr`	object	Shipping address
`CustomerMemo.value`	string	Memo visible to customer
`PrivateNote`	string	Internal note (not visible to customer)
`EmailStatus`	string	"NotSet", "NeedToSend", "EmailSent"

Line Item Fields (SalesItemLineDetail)

Field	Type	Required	Description
`Line.Amount`	decimal	Yes	Line total (Qty x Rate)
`Line.Description`	string	No	Line item description
`Line.DetailType`	string	Yes	"SalesItemLineDetail"
`Line.SalesItemLineDetail.ItemRef.value`	string	Yes	Item ID
`Line.SalesItemLineDetail.Qty`	decimal	No	Quantity
`Line.SalesItemLineDetail.UnitPrice`	decimal	No	Unit price
`Line.SalesItemLineDetail.ServiceDate`	date	No	Service date

Tax Fields

Field	Type	Description
`TxnTaxDetail.TotalTax`	decimal	Total tax amount
`TxnTaxDetail.TxnTaxCodeRef.value`	string	Tax code ID
`GlobalTaxCalculation`	string	"TaxExcluded", "TaxInclusive", "NotApplicable"

Metadata Fields

Field	Type	Description
`MetaData.CreateTime`	datetime	Creation timestamp
`MetaData.LastUpdatedTime`	datetime	Last update timestamp

API Patterns

Query Invoices

GET /v3/company/{realmId}/query?query=SELECT * FROM Invoice WHERE CustomerRef = '123' AND Balance > '0'&minorversion=73
Authorization: Bearer {access_token}
Accept: application/json

Common Queries:

-- Unpaid invoices for a customer
SELECT * FROM Invoice WHERE CustomerRef = '123' AND Balance > '0'

-- All invoices in a date range
SELECT * FROM Invoice WHERE TxnDate >= '2026-01-01' AND TxnDate <= '2026-01-31' ORDERBY TxnDate DESC

-- Overdue invoices (past due date with balance)
SELECT * FROM Invoice WHERE DueDate < '2026-02-23' AND Balance > '0' ORDERBY DueDate ASC

-- Recent invoices
SELECT * FROM Invoice ORDERBY TxnDate DESC MAXRESULTS 25

-- Invoices by doc number
SELECT * FROM Invoice WHERE DocNumber = 'INV-1042'

Get Single Invoice

GET /v3/company/{realmId}/invoice/456?minorversion=73
Authorization: Bearer {access_token}

curl -s -H "Authorization: Bearer $QBO_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  "https://quickbooks.api.intuit.com/v3/company/$QBO_REALM_ID/invoice/456?minorversion=73"

Create Invoice

POST /v3/company/{realmId}/invoice?minorversion=73
Content-Type: application/json
Authorization: Bearer {access_token}

Monthly Managed Services Invoice:

{
  "CustomerRef": {
    "value": "123"
  },
  "TxnDate": "2026-02-01",
  "SalesTermRef": {
    "value": "3"
  },
  "BillEmail": {
    "Address": "billing@acmecorp.com"
  },
  "EmailStatus": "NeedToSend",
  "Line": [
    {
      "Amount": 2500.00,
      "Description": "Monthly Managed IT Services - February 2026\nIncludes: 24/7 monitoring, patch management, help desk support (unlimited)",
      "DetailType": "SalesItemLineDetail",
      "SalesItemLineDetail": {
        "ItemRef": { "value": "1" },
        "Qty": 1,
        "UnitPrice": 2500.00,
        "ServiceDate": "2026-02-01"
      }
    },
    {
      "Amount": 150.00,
      "Description": "Cloud Backup Service - 500GB - February 2026",
      "DetailType": "SalesItemLineDetail",
      "SalesItemLineDetail": {
        "ItemRef": { "value": "2" },
        "Qty": 1,
        "UnitPrice": 150.00,
        "ServiceDate": "2026-02-01"
      }
    },
    {
      "Amount": 200.00,
      "Description": "Email Security Filtering - 50 mailboxes - February 2026",
      "DetailType": "SalesItemLineDetail",
      "SalesItemLineDetail": {
        "ItemRef": { "value": "3" },
        "Qty": 50,
        "UnitPrice": 4.00,
        "ServiceDate": "2026-02-01"
      }
    }
  ],
  "CustomerMemo": {
    "value": "Thank you for choosing our managed IT services."
  },
  "PrivateNote": "Monthly recurring invoice - auto-generated"
}

curl -s -X POST \
  -H "Authorization: Bearer $QBO_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  "https://quickbooks.api.intuit.com/v3/company/$QBO_REALM_ID/invoice?minorversion=73" \
  -d '{
    "CustomerRef": { "value": "123" },
    "Line": [{
      "Amount": 2500.00,
      "Description": "Monthly Managed IT Services - February 2026",
      "DetailType": "SalesItemLineDetail",
      "SalesItemLineDetail": {
        "ItemRef": { "value": "1" },
        "Qty": 1,
        "UnitPrice": 2500.00
      }
    }]
  }'

Send Invoice via Email

POST /v3/company/{realmId}/invoice/456/send?minorversion=73
Authorization: Bearer {access_token}

curl -s -X POST \
  -H "Authorization: Bearer $QBO_ACCESS_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  "https://quickbooks.api.intuit.com/v3/company/$QBO_REALM_ID/invoice/456/send?sendTo=billing@acmecorp.com&minorversion=73"

Update Invoice (Sparse)

{
  "Id": "456",
  "SyncToken": "3",
  "sparse": true,
  "CustomerMemo": {
    "value": "Payment is now overdue. Please remit immediately."
  }
}

QuickBooks Online Invoices

How to add

Drop this on your repo README

Related skills

pdf

pptx

docx

canvas-design

Get new Documentos skills every Monday