Building invoicing into your app sounds straightforward—until you open the QuickBooks API docs.
Nested objects three levels deep. Fields named SalesItemLineDetail inside DetailType inside Line. A SyncToken you need to track for every update. Error code 5010 when someone else touched the record 200ms before you did.
The QuickBooks Invoice API is powerful, but it wasn't designed for developers who just want to create an invoice and move on.
This guide covers both paths:
- The native approach — Full endpoint reference, working code examples, and the gotchas that'll save you hours of debugging
- The unified API approach — How to reduce 100+ lines of QuickBooks-specific code to 20 lines that work across QuickBooks, Xero, NetSuite, and 30+ other accounting platforms
Whether you're building a direct integration or evaluating unified APIs, you'll walk away knowing exactly what QuickBooks invoicing requires under the hood.
QuickBooks Invoice API Overview
Before diving in, make sure you have your QuickBooks API credentials set up. If you're evaluating whether to build this integration yourself or use a unified API, check out our QuickBooks API pricing breakdown to understand the costs involved.
The QuickBooks Invoice API lets you programmatically:
- Create and send invoices
- Add line items with products/services
- Apply discounts and taxes
- Track payment status
- Send payment reminders
- Void or delete invoices
- Query invoice history
API Endpoints
| Operation | Method | Endpoint |
|---|---|---|
| Create | POST | /v3/company/{realmId}/invoice |
| Read | GET | /v3/company/{realmId}/invoice/{invoiceId} |
| Update | POST | /v3/company/{realmId}/invoice |
| Delete | POST | /v3/company/{realmId}/invoice?operation=delete |
| Void | POST | /v3/company/{realmId}/invoice?operation=void |
| Send | POST | /v3/company/{realmId}/invoice/{invoiceId}/send |
| Query | GET | /v3/company/{realmId}/query?query=SELECT * FROM Invoice |
Base URLs:
- Production:
https://quickbooks.api.intuit.com - Sandbox:
https://sandbox-quickbooks.api.intuit.com
Note: Updates use the same endpoint as create. The distinction is in the request body—updates must include
IdandSyncTokenfields. Working with QuickBooks Desktop instead? See our QuickBooks Desktop integration guide.
Creating Invoices with the Native API
Basic Invoice
const createInvoice = async (realmId, accessToken) => {
const invoice = {
CustomerRef: {
value: "123" // Customer ID
},
Line: [
{
Amount: 150.00,
DetailType: "SalesItemLineDetail",
SalesItemLineDetail: {
ItemRef: {
value: "1",
name: "Consulting Services"
},
Qty: 3,
UnitPrice: 50.00
},
Description: "Strategy consulting - 3 hours"
}
],
DueDate: "2024-02-15"
};
const response = await fetch(
`https://quickbooks.api.intuit.com/v3/company/${realmId}/invoice?minorversion=75`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json',
'Accept': 'application/json'
},
body: JSON.stringify(invoice)
}
);
return response.json();
};
Invoice with Multiple Line Items
const invoice = {
CustomerRef: { value: "123" },
Line: [
{
Amount: 500.00,
DetailType: "SalesItemLineDetail",
SalesItemLineDetail: {
ItemRef: { value: "1" },
Qty: 10,
UnitPrice: 50.00
},
Description: "Development services"
},
{
Amount: 200.00,
DetailType: "SalesItemLineDetail",
SalesItemLineDetail: {
ItemRef: { value: "2" },
Qty: 4,
UnitPrice: 50.00
},
Description: "Design services"
}
],
DueDate: "2024-02-15",
PrivateNote: "Internal note: Rush project"
};
Invoice with Discount and Tax
const invoiceWithDiscountAndTax = {
CustomerRef: { value: "123" },
Line: [
{
Amount: 1000.00,
DetailType: "SalesItemLineDetail",
SalesItemLineDetail: {
ItemRef: { value: "1" },
Qty: 10,
UnitPrice: 100.00,
TaxCodeRef: { value: "TAX" }
}
},
{
Amount: 100.00,
DetailType: "DiscountLineDetail",
DiscountLineDetail: {
PercentBased: true,
DiscountPercent: 10,
DiscountAccountRef: { value: "86" }
}
}
],
TxnTaxDetail: {
TxnTaxCodeRef: { value: "2" },
TotalTax: 74.25 // (1000 - 100) * 8.25%
}
};
Reading and Querying Invoices
Get Single Invoice
const getInvoice = async (realmId, invoiceId, accessToken) => {
const response = await fetch(
`https://quickbooks.api.intuit.com/v3/company/${realmId}/invoice/${invoiceId}?minorversion=75`,
{
headers: {
'Authorization': `Bearer ${accessToken}`,
'Accept': 'application/json'
}
}
);
return response.json();
};
Query Examples
QuickBooks uses a SQL-like query syntax with some limitations:
Supported: WHERE, LIKE (% wildcard only), ORDER BY, IN, AND, comparison operators, STARTPOSITION, MAXRESULTS
Not supported: OR, NOT, JOIN, GROUP BY, projections (selecting specific fields)
// Unpaid invoices
const query = "SELECT * FROM Invoice WHERE Balance > '0' ORDER BY DueDate";
// Customer's invoices
const query = `SELECT * FROM Invoice WHERE CustomerRef = '${customerId}'`;
// Overdue invoices
const today = new Date().toISOString().split('T')[0];
const query = `SELECT * FROM Invoice WHERE DueDate < '${today}' AND Balance > '0'`;
// Date range (note: use single quotes for values)
const query = `SELECT * FROM Invoice WHERE TxnDate >= '2024-01-01' AND TxnDate <= '2024-01-31'`;
// With pagination (default: 100 results, max: 1000)
const query = `SELECT * FROM Invoice STARTPOSITION 1 MAXRESULTS 200`;
Updating Invoices
QuickBooks uses sparse updates—send only changed fields plus Id and SyncToken. Updates use the same endpoint as create; the presence of Id and SyncToken signals an update operation:
const updateInvoice = async (realmId, invoice, accessToken) => {
const updatePayload = {
Id: invoice.Id,
SyncToken: invoice.SyncToken, // Required for optimistic locking
sparse: true,
DueDate: "2024-03-01"
};
const response = await fetch(
`https://quickbooks.api.intuit.com/v3/company/${realmId}/invoice?minorversion=75`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(updatePayload)
}
);
return response.json();
};
Note: Even with sparse updates, some operations may still require
CustomerRefandLineitems depending on what you're changing.
Sending and Managing Invoices
Send via Email
const sendInvoice = async (realmId, invoiceId, email, accessToken) => {
const url = email
? `https://quickbooks.api.intuit.com/v3/company/${realmId}/invoice/${invoiceId}/send?sendTo=${email}`
: `https://quickbooks.api.intuit.com/v3/company/${realmId}/invoice/${invoiceId}/send`;
const response = await fetch(url, {
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/octet-stream'
}
});
return response.json();
};
Auto-Send on Creation
To automatically email an invoice when creating it, set EmailStatus to NeedToSend. Note that BillEmail is required when using this option:
const invoice = {
CustomerRef: { value: "123" },
BillEmail: { Address: "customer@example.com" }, // Required when EmailStatus is NeedToSend
EmailStatus: "NeedToSend", // Options: NotSet, NeedToSend, EmailSent
Line: [/* ... */]
};
Void an Invoice
const voidInvoice = async (realmId, invoice, accessToken) => {
const response = await fetch(
`https://quickbooks.api.intuit.com/v3/company/${realmId}/invoice?operation=void`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
Id: invoice.Id,
SyncToken: invoice.SyncToken
})
}
);
return response.json();
};
Reconciling Payments
Once invoices are sent, you'll need to record payments against them. QuickBooks uses a separate Payment API that links payments to invoices through the LinkedTxn object.
Record a Full Payment
To record a payment against an invoice, create a Payment object that references the invoice:
const recordPayment = async (realmId, invoiceId, amount, customerId, accessToken) => {
const payment = {
CustomerRef: { value: customerId },
TotalAmt: amount,
Line: [
{
Amount: amount,
LinkedTxn: [
{
TxnId: invoiceId,
TxnType: "Invoice"
}
]
}
]
};
const response = await fetch(
`https://quickbooks.api.intuit.com/v3/company/${realmId}/payment?minorversion=75`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json',
'Accept': 'application/json'
},
body: JSON.stringify(payment)
}
);
return response.json();
};
Partial Payments
QuickBooks supports partial payments—just set the Amount to less than the invoice total:
const recordPartialPayment = async (realmId, invoiceId, partialAmount, customerId, accessToken) => {
const payment = {
CustomerRef: { value: customerId },
TotalAmt: partialAmount,
Line: [
{
Amount: partialAmount,
LinkedTxn: [
{
TxnId: invoiceId,
TxnType: "Invoice"
}
]
}
]
};
const response = await fetch(
`https://quickbooks.api.intuit.com/v3/company/${realmId}/payment?minorversion=75`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(payment)
}
);
return response.json();
};
After recording a partial payment, the invoice's Balance field will reflect the remaining amount due.
Payment Against Multiple Invoices
A single payment can be applied across multiple invoices:
const payment = {
CustomerRef: { value: "123" },
TotalAmt: 1500.00,
Line: [
{
Amount: 1000.00,
LinkedTxn: [{ TxnId: "invoice-1", TxnType: "Invoice" }]
},
{
Amount: 500.00,
LinkedTxn: [{ TxnId: "invoice-2", TxnType: "Invoice" }]
}
]
};
Apply Credits to Invoices
If a customer has credits (from overpayments or credit memos), you can apply them to invoices:
const applyCredit = async (realmId, invoiceId, creditMemoId, amount, customerId, accessToken) => {
const payment = {
CustomerRef: { value: customerId },
TotalAmt: 0, // Zero when applying credits only
Line: [
{
Amount: amount,
LinkedTxn: [{ TxnId: invoiceId, TxnType: "Invoice" }]
},
{
Amount: amount,
LinkedTxn: [{ TxnId: creditMemoId, TxnType: "CreditMemo" }]
}
]
};
const response = await fetch(
`https://quickbooks.api.intuit.com/v3/company/${realmId}/payment?minorversion=75`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(payment)
}
);
return response.json();
};
Query Payment Status
Check if an invoice has been paid by querying its Balance field or by finding linked payments:
// Find all payments for an invoice
const query = `SELECT * FROM Payment WHERE Line.LinkedTxn.TxnId = '${invoiceId}'`;
// Or check invoice balance directly
const invoice = await getInvoice(realmId, invoiceId, accessToken);
const isPaid = invoice.Invoice.Balance === 0;
const isPartiallyPaid = invoice.Invoice.Balance > 0 &&
invoice.Invoice.Balance < invoice.Invoice.TotalAmt;
With Apideck
Apideck normalizes payment recording across all accounting platforms:
// Record a payment
const { data } = await apideck.accounting.payments.add({
consumerId,
serviceId: 'quickbooks',
payment: {
customer_id: customerId,
total_amount: 500.00,
transaction_date: new Date().toISOString(),
allocations: [
{
type: 'invoice',
id: invoiceId,
amount: 500.00
}
]
}
});
// List payments for a customer
const { data: payments } = await apideck.accounting.payments.all({
consumerId,
serviceId: 'quickbooks',
filter: { customer_id: customerId }
});
Before & After: Native QuickBooks vs. Apideck
Here's where developer experience really matters. Building invoicing with the native API requires understanding QuickBooks-specific concepts. With Apideck, you use a clean, normalized model that works across QuickBooks, Xero, NetSuite, and 30+ other accounting platforms.
Before: Native QuickBooks Invoice Creation
// The full picture of what you need to manage
class QuickBooksInvoiceService {
constructor() {
this.auth = new QuickBooksAuth();
}
async createInvoice(customerData, lineItems, options = {}) {
// 1. Handle authentication
const accessToken = await this.auth.getAccessToken();
const realmId = await this.auth.getRealmId();
// 2. Transform your data to QuickBooks format
const qbInvoice = {
CustomerRef: { value: customerData.id },
Line: lineItems.map((item, index) => ({
// QuickBooks requires Amount at line level
Amount: item.quantity * item.unitPrice,
// Must specify DetailType exactly
DetailType: "SalesItemLineDetail",
SalesItemLineDetail: {
// ItemRef is required and must exist in QuickBooks
ItemRef: {
value: item.productId,
name: item.productName // Optional but helps debugging
},
Qty: item.quantity,
UnitPrice: item.unitPrice,
// TaxCodeRef uses QuickBooks-specific codes
TaxCodeRef: item.taxable ? { value: "TAX" } : { value: "NON" }
},
Description: item.description,
LineNum: index + 1
})),
// Date format must be YYYY-MM-DD
DueDate: this.formatDate(options.dueDate || this.addDays(new Date(), 30)),
TxnDate: this.formatDate(options.invoiceDate || new Date()),
// QuickBooks calls this DocNumber (max 21 characters)
DocNumber: options.invoiceNumber,
// Private note vs customer memo are different fields
PrivateNote: options.internalMemo, // Internal only, up to 4000 chars
CustomerMemo: options.customerNote ? { value: options.customerNote } : undefined,
// Email handling - BillEmail required if EmailStatus is NeedToSend
BillEmail: customerData.email ? { Address: customerData.email } : undefined,
EmailStatus: options.sendImmediately ? "NeedToSend" : "NotSet"
};
// 3. Handle tax if applicable
if (options.taxRate) {
qbInvoice.TxnTaxDetail = {
TxnTaxCodeRef: { value: options.taxCodeId },
TotalTax: this.calculateTax(lineItems, options.taxRate)
};
}
// 4. Make the API call
const response = await fetch(
`https://quickbooks.api.intuit.com/v3/company/${realmId}/invoice?minorversion=75`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json',
'Accept': 'application/json'
},
body: JSON.stringify(qbInvoice)
}
);
// 5. Handle QuickBooks-specific errors
if (!response.ok) {
const error = await response.json();
const qbError = error.Fault?.Error?.[0];
switch (qbError?.code) {
case '6140':
throw new Error(`Duplicate document number: ${options.invoiceNumber}`);
case '6240':
throw new Error(`Duplicate name exists (customer/vendor/employee)`);
case '610':
throw new Error(`Customer not found: ${customerData.id}`);
case '2500':
throw new Error(`Invalid item reference in line items`);
case '5010':
throw new Error('Stale data - invoice was modified. Refetch and retry.');
default:
throw new Error(`QuickBooks error: ${qbError?.Message || 'Unknown'}`);
}
}
const result = await response.json();
// 6. Send email if requested (already handled via EmailStatus, but can also call send endpoint)
if (options.sendImmediately && !qbInvoice.EmailStatus) {
await this.sendInvoice(result.Invoice.Id, customerData.email);
}
// 7. Transform response back to your format
return this.transformFromQuickBooks(result.Invoice);
}
formatDate(date) {
return date.toISOString().split('T')[0];
}
addDays(date, days) {
const result = new Date(date);
result.setDate(result.getDate() + days);
return result;
}
calculateTax(lineItems, taxRate) {
const taxableAmount = lineItems
.filter(item => item.taxable)
.reduce((sum, item) => sum + (item.quantity * item.unitPrice), 0);
return taxableAmount * taxRate;
}
transformFromQuickBooks(qbInvoice) {
return {
id: qbInvoice.Id,
invoiceNumber: qbInvoice.DocNumber,
customerId: qbInvoice.CustomerRef.value,
status: qbInvoice.Balance > 0 ? 'open' : 'paid',
total: qbInvoice.TotalAmt,
balance: qbInvoice.Balance,
dueDate: qbInvoice.DueDate,
createdAt: qbInvoice.MetaData.CreateTime,
// ... more field mapping
};
}
}
Pain points:
- 100+ lines for basic invoice creation
- QuickBooks-specific field names (
DetailType,SalesItemLineDetail, etc.) - Manual date formatting
- Complex nested object structure
- Platform-specific error codes to handle
- Transform data in and out
After: With Apideck
import { Apideck } from '@apideck/node';
const apideck = new Apideck({
apiKey: process.env.APIDECK_API_KEY,
appId: process.env.APIDECK_APP_ID
});
// Create invoice - clean, intuitive API
const createInvoice = async (consumerId, invoiceData) => {
const { data } = await apideck.accounting.invoices.add({
consumerId,
serviceId: 'quickbooks', // Switch to 'xero' or 'netsuite' anytime
invoice: {
customer_id: invoiceData.customerId,
invoice_number: invoiceData.invoiceNumber,
invoice_date: invoiceData.date,
due_date: invoiceData.dueDate,
memo: invoiceData.memo,
line_items: invoiceData.items.map(item => ({
name: item.name,
description: item.description,
quantity: item.quantity,
unit_price: item.unitPrice,
tax_rate_id: item.taxRateId
}))
}
});
return data;
};
// List invoices with filters
const getUnpaidInvoices = async (consumerId) => {
const { data } = await apideck.accounting.invoices.all({
consumerId,
serviceId: 'quickbooks',
filter: {
status: 'open'
}
});
return data;
};
// Get single invoice
const getInvoice = async (consumerId, invoiceId) => {
const { data } = await apideck.accounting.invoices.one({
consumerId,
serviceId: 'quickbooks',
id: invoiceId
});
return data;
};
// Update invoice
const updateInvoice = async (consumerId, invoiceId, updates) => {
const { data } = await apideck.accounting.invoices.update({
consumerId,
serviceId: 'quickbooks',
id: invoiceId,
invoice: updates
});
return data;
};
// Delete invoice
const deleteInvoice = async (consumerId, invoiceId) => {
await apideck.accounting.invoices.delete({
consumerId,
serviceId: 'quickbooks',
id: invoiceId
});
};
Code Comparison
| Aspect | Native QuickBooks | Apideck |
|---|---|---|
| Lines of code | 100+ | 20 |
| Auth handling | Manual (50+ lines) | Automatic |
| Data transformation | Required (both ways) | None needed |
| Error handling | Platform-specific codes | Unified errors |
| Multi-platform | Complete rewrite | Change serviceId |
| Learning curve | QuickBooks docs | One unified API |
Real-World Example: CRM to Invoice
Native approach:
// When deal closes, create invoice - native QuickBooks
async function onDealWon(deal) {
const qbAuth = new QuickBooksAuth();
const accessToken = await qbAuth.getAccessToken();
const realmId = await qbAuth.getRealmId();
// First, find or create customer in QuickBooks
let customer = await findQuickBooksCustomer(deal.company.email, accessToken, realmId);
if (!customer) {
const customerResponse = await fetch(
`https://quickbooks.api.intuit.com/v3/company/${realmId}/customer?minorversion=75`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
DisplayName: deal.company.name,
PrimaryEmailAddr: { Address: deal.company.email },
CompanyName: deal.company.name
})
}
);
customer = (await customerResponse.json()).Customer;
}
// Then create the invoice
const invoice = {
CustomerRef: { value: customer.Id },
Line: deal.products.map(p => ({
Amount: p.quantity * p.price,
DetailType: "SalesItemLineDetail",
SalesItemLineDetail: {
ItemRef: { value: mapProductToQBItem(p.id) },
Qty: p.quantity,
UnitPrice: p.price
}
})),
DueDate: formatDate(addDays(new Date(), 30))
};
const response = await fetch(
`https://quickbooks.api.intuit.com/v3/company/${realmId}/invoice?minorversion=75`,
{
method: 'POST',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(invoice)
}
);
// Handle errors, send email, etc...
}
With Apideck:
// When deal closes, create invoice - with Apideck
async function onDealWon(deal) {
// Create customer if needed
const { data: customer } = await apideck.accounting.customers.add({
consumerId: deal.accountId,
serviceId: 'quickbooks',
customer: {
display_name: deal.company.name,
company_name: deal.company.name,
email: deal.company.email
}
}).catch(async (err) => {
// If customer exists, find them
if (err.status === 409) {
return apideck.accounting.customers.all({
consumerId: deal.accountId,
serviceId: 'quickbooks',
filter: { email: deal.company.email }
});
}
throw err;
});
// Create invoice
const { data: invoice } = await apideck.accounting.invoices.add({
consumerId: deal.accountId,
serviceId: 'quickbooks',
invoice: {
customer_id: customer.id,
line_items: deal.products.map(p => ({
description: p.name,
quantity: p.quantity,
unit_price: p.price
})),
due_date: addDays(new Date(), 30).toISOString()
}
});
return invoice;
}
Common Error Handling
QuickBooks Error Codes Reference
| Error Code | Message | Solution |
|---|---|---|
| 6000 | Business Validation Error | Check required fields |
| 6140 | Duplicate Document Number | Use unique DocNumber |
| 6240 | Duplicate Name Exists | Customer/vendor/employee name already exists |
| 610 | Object Not Found | Customer or Item invalid |
| 5010 | Stale Object | Refresh SyncToken and retry |
| 2500 | Invalid Reference | Referenced entity doesn't exist |
With Apideck
Errors are normalized across all platforms:
try {
await apideck.accounting.invoices.add({ ... });
} catch (error) {
if (error.status === 400) {
// Validation error - check error.detail
} else if (error.status === 404) {
// Customer or item not found
} else if (error.status === 409) {
// Duplicate invoice number
}
}
Get Started
Choosing between native integration and a unified API? Consider your long-term roadmap. If you'll need multiple accounting integrations, the unified approach saves significant engineering time.
Native QuickBooks
- Register at developer.intuit.com
- Create an app
- Implement OAuth flow
- Learn QuickBooks data model
- Build integration
- Handle edge cases
Timeline: 2-4 weeks
With Apideck
- Sign up at apideck.com
- Get API key
- Use Vault for OAuth
- Start making API calls
Timeline: 1 day
// You're ready to go
const apideck = new Apideck({ apiKey, appId });
const { data } = await apideck.accounting.invoices.add({
consumerId: 'user-123',
serviceId: 'quickbooks',
invoice: {
customer_id: 'cust-456',
line_items: [{ description: 'Services', quantity: 1, unit_price: 1000 }]
}
});
console.log('Invoice created:', data.id);
Related:
QuickBooks guides:
- How to Get Your QuickBooks API Key
- QuickBooks API Pricing and the Intuit App Partner Program
- Build an Integration with QuickBooks Desktop in 2025
- Accounts Payable Automation with QuickBooks
Accounting integrations:
- Top 15 Accounting APIs to Integrate With
- Xero API Pricing and the App Partner Program
- NetSuite Integration Guide
- Accounting API Integration for Fintech
Platform comparisons:
Ready to get started?
Scale your integration strategy and deliver the integrations your customers need in record time.







