Symptoms
You may notice one or more of the following:
No new invoices appear after syncing, even though unpaid invoices exist in your accounting system.
Previously working imports now return zero results.
Some invoices are imported but others are missing.
You see an error message when attempting to sync.
On Settings > Integrations, the connection shows Reconnect needed or Sync failed.
Quick reference: authentication per integration
The fix depends on how each integration authenticates. Use this table to jump to the right section.
Integration | Authentication method | Most common cause |
Stripe | OAuth | Revoked connection that needs authorization again |
QuickBooks Online | OAuth2 | Expired or revoked OAuth connection |
Zoho Books | OAuth2 | Expired or revoked OAuth connection |
KashFlow | Username, password, and memorable word | Saved login details no longer accepted |
Zapier | API Key (XApiKey) | Invalid Debitura API key |
What Reconnect needed and Sync failed mean
Settings > Integrations shows a status for each connection. Two of them point to a problem:
Reconnect needed - the accounting system no longer accepts Debitura's access. An admin fixes it from that connection's row: Connect again for Stripe, Zoho Books, and KashFlow, or Intuit's Connect to QuickBooks button for QuickBooks Online. Other users see "Ask an admin to connect it again."
Sync failed - the last import of invoices failed, but the accounting system has not refused Debitura's access. Debitura tries again automatically, so reconnecting is not the fix. If it keeps failing, email [email protected].
For Stripe, Zoho Books, and KashFlow, the status changes the next time Debitura syncs that connection, not when you open the page. Opening View invoices for the connection can start a sync sooner.
Stripe: common causes and fixes
Cause 1: Stripe connection revoked or needs authorization again
Stripe connects through OAuth (Connect with Stripe). Debitura refreshes access automatically, but if access is revoked on the Stripe side, Debitura can no longer fetch invoices and asks you to reconnect. Existing connections set up earlier with a restricted API key continue to work; if one of them stops working, reconnect it through OAuth.
Fix:
Go to Settings > Integrations. If the Stripe connection shows Reconnect needed, click Connect again on that row, then Connect with Stripe. Reconnecting the same Stripe account keeps the existing integration and its imported cases.
Run a new sync to verify invoices are imported.
For full setup instructions, see How to connect Stripe.
Cause 2: Missing customer data
A Stripe invoice whose customer has an incomplete address is still listed on the Unpaid invoices page, but it cannot start until the debtor details are complete.
Fix:
On the Unpaid invoices page, correct the debtor's address before you start. The correction applies for this visit only and is not written back to Stripe.
Or, in your Stripe Dashboard, make sure the customer has a complete billing address (street, city, postal code, and country), then refresh the list on the Unpaid invoices page.
QuickBooks Online: common causes and fixes
Cause 1: OAuth connection expired or revoked
QuickBooks Online uses OAuth2 authentication. Debitura handles token refresh automatically, so expired tokens are refreshed for you - you only need to re-authorize if the connection has actually been broken. If you actively disconnect Debitura from inside QuickBooks (Apps > Disconnect), Debitura keeps the integration and, once it confirms that access was revoked, flags it Reconnect needed. If instead the connection stops working on its own - for example your QuickBooks password changed, or access was revoked outside the normal Disconnect flow - Debitura keeps the integration visible and flags it Reconnect needed rather than silently removing it. Debitura detects this the next time you open the Integrations page or View invoices for that connection, so it isn't instant.
Fix:
Go to Settings > Integrations in your Debitura account.
Check the status of your QuickBooks connection.
If the connection shows a "Reconnect needed" state, click Connect to QuickBooks to re-authorize. You will be redirected to QuickBooks to sign in and grant access again.
After reconnecting, run a sync to verify invoices are imported.
For full setup instructions, see How to connect QuickBooks Online.
Cause 2: Wrong QuickBooks company connected
If you have multiple QuickBooks Online companies, you may have authorized Debitura against a different company than intended. Invoices will only be imported from the connected company.
Fix:
During the OAuth flow, QuickBooks asks you to choose which company to connect. Verify you selected the correct one.
If the wrong company is connected, disconnect the integration in Debitura and reconnect, selecting the correct company during the OAuth step.
Cause 3: Invoice cannot be started yet
On the Unpaid invoices page, an invoice you expected to send to collection may not be ready to start yet. The two most common reasons are:
The invoice is not yet past its due date.
The QuickBooks customer is missing a complete billing address - street, city, state (for customers in the United States), and country.
If neither the QuickBooks customer nor your Debitura company account has a country set, Debitura falls back to your QuickBooks company's home country. If that is also missing, the invoice is still listed, but with no debtor country or jurisdiction.
Fix:
On the Unpaid invoices page, complete the missing address details before you start. These corrections are not written back to QuickBooks and are discarded if you refresh the page before starting.
Or, in QuickBooks, open the customer record for the affected invoice and complete the billing address (add the country, and the state if the customer is in the United States), then refresh the list on the Unpaid invoices page. Debitura reads the corrected data from QuickBooks - no reconnection needed.
Zoho Books: common causes and fixes
Cause 1: OAuth connection expired or revoked
Zoho Books uses OAuth2 authentication. Debitura handles token refresh automatically, but the connection can break if you revoke access in your Zoho account settings or if Zoho invalidates the token.
Fix:
Go to Settings > Integrations in your Debitura account.
Check the status of your Zoho Books connection.
If the connection shows Reconnect needed, click Connect again on that row to re-authorize. You will be redirected to Zoho to sign in and grant access. The correct Zoho data centre is detected automatically.
After reconnecting, run a sync to verify invoices are imported.
For full setup instructions, see How to connect Zoho Books.
Cause 2: Wrong Zoho Books organization connected
If you have multiple organizations in Zoho Books, Debitura connects to the first organization automatically during the OAuth flow. Invoices from other organizations will not be imported.
Fix:
Verify in Zoho Books which organization contains the invoices you need.
If the wrong organization is connected, disconnect and reconnect. Ensure the correct organization is the primary one during the OAuth step.
KashFlow: common causes and fixes
Cause 1: KashFlow no longer accepts the saved login
KashFlow connects with your KashFlow username, password, and memorable word rather than a sign-in redirect. If KashFlow stops accepting the saved login details, the connection shows Reconnect needed.
Fix:
Go to Settings > Integrations in your Debitura account.
On the KashFlow connection, click Connect again.
Enter your KashFlow username, password, and memorable word, then click Connect KashFlow.
If Debitura does not accept the login, check your username and password by logging in to KashFlow directly at app.kashflow.com. If you are unsure of your memorable word, contact KashFlow support to reset it.
For full setup instructions, see How to connect KashFlow.
Zapier: common causes and fixes
Cause 1: Debitura API key is invalid or expired
The Zapier integration authenticates using your Debitura API key (the same key used for direct API access). If the key has been rotated or deleted, Zapier can no longer communicate with Debitura.
Fix:
Go to API Keys in your Debitura account and verify your API key is active.
If needed, generate a new API key. See How to generate an API key.
In Zapier, go to your Debitura connection settings and update the API key.
Test the connection in Zapier to confirm it works.
For full setup instructions, see How to connect Zapier.
Cause 2: Wrong environment (test vs production)
Debitura has separate test and production environments. If you are using a test API key with the production environment (or vice versa), the connection will fail.
Fix:
Check whether you are using the correct API key for your environment:
Production: generated from app.debitura.com
Test: generated from testapp.debitura.com
Update the key in Zapier if you were using the wrong one.
Cause 3: Zapier polling delay
Zapier triggers use polling (not real-time webhooks). The polling frequency depends on your Zapier subscription tier. On free plans, Zapier checks for new data every 15 minutes. Paid plans poll more frequently (as often as every 1 to 2 minutes).
Fix: If data appears delayed rather than missing, wait for the next polling cycle. You can also manually trigger a test in the Zapier editor to check whether the connection is working.
General checks (all integrations)
If the integration-specific fixes above do not resolve your issue, try these general steps:
Check invoice status in your accounting system. Debitura only imports unpaid invoices. Stripe imports invoices with status "open." Zoho Books imports invoices that are still unpaid. QuickBooks lists invoices that still have a balance above zero, including partially paid ones, with the remaining balance as the amount to recover. Apart from that QuickBooks exception, an invoice that has been partially or fully paid will not appear in Debitura.
Check debtor address data. All integrations validate that the customer/debtor has complete address information. For Stripe, QuickBooks Online and Zoho Books, an invoice with an incomplete debtor address is still listed on the Unpaid invoices page but cannot start until the details are complete. You can correct supported debtor details there before you start, without changing your accounting system. KashFlow keeps its own import page.
Check for duplicates. All integrations prevent duplicate case creation. If a case was already created from an invoice, Debitura does not create a second case for it. On the Unpaid invoices page, check the Sent to Debitura count.
QuickBooks: check country data. If neither the QuickBooks customer nor your Debitura company account has a country, Debitura uses your QuickBooks company's home country. If that is also missing, the invoice is listed without a debtor country or jurisdiction. Set the country on the customer record in QuickBooks, or correct the debtor's country on the Unpaid invoices page, before you start a case.
Check whether the list finished loading. On the Unpaid invoices page, rows shown while invoices are still loading are provisional. If loading was stopped with Stop and use loaded invoices, or the list reached its time or invoice limit, other invoices may be missing - the page tells you when this is the case, and the invoices shown are not necessarily the oldest or the newest. Refresh the list and let it finish loading. If invoices are still missing, contact support (see below).
Check a start that shows Not confirmed. If starting an invoice shows Not confirmed, do not start the same invoice again. Check the result of that same request first, and contact support if it stays unclear.
Escalation
If the steps above do not resolve the issue, contact Debitura Support and include the following information:
Which integration you are using (Stripe, QuickBooks Online, Zoho Books, KashFlow, or Zapier).
When the sync last worked (approximate date and time).
Two or three sample invoice IDs or numbers from your accounting system that should have been imported but were not.
Screenshots of any error messages you see in Debitura or in the external system.
Whether you made any recent changes (rotated keys, changed passwords, revoked access, switched accounts or organizations).
For an overview of all available integration methods, see Integration options.
Developer Docs: Developers: Want to troubleshoot API key authentication or error codes programmatically? See Developer Docs: Authentication.