Syncing Invoices to QuickBooks Desktop Over a REST API
- sync invoices to quickbooks desktop
- quickbooks desktop invoice api
- create invoice quickbooks desktop rest api
- quickbooks desktop integration for saas

Quick answers
Can I create QuickBooks Desktop invoices over a REST API? Yes — TenkeyBridge accepts QuickBooks Online–shaped POST /v3/company/{realmId}/invoice JSON and writes it into a Desktop or Enterprise company file.
What's the minimum payload? A CustomerRef and at least one SalesItemLineDetail line with an ItemRef and Amount.
Why does Desktop reject my DocNumber? Desktop's underlying RefNumber field maxes out at 11 characters; anything longer is rejected up front with a 400 rather than silently truncated.
What do I store after a successful write? The returned Id and SyncToken — Id is how you find the invoice again, SyncToken is how you update it without clobbering someone's edits.
Is invoice write support complete? No. Invoice writes are partial — group item lines, in particular, are not supported. Check the compatibility matrix before you design around a field.
If you already ship an integration against the QuickBooks Online API, you know what an invoice write looks like: a JSON body, a CustomerRef, a Line array, an access token in the header. The Desktop story has historically looked nothing like that — qbXML over the Web Connector, a request queue, a desktop machine that has to be running, and a type system that doesn't map cleanly onto anything you already wrote.
This post walks through what it actually takes to sync invoices from your app to a QuickBooks Desktop or Enterprise company file using the same QBO-shaped JSON you're already producing: what to send, what Desktop does differently, and the two fields you must persist or you'll be writing a reconciliation job six months from now.
The shape of the request
The endpoint and the body are the QBO ones:
POST /v3/company/{realmId}/invoice
Host: api.tenkeybridge.com
Authorization: Bearer {access_token}
Content-Type: application/json
{
"CustomerRef": { "value": "80000012-1234567890" },
"TxnDate": "2025-03-14",
"DocNumber": "INV-10427",
"Line": [
{
"DetailType": "SalesItemLineDetail",
"Amount": 1250.00,
"Description": "Monthly retainer — March",
"SalesItemLineDetail": {
"ItemRef": { "value": "80000004-1234567890" },
"Qty": 1,
"UnitPrice": 1250.00,
"TaxCodeRef": { "value": "NON" }
}
}
]
}
A successful write comes back with the created invoice, including the two fields that matter most downstream:
{
"Invoice": {
"Id": "8A1-1741910400",
"SyncToken": "0",
"DocNumber": "INV-10427",
"TotalAmt": 1250.00,
"CustomerRef": { "value": "80000012-1234567890", "name": "ExampleCo" }
},
"time": "2025-03-14T09:42:11-07:00"
}
If you've been writing against QBO, nothing here is new. The interesting part is what happens underneath, and where the model doesn't line up.
CustomerRef: Desktop resolves by ListID, not by name
CustomerRef.value must be an identifier the company file recognizes. Desktop's native identifier is a ListID — an opaque string like 80000012-1234567890, not a small integer. That's the value you get back from a customer query, and that's the value to store against your own customer records.
Do not try to synthesize it. Query first:
GET /v3/company/{realmId}/query?query=select * from Customer where DisplayName = 'ExampleCo'
Two Desktop-specific things to know:
- Job hierarchy is part of the name. Desktop customers can have sub-jobs, and the full name is colon-delimited:
ExampleCo:Warehouse Buildout. If your app models "customer" flat and your users model "customer:job," decide early which side does the mapping. An invoice written against the parent when the user expected the job is a reconciliation headache that surfaces weeks later. - Names are unique and case-insensitive-ish in practice. Creating
ExampleCowhenexamplecoexists will fail. Resolve, don't blindly create.
If CustomerRef points at something the file doesn't have, you get a 400 with a QBO-style fault rather than a half-written invoice. We went deep on how Desktop's native status codes get translated into faults your existing error handler already understands in Decoding QuickBooks Desktop Errors.
Line items
Each line needs a DetailType, an Amount, and a detail object. For invoices you'll mostly use SalesItemLineDetail, with an ItemRef that — like CustomerRef — is a Desktop ListID.
A few practical notes:
Amountis authoritative. If you sendQtyandUnitPricethat don't multiply toAmount, Desktop will use what it's given for the line total and you'll get a rounding surprise. ComputeAmountyourself and send all three consistently.DescriptionOnlylines work for notes and section headers. They carry noAmount.DiscountLineandSubTotalLinebehave differently from QBO. Desktop treats discounts as item-based lines that apply to the preceding line or subtotal, not as a document-level discount object. If your app models a single order-level discount, the cleanest mapping is usually a discount item line appended after a subtotal line.- Group item lines are not supported. Desktop's "group" items expand into multiple sub-lines inside the file, and that expansion doesn't round-trip cleanly through a QBO-shaped
Linearray. If your users invoice with group items, read the Invoice entry in the compatibility matrix before you commit to a design. This is a real gap, not a "coming soon" footnote.
Tax codes
TaxCodeRef on a line takes a Desktop sales tax code — typically TAX or NON, or a custom code defined in the file. This is one of the sharper edges between QBO and Desktop:
- QBO (US) computes tax through an automated sales tax service and largely ignores line-level codes you supply.
- Desktop computes tax from the line's
TaxCodeRefplus the transaction's sales tax item, exactly as entered.
Practically, that means you are responsible for sending the right code per line on Desktop, and the file's tax setup is responsible for the rate. If your app already calculates tax with an external engine, you have a decision to make: either mirror your computed tax as its own line and mark everything NON, or let Desktop compute and accept that the two totals can disagree by pennies. Pick one per tenant and write it down; mixing strategies inside a single company file is how you end up with a tax liability report nobody can explain.
Also: Desktop files may have sales tax disabled entirely. Sending TAX into a file with no sales tax preference enabled is an error, not a no-op. Check the company preferences once at connect time and cache the answer.
DocNumber and the 11-character wall
This is the single most common surprise when pointing a QBO integration at Desktop.
QBO's DocNumber accepts up to 21 characters. Desktop's underlying RefNumber field is capped at 11 characters. If your app generates invoice numbers like EXAMPLECO-2025-000427, every write will fail.
TenkeyBridge rejects the over-length value up front with a 400 rather than passing it through and letting Desktop truncate it:
{
"Fault": {
"Error": [
{
"Message": "Invalid field value",
"Detail": "DocNumber exceeds the QuickBooks Desktop RefNumber maximum of 11 characters.",
"code": "2000"
}
],
"type": "ValidationFault"
}
}
The up-front rejection is deliberate. Silent truncation produces two invoices that look identical in the file but map to different records in your system, and you won't notice until a customer calls about a double-billed job. A loud 400 at write time is cheaper than a silent collision discovered at month-end close.
Your options, roughly in order of how much we'd recommend them:
- Shorten the generated number. A base-36 or zero-padded sequence fits comfortably in 11 characters.
- Omit
DocNumberentirely and let Desktop auto-increment, then store what it returns. This is the lowest-friction path if your app doesn't need to control the number. - Put your long identifier somewhere else — a custom field, or
PrivateNote, or the line description — and use a shortDocNumberfor Desktop's own numbering.
Whatever you pick, validate the length in your own code before the request leaves your service. Catching it in your own validator gives you a better error message than any API can.
Store the Id and the SyncToken
Two fields come back from every successful write. Persist both, keyed to your own invoice record.
Id is the handle. It's how you fetch, update, or void the invoice later. Don't plan to re-find invoices by DocNumber — numbers get edited by hand in the file, and DocNumber is not guaranteed unique in Desktop.
SyncToken is the optimistic concurrency control. It's an integer that increments on every write. When you update, you send the SyncToken you last saw:
{
"Id": "8A1-1741910400",
"SyncToken": "0",
"sparse": true,
"DocNumber": "INV-10428"
}
If someone opened the invoice in QuickBooks and changed a line between your read and your write, the stored token is stale, and the update fails rather than overwriting their edit. That failure is the feature. Handle it by re-reading the invoice, deciding whether your change still applies, and retrying with the fresh token.
Note "sparse": true in that payload. A sparse update modifies only the fields you send; a full replacement overwrites the entire object with your version, dropping anything you didn't include. On Desktop, where bookkeepers routinely edit transactions by hand in the UI, the difference is not academic — we walked through exactly how both behave, and which to reach for when, in Sparse Updates vs. Full Replacement.
A reasonable write loop:
- Resolve
CustomerRefand eachItemRefto DesktopListIDs (cache these). - Validate
DocNumberlength locally. POSTthe invoice.- Persist
IdandSyncTokenin the same transaction that marks your record as synced. - On update, send
Id+ currentSyncToken+sparse: true, and persist the newSyncTokenfrom the response.
Batching invoices, and what "batch" doesn't mean
If you're backfilling a few thousand invoices, the batch endpoint is the right tool for throughput. It is not the right tool for atomicity. A QuickBooks batch request is a bundle of independent operations, and partial failure is the normal case — eight succeed, two fail, and you get a mixed response you have to walk item by item. If your sync code assumes all-or-nothing, you'll end up with invoices in the file that your database thinks never got written. We covered the failure modes and a workable retry shape in QuickBooks Batch Requests Are Not Transactions.
What's partial, and how to find out
Invoice write support against Desktop is partial. The honest framing: the common path — a customer, item lines, quantities, prices, tax codes, terms, due date, memo, classes — works. The long tail does not uniformly.
Known gaps worth checking before you build:
- Group item lines aren't supported, as above.
- Linked transactions (applying an invoice against an estimate or sales order) have different semantics on Desktop than QBO's
LinkedTxn. - Custom fields exist on Desktop but are defined per-file and don't map to QBO's
CustomFieldarray identically. - Attachments follow a different model.
Rather than guessing from this list, the Invoice entry in the compatibility matrix is field-by-field and is the source of truth. If a field isn't listed, assume it isn't supported and design around it.
Trying it without a company file
You don't need a QuickBooks installation to write this code. The sandbox is a hosted Desktop-backed company file you can point your existing QBO client at and start POSTing invoices against for free — including the failure cases, which are the ones worth exercising. Send a 15-character DocNumber and watch the 400 come back; send a stale SyncToken and see what your retry logic does. If you want a side-by-side of how the same request behaves against Intuit's sandbox and this one, that comparison is here.
For the full request/response reference, the API docs cover every supported field on Invoice, and the quickstart gets you authenticated and writing in about ten minutes.
FAQ
What fields do I send to create a Desktop invoice?
At minimum: CustomerRef.value set to a Desktop customer ListID, and a Line array with at least one entry carrying DetailType: "SalesItemLineDetail", an Amount, and a SalesItemLineDetail.ItemRef. Everything else — TxnDate, DocNumber, DueDate, SalesTermRef, PrivateNote, per-line TaxCodeRef — is optional but usually worth sending explicitly rather than inheriting file defaults.
Why was my DocNumber rejected?
Almost certainly length. QuickBooks Desktop's RefNumber field caps at 11 characters, and values longer than that are rejected with a 400 instead of being truncated into a silent duplicate. Shorten your generated number, or omit DocNumber and store the one Desktop assigns.
How do I update an invoice later without clobbering someone's edits?
Send the invoice's Id plus the SyncToken you got from your last read or write, with "sparse": true so only the fields you include are modified. If a bookkeeper edited the invoice in QuickBooks in the meantime, your token is stale and the write fails — re-read, re-evaluate, retry.
Can I delete or void an invoice through the API?
Void and delete follow the QBO operation pattern (POST .../invoice?operation=void and ?operation=delete), and both require a current SyncToken. Be aware that Desktop files are often in a closed accounting period; a write against a closed period will fail at the file level regardless of what your request looks like.
Does the user's QuickBooks have to be open for my writes to land?
The company file must be reachable by the connector, which is a different question from "a human has it open." Multi-user mode, hosted environments, and always-on setups all change the answer — we broke down each configuration in Integrating with Multi-User and Hosted QuickBooks Desktop.
How do I find invoices that changed in QuickBooks since my last sync?
Change data capture works against Desktop, with real constraints: a 30-day lookback window and a per-request object cap that you have to page around. Design your sync cadence so you never fall outside the window, because recovering from that means a full re-query. If you want to see the 400 for yourself, the sandbox takes about five minutes — or start at the quickstart and POST a real invoice.