How to integrate the QuickBooks Invoice API in 2026

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:

1. The native approach — Full endpoint reference, working code examples, and the gotchas that'll save you hours of debugging
2. 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

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 Id and SyncToken fields. 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 CustomerRef and Line items 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

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

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

1. Register at developer.intuit.com
2. Create an app
3. Implement OAuth flow
4. Learn QuickBooks data model
5. Build integration
6. Handle edge cases

Timeline: 2-4 weeks

With Apideck

1. Sign up at apideck.com
2. Get API key
3. Use Vault for OAuth
4. 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);

Start building with Apideck →

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:

• What is a Unified API?
• Rutter Alternatives: A Technical Evaluation

Ready to get started?

Scale your integration strategy and deliver the integrations your customers need in record time.