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

Como adicionar

Cole no README do seu repo

Skills relacionadas

pdf

theme-factory

pptx

canvas-design

Receba novas skills de Documentos toda segunda