FreshBooks integration
FreshBooks integration
The FreshBooks integration connects one xClause company to one FreshBooks business. It sends your xClause invoices, and the clients they belong to, to FreshBooks, and can refresh client details from FreshBooks.
What it does
- Creates a FreshBooks invoice for each xClause invoice, either automatically or when you click Sync All. Invoices arrive in FreshBooks as drafts.
- Creates or updates the FreshBooks client for an invoice's client when that client has not been linked yet.
- Refreshes the name, address and phone of clients you already linked to a FreshBooks client.
- Lets you import FreshBooks clients as xClause clients, one at a time, from Manage.
- Makes FreshBooks invoice lines available as a read-only source for SOW import (Invoice lines).
xClause does not read payments from FreshBooks and does not update invoice status from FreshBooks.
Before you start
- Your xClause plan must include accounting integrations. The Free, Free Plan and MSP Starter plans do not. On those plans the connect step fails with "Accounting integrations are not available on your [plan name] plan. Upgrade to Pro to connect integrations."
- Any user who belongs to your xClause company can connect, change settings, sync and disconnect. The code checks company membership, not a specific role.
- You need to be able to sign in to FreshBooks and authorize xClause. The FreshBooks account must have a business; xClause connects the first business on the account.
Connect
- In xClause, go to Settings > Integrations.
- Under Accounting, click the FreshBooks tile. The FreshBooks panel opens.
- Click Connect to FreshBooks. A Connect to FreshBooks window opens.
- Click Connect. You go to FreshBooks to sign in and grant permissions.
- You return to Settings > Integrations. Open the FreshBooks tile again. The panel shows a Connected badge, Business ID, Connected since, Last synced and Connection status.
To re-authorize later, click Update connection, then Reauthorize.
New connections start with these settings:
| Setting | Default |
|---|---|
| Auto-sync invoices to FreshBooks | Off |
| Auto-sync clients to FreshBooks | On (but see What syncs) |
Permissions
xClause requests these scopes:
user:profile:read user:clients:read user:clients:write user:invoices:read user:invoices:write
xClause stores the access token and refresh token encrypted, and does not see your FreshBooks password.
These are the only FreshBooks API calls xClause makes from the product:
| FreshBooks endpoint | What xClause does | Access |
|---|---|---|
users/me (auth API, at connect time) | Reads your profile to find your business ID | Read-only |
clients/clients (search by organization) | Looks for a client with the same name as the xClause client | Read-only |
clients/clients (POST, PUT) | Creates a client, or updates the client with the same name: organization, first/last name, email, street address, phone, currency USD | Read + write |
clients/clients (GET, paged 100) | Lists clients to refresh linked clients and to build the Manage list | Read-only |
invoices/invoices (POST) | Creates an invoice: client, dates, invoice number, notes, line items, currency USD, draft status | Read + write |
invoices/invoices (GET, paged 100) | Reads invoices and lines for SOW import | Read-only |
What syncs
Nothing runs on a schedule. Every sync is triggered by an action in xClause.
| Data | Direction | Trigger |
|---|---|---|
| Invoice to FreshBooks invoice | xClause to FreshBooks | Auto-sync invoices to FreshBooks is on and you create an invoice, or send an invoice that is not yet synced. With the setting off, click Sync All, which syncs every unsynced invoice in status DRAFT, SENT or PAID regardless of the setting. |
| Client to FreshBooks client | xClause to FreshBooks | Happens as part of the first invoice sync for a client with no saved FreshBooks client ID. If a FreshBooks client with the same organization name exists, xClause updates it with the xClause details. xClause saves the FreshBooks client ID on the client. |
| Client details | FreshBooks to xClause | Sync All. Updates only clients already linked to a FreshBooks client. It does not create new clients. |
| New clients from FreshBooks clients | FreshBooks to xClause | Clients & users > Manage. Check Import this org as a client for each client, then click Save. |
Details:
- Auto-sync clients to FreshBooks. This setting saves, but xClause does not push a new client to FreshBooks when you create it. The client reaches FreshBooks when its first invoice syncs.
- Invoices. Each xClause invoice line becomes a FreshBooks line with its description, quantity and unit cost in USD. FreshBooks invoices are created as drafts; you send them from FreshBooks.
- Sync All. Runs the client refresh, then the invoice sync. Results show as "Sync completed: N invoices created" (and client counts), with a warning if any failed.
- Failures. If an automatic invoice sync fails when you create an invoice, the invoice is still created and nothing is shown. If it fails when you send an invoice, the invoice is still sent and xClause reports "FreshBooks sync failed. The invoice was still sent."
- Client users. You pick which contacts become client users in Manage. Later syncs import new contacts automatically only when Keep picked clients' contacts updated on each FreshBooks sync is on.
Troubleshooting
| What you see | What it means | What to do |
|---|---|---|
| Needs refresh badge, or Connection status shows Needs reconnecting | The stored access token has passed its expiry time. xClause refreshes it automatically the next time it calls FreshBooks, so syncs can still work. | Try Sync All. If it fails with an authentication error, click Update connection, then Reauthorize. |
| "Failed to connect to FreshBooks", or the plan message shown above | The connect request was refused or failed. | Check your plan and try again. |
| "We couldn't load your FreshBooks connection status. Check your connection and refresh." | The status request failed. | Reload the page. |
| "Failed to sync with FreshBooks" | The sync request failed. | Try again. If it repeats, reauthorize. |
| "Sync completed with N errors. Check console for details." | Some records failed. Details are only in your browser's developer console. | Open the console and read the logged errors. |
| "We couldn't save your settings. Check your connection and try again." | A toggle did not save. The toggle reverts. | Try again. |
FreshBooks authentication failed, access forbidden, rate limit exceeded, server error, request timed out, Network error connecting to FreshBooks | Error text from the FreshBooks API, logged per record. | For authentication or forbidden errors, reauthorize. For the others, wait and retry. |
Failed to refresh FreshBooks token, or FreshBooks credentials invalid - reconnect required | FreshBooks rejected the refresh token, or the stored credentials cannot be read. | Click Update connection, then Reauthorize. |
If the connect redirect fails, you return to Settings > Integrations with an error code in the URL, such as error=no_business_found or error=token_exchange_failed. xClause does not display the code on the page. Try again; if it repeats, contact support with the code.
Disconnecting
- Open the FreshBooks tile and click Disconnect.
- Confirm: "Are you sure you want to disconnect from FreshBooks? This will remove all integration settings."
xClause deletes the saved connection, which includes the stored tokens, the business ID and your sync settings. It does not send a request to FreshBooks. Clients and invoices already created in FreshBooks stay there. xClause keeps the FreshBooks client IDs on your clients and the FreshBooks invoice IDs on your invoices, so after you reconnect, invoices that were already synced are not sent again. To also remove xClause's authorization on the FreshBooks side, revoke it in FreshBooks.