QuickBooks to Square
Prepare a Square Order fragment from one fresh, authoritative QuickBooks invoice and preserve its evidence.
On this page
Link the source to Square
- Connect and reconcile QuickBooks inside the same merchant and environment as Square.
- Resolve factual invoice and item-mapping exceptions before payment preparation.
- Enable the QuickBooks source on the Square integration with authority over both providers.
- Issue a Square-integration Carden key with invoices:read and enrichment:write.
A Stripe-integration key cannot call Square preparation. Linking does not alter existing keys and does not grant QuickBooks management scopes to the Square service.
Prepare one stored invoice
POST /api/v1/square/order-enrichment/from-invoice| Input | Rule |
|---|---|
| invoice reference | Exactly one invoiceId, quickbooksInvoiceId, or unambiguous invoiceNumber. |
| amountMinor / currency | Positive full invoice amount and exact lowercase source currency. |
| expectedRevision | Recommended current revision from invoice review. |
| idempotencyKey | Stable preparation key persisted before the first request. |
- The invoice must be open, positive, fully unpaid, and ready.
- The QuickBooks source must be active, fresh, and free of pending refresh work.
- Fractional quantities, unresolved source facts, unsupported freight or deposits, and invalid arithmetic remain blocked.
- Partial allocations and combined invoices require a separately supported matching workflow.
Merge only the Order fragment
The response includes Square request fields in data and immutable source evidence in preparation. Save preparation.id, snapshotId, revision, source IDs, amount, currency, and diagnostic request ID with the payment attempt.
Add the merchant's real location_id and Square Order idempotency key outside the Carden fragment. Create the Order once, then call CreatePayment with the returned order_id and a separately idempotent provider request.
Report from saved preparation evidence
Use preparation.id as enrichmentRequestId when delivering the Square payment observation. Later captures, failures, cancellations, or refunds keep attemptId and preparation.id while using a new eventId and cumulative amounts.
A later QuickBooks edit or disconnect cannot rewrite the historical snapshot. If actual Payment amount or currency differs, report the actual Square facts and retain the correlation exception for review.