QuickBooks invoice data
Look up imported QuickBooks invoices, inspect source provenance, and use immutable snapshots for provider preparation.
On this page
Access a linked source
Use a Stripe- or Square-integration Carden key with explicitly granted invoices:read to read invoices from that payment integration's linked QuickBooks source. Provider preparation also requires enrichment:write; reporting separately requires payments:write.
The source link and invoice-read grant require authority over both the QuickBooks source and payment destination in the same merchant and environment. Existing keys receive no automatic grants. An invoice ID, realmId, or caller-supplied organization cannot broaden access.
List or find invoices
GET /api/v1/invoices?quickbooksInvoiceId=1042&limit=20
GET /api/v1/invoices?invoiceNumber=INV-1042&limit=20| Query field | Meaning |
|---|---|
| quickbooksInvoiceId | Optional exact QuickBooks Invoice ID; this is not the Carden invoice UUID. |
| invoiceNumber | Optional exact source invoice number. Resolve ambiguous results instead of selecting the first result. |
| cursor | Optional opaque pagination cursor from the preceding page. |
| limit | Optional integer from 1 to 100; defaults to 25. |
Follow nextCursor with unchanged filters until it is null. An empty invoices array means there is no matching visible record in the authorized linked source; it does not prove the invoice never existed in QuickBooks.
{
"object": "invoice.list",
"api_version": "v1",
"data": {
"invoices": [
{
"id": "11111111-1111-4111-8111-111111111111",
"quickbooksInvoiceId": "1042",
"invoiceNumber": "INV-1042",
"status": "open",
"currency": "usd",
"totalAmountMinor": 10800,
"sourceVersion": "3",
"revision": "invoice-revision-example-3",
"snapshotId": "22222222-2222-4222-8222-222222222222",
"checkedThrough": "2026-01-01T11:59:00.000Z",
"ready": true,
"issues": []
}
],
"nextCursor": null
}
}Interpret readiness
| Field | Meaning |
|---|---|
| id / quickbooksInvoiceId | Carden invoice UUID and authoritative external QuickBooks Invoice ID. |
| invoiceNumber / status | Source invoice number and current known state. |
| currency / totalAmountMinor | Lowercase currency and integer minor-unit total; unresolved values remain null. |
| sourceVersion | Provider version when available. |
| revision / snapshotId | Current source-and-mapping revision and immutable snapshot identity when available. |
| checkedThrough | Source freshness boundary from the latest successful check, not the time the page was opened. |
| ready | Whether the invoice passed the currently supported preparation checks at inspection time. |
| issues | Source, mapping, validation, payment, freshness, or access issues that keep unsupported facts explicit. |
Preparation rechecks authorization, source freshness, revision, and full-invoice economics even when ready was true during lookup. The current freshness check requires a completed source checkpoint within four hours and no active or pending refresh.
Retrieve invoice detail and provenance
GET /api/v1/invoices/{invoiceId}A successful response is { object: invoice, api_version: v1, data: InvoiceDetail }. InvoiceDetail extends the summary with a StoredInvoice or null and source provenance. A missing or out-of-scope identifier is never permission to search another merchant.
{
"object": "invoice",
"api_version": "v1",
"data": {
"id": "11111111-1111-4111-8111-111111111111",
"quickbooksInvoiceId": "1042",
"invoiceNumber": "INV-1042",
"status": "open",
"currency": "usd",
"totalAmountMinor": 10800,
"sourceVersion": "3",
"revision": "invoice-revision-example-3",
"snapshotId": "22222222-2222-4222-8222-222222222222",
"checkedThrough": "2026-01-01T11:59:00.000Z",
"ready": true,
"issues": [],
"invoice": {
"invoiceNumber": "INV-1042",
"purchaseOrderReference": null,
"status": "open",
"currency": "usd",
"subtotalAmountMinor": 10000,
"taxAmountMinor": 800,
"shippingAmountMinor": 0,
"discountAmountMinor": 0,
"totalAmountMinor": 10800,
"balanceAmountMinor": 10800,
"taxRepresentation": "transaction",
"discountRepresentation": "transaction",
"issuedAt": null,
"dueAt": null,
"voidedAt": null,
"lineItems": [
{
"sourceLineId": "1",
"sourceItemId": "42",
"sequence": 1,
"productName": "Industrial filters, boxed",
"description": null,
"productCode": "FILTER-01",
"unitOfMeasure": "box",
"commodityCode": null,
"quantity": "2",
"unitAmountMinor": 5000,
"subtotalAmountMinor": 10000,
"taxAmountMinor": null,
"discountAmountMinor": null,
"totalAmountMinor": null
}
]
},
"provenance": {
"sourceIntegrationId": "33333333-3333-4333-8333-333333333333",
"sourceConnectionId": "quickbooks_connection_example",
"sourceRecordId": "66666666-6666-4666-8666-666666666666",
"mapperVersion": "quickbooks-stored-invoice.v2",
"dependencies": [
{
"sourceRecordId": "66666666-6666-4666-8666-666666666666",
"objectType": "Invoice",
"externalId": "1042"
},
{
"sourceRecordId": "77777777-7777-4777-8777-777777777777",
"objectType": "Item",
"externalId": "42"
},
{
"sourceRecordId": "88888888-8888-4888-8888-888888888888",
"objectType": "Preferences",
"externalId": "preferences"
}
],
"mappings": [
{
"id": "item_mapping_example",
"sourceItemId": "42",
"productCode": "FILTER-01",
"unitOfMeasure": "box",
"version": 2,
"evidence": "Fixture merchant confirmed the item code and that this item is sold by the box.",
"approvedBy": "fixture_reviewer",
"approvedAt": "2026-01-01T11:00:00.000Z"
}
]
}
}
}Provenance identifies the exact source integration, connection, record, mapper version, Invoice, Item, and Preferences dependencies, plus any confirmed item mappings. Mapping evidence retains its source item, factual value, reviewer, approval time, and version. These references are audit evidence, not raw provider payloads or credentials.
Stored invoice lines retain sourceLineId and nullable sourceItemId. Under transaction-level tax or discounts, unallocated line tax, discount, and total amounts stay null. Carden never invents item-level allocations merely to satisfy a destination field.
const matches = await carden.invoices.list({
quickbooksInvoiceId: order.quickbooksInvoiceId,
limit: 2,
});
if (matches.invoices.length !== 1 || matches.nextCursor) {
throw new Error("Resolve the missing or ambiguous invoice before continuing.");
}
const invoice = await carden.invoices.retrieve(matches.invoices[0].id);
if (!invoice.ready || !invoice.revision) {
throw new Error("Resolve the invoice issues before continuing.");
}Use one invoice for provider preparation
Stripe and Square use the same exact stored-invoice selector: one of invoiceId, quickbooksInvoiceId, or invoiceNumber; a positive amountMinor; lowercase currency; a saved idempotencyKey; and optional expectedRevision. The source must be linked to the chosen destination.
| Body field | Rule |
|---|---|
| invoice selector | Supply exactly one identifier. Invoice numbers must resolve unambiguously. |
| amountMinor | Must equal the entire positive open invoice total and balance. |
| currency | Must exactly match the invoice currency. |
| expectedRevision | Recommended to reject a source or mapping change after review. |
| idempotencyKey | Persist 1–160 allowed characters before the first preparation request. |
{
"invoiceId": "11111111-1111-4111-8111-111111111111",
"amountMinor": 10800,
"currency": "usd",
"expectedRevision": "invoice-revision-example-3",
"idempotencyKey": "prepare_attempt_1042_1"
}- Only exact full, open, fully unpaid invoices are supported by this flow.
- Partial payments, combined invoices, overpayments, amount mismatches, and currency mismatches stay blocked.
- The linked source must be active and fresh with no pending refresh.
- Unsupported tax-inclusive data, group lines, deposits, unsupported freight, unresolved item facts, and invalid arithmetic stay in exception review.
The QuickBooks mapper supports USD, CAD, EUR, GBP, AUD, and NZD and accepts no more than 1,000 source lines. Stripe and Square adapters can apply narrower limits. These are validation limits, not permission to truncate an invoice.
Preserve stable preparation identity
{
"object": "stripe.payment_intent_enrichment",
"api_version": "v1",
"data": {
"payment_details": {
"order_reference": "INV-1042"
},
"amount_details": {
"enforce_arithmetic_validation": true,
"line_items": [
{
"product_name": "Industrial filters, boxed",
"product_code": "FILTER-01",
"unit_cost": 5000,
"quantity": 2,
"unit_of_measure": "box"
}
],
"tax": {
"total_tax_amount": 800
}
}
},
"preparation": {
"id": "44444444-4444-4444-8444-444444444444",
"invoiceId": "11111111-1111-4111-8111-111111111111",
"snapshotId": "22222222-2222-4222-8222-222222222222",
"revision": "invoice-revision-example-3",
"sourceIntegrationId": "33333333-3333-4333-8333-333333333333",
"sourceConnectionId": "quickbooks_connection_example",
"checkedThrough": "2026-01-01T11:59:00.000Z",
"createdAt": "2026-01-01T12:00:00.000Z",
"amountMinor": 10800,
"currency": "usd"
}
}A source-backed response keeps destination request fields in data and immutable source evidence in the sibling preparation object. SDKs return the native equivalent { enrichment, preparation, requestId }. Merge only enrichment into the provider request.
| Preparation field | Meaning |
|---|---|
| id | Stable preparation identity. Use it as enrichmentRequestId on the later payment report. |
| invoiceId / snapshotId / revision | The Carden invoice, immutable snapshot, and exact source-and-mapping revision. |
| sourceIntegrationId / sourceConnectionId | The QuickBooks source that supplied the evidence. |
| checkedThrough / createdAt | The source-check boundary and preparation creation time. |
| amountMinor / currency | The full payment amount and currency validated for this preparation. |
Identical accepted retries retain preparation.id while diagnostic x-carden-request-id values can differ. Reusing an idempotency key with changed input conflicts, and idempotency never bypasses current authorization or freshness checks.