Accounting Connections
An accounting connection joins one of your billing entities to an accounting ledger. Runnit stays the record of what was billed and what it was billed for. The ledger mirrors it and owns your books.
Connecting, enabling and disconnecting need finance:manage_integrations.
Reading a connection and its mappings also accepts finance:manage_settings.
What a connection does
Section titled “What a connection does”Outbound, Runnit pushes what it issued: the client as a contact, issued invoices and credit notes, how a credit note was applied, voids, and the invoice PDF where the ledger accepts one.
Inbound, Runnit reads what the ledger knows about payments, through a signed webhook where the provider has one, a nightly poll, and a weekly full resync.
Where the two disagree, the difference is recorded and shown to you. It is never applied silently in either direction.
The recognition journal is a separate thing and is not part of this. It is built and exported as a file, which you post in your ledger. See Revenue and WIP.
Setting one up
Section titled “Setting one up”A connection starts disabled and syncs nothing until its mappings are complete. Runnit asks for:
- Tax rates, mapped for sales and for purchases separately, because a ledger rejects a sales tax code used on a purchase account;
- Revenue accounts, a default and one per service type where you want them split;
- Expense accounts, per expense category;
- A bad debts account; and
- Tracking, if you want client, project or service type carried across as the ledger’s own tracking dimensions.
Runnit tells you what is still unmapped rather than syncing a document to the wrong account.
More than one ledger at once
Section titled “More than one ledger at once”An entity holds at most one connection per provider, so it can be connected to Xero and QuickBooks Online at the same time.
When it is, an issued document goes to every enabled connection. Each connection keeps its own remote identity, its own mappings and its own sync status, and neither can overwrite the other’s. Draining the queue for one connection never touches the other.
Runnit knowing about two ledgers does not mean you use two. The choice is per connection, and most organisations will have one.
What each provider cannot do
Section titled “What each provider cannot do”Runnit asks each provider what it can do and skips what it cannot, naming the reason on the operation rather than failing against it repeatedly.
| Xero | QuickBooks Online | |
|---|---|---|
| Invoices and credit notes | Yes | Yes |
| Applying a credit note | Yes | No. QuickBooks applies a credit through a payment, which Runnit does not write on your behalf |
| Attaching the invoice PDF | Yes | No |
| Reading payments | One invoice at a time | As receipts, which can hold several allocations |
| Supplier contacts and bills | No | No |
| Items, classes and departments | Not used | Yes |
| Provider webhooks | Yes | No. Polling and the change feed cover the same ground |
There is no purchase-side sync for either provider. What you pay suppliers stays in Runnit. See Paying Suppliers and People.
Differences you will meet with QuickBooks
Section titled “Differences you will meet with QuickBooks”- One company file is bound when you connect, and there is no list to choose from afterwards.
- Reconnecting with a different company file is refused. Disconnect first. A different company file is not a refreshed token, and rebinding quietly would push your invoices into somebody else’s ledger.
- Revenue posts through an item, not an account. A QuickBooks revenue mapping names items, and Runnit refuses an item with no income account and warns about an inactive one.
- Customers are matched by their display name, because QuickBooks has no field Runnit owns. A contact is written as the client’s name with its contact number after it.
- A connection that is never used dies on its own. The refresh credential expires about three months after it was issued, and the connection then asks to be reconnected.
Receipts, and money that never arrived
Section titled “Receipts, and money that never arrived”A QuickBooks payment is a header against a customer with children, and a child may apply an existing credit rather than receive cash. Runnit reads each child separately, and a credit application is never recorded as money that arrived.
Where a receipt matches a payment Runnit already recorded, the existing payment is used and no second one is created. Where more than one payment could be the match, nothing is allocated automatically: it goes to a reconciliation queue for a person to resolve.
The change feed
Section titled “The change feed”For a provider that has one, Runnit keeps a durable marker of how far it has read, per connection. If the provider’s change window has expired, Runnit asks for a full resync rather than resuming into a gap, and the connection says so.
Today the feed is a health signal. The changes it notices are not yet used to target which documents get re-read; the ordinary nightly reconciliation still does that.
Turning on production use
Section titled “Turning on production use”Enabling a connection and enabling it for production are two different things. A connection starts with production off, and turning it on is refused without recorded evidence from the provider, kept with who recorded it and when.
For QuickBooks that evidence is the authorisation and token exchange, an invoice created, read and voided, a receipt with more than one allocation, a credit application, a version conflict, a change feed response including a deletion, a verified webhook, an observed rate limit and a refused reconnect to a different company file. Xero has its own list. Runnit shows the state on the connection, so you can see what has been recorded rather than assume it.
Ledgers Runnit does not support
Section titled “Ledgers Runnit does not support”Named with the reason, so the answer is not a silent absence:
| Ledger | Why not |
|---|---|
| NetSuite | The integration record, its certificate and the role permissions are issued inside a NetSuite account, and Runnit has no adapter for it |
| Sage Intacct | Sender credentials are issued by Sage to a registered partner, and Runnit has no adapter for it |
| MYOB | AccountRight holds a second credential per company file, and Runnit has no adapter for it |
Selecting one of these is refused rather than starting a flow that could not finish.
Next step
Section titled “Next step”Reconcile what actually moved through the bank: Bank Reconciliation, or close the month at Month End.
Configuration shown on the page
Section titled “Configuration shown on the page”The page reports whether Xero and QuickBooks credentials are configured for this deployment, and lists unavailable ledgers with the server’s reasons. Configured credentials are a separate thing from production approval, which is recorded per connection.