> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routemcp.io/llms.txt
> Use this file to discover all available pages before exploring further.

# FreshBooks

> Sync invoices, bills, customers, suppliers, payments, expenses, items, tax rates, credit notes, chart of accounts, journal entries, projects, employees, and the four standard financial reports with FreshBooks via OAuth 2.0.

<img src="https://icon.horse/icon/freshbooks.com" alt="FreshBooks" style={{ width: "48px", height: "48px", marginBottom: "16px" }} />

## Overview

| Property    | Value                                         |
| ----------- | --------------------------------------------- |
| Slug        | `freshbooks`                                  |
| Auth        | OAuth 2.0                                     |
| API version | `alpha` (current production)                  |
| Sandbox     | No — use a low-value test account             |
| Rate limit  | \~2,500 req/hour/business, \~20 req/sec burst |

## Supported resources

| Resource                   | List                                      | Get                                       | Create                                    | Update                                    | Delete                                    |
| -------------------------- | ----------------------------------------- | ----------------------------------------- | ----------------------------------------- | ----------------------------------------- | ----------------------------------------- |
| Invoice                    | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> |
| Contact                    | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> |
| Account                    | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | —                                         | —                                         | —                                         |
| Payment                    | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> |
| Tax Rate                   | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> |
| Journal Entry              | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | —                                         | —                                         | —                                         |
| Expense                    | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> |
| Purchase Order             | —                                         | —                                         | —                                         | —                                         | —                                         |
| Sales Order                | —                                         | —                                         | —                                         | —                                         | —                                         |
| Credit Note                | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> |
| Vendor Credit              | —                                         | —                                         | —                                         | —                                         | —                                         |
| Item                       | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> |
| Tracking Category          | —                                         | —                                         | —                                         | —                                         | —                                         |
| Payment Method             | —                                         | —                                         | —                                         | —                                         | —                                         |
| Payment Term               | —                                         | —                                         | —                                         | —                                         | —                                         |
| Company Info               | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | —                                         | —                                         | —                                         |
| Accounting Period          | —                                         | —                                         | —                                         | —                                         | —                                         |
| Employee                   | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | —                                         | —                                         | —                                         |
| Project                    | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> |
| Attachment                 | —                                         | —                                         | —                                         | —                                         | —                                         |
| Expense Report             | —                                         | —                                         | —                                         | —                                         | —                                         |
| Item Fulfillment           | —                                         | —                                         | —                                         | —                                         | —                                         |
| Balance Sheet              | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | —                                         | —                                         | —                                         |
| Income Statement           | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | —                                         | —                                         | —                                         |
| Cash Flow Statement        | <span style={{color: "#16a34a"}}>✓</span> | <span style={{color: "#16a34a"}}>✓</span> | —                                         | —                                         | —                                         |
| General Ledger Transaction | <span style={{color: "#16a34a"}}>✓</span> | —                                         | —                                         | —                                         | —                                         |
| Transaction                | <span style={{color: "#16a34a"}}>✓</span> | —                                         | —                                         | —                                         | —                                         |
| Bank Feed Account          | —                                         | —                                         | —                                         | —                                         | —                                         |
| Bank Feed Transaction      | —                                         | —                                         | —                                         | —                                         | —                                         |
| Address                    | —                                         | <span style={{color: "#16a34a"}}>✓</span> | —                                         | —                                         | —                                         |
| Phone Number               | —                                         | <span style={{color: "#16a34a"}}>✓</span> | —                                         | —                                         | —                                         |

## Connect setup

FreshBooks uses OAuth 2.0. You need an app registered in the **FreshBooks Developer Portal**.

<Steps>
  <Step title="Create a FreshBooks app">
    Sign in at [my.freshbooks.com/#/developer](https://my.freshbooks.com/#/developer) and click **Create an App**. Copy the **Client ID** and **Client Secret**.
  </Step>

  <Step title="Add the redirect URL">
    In your app's **Redirect URIs** list, add:

    ```
    https://api.routemcp.io/api/v1/auth/callback
    ```
  </Step>

  <Step title="Configure required scopes">
    Enable the following scopes on your app:

    * `user:profile:read`
    * `user:account:read`
    * `user:account:write`
    * `user:clients:read`
    * `user:clients:write`
    * `user:invoices:read`
    * `user:invoices:write`
    * `user:payments:read`
    * `user:payments:write`
    * `user:expenses:read`
    * `user:expenses:write`
    * `user:taxes:read`
    * `user:taxes:write`
    * `user:billable_items:read`
    * `user:billable_items:write`
    * `user:credit_notes:read`
    * `user:credit_notes:write`
    * `user:bills:read`
    * `user:bills:write`
    * `user:bill_vendors:read`
    * `user:bill_vendors:write`
    * `user:bill_payments:read`
    * `user:bill_payments:write`
    * `user:journal_entries:read`
    * `user:journal_entries:write`
    * `user:projects:read`
    * `user:projects:write`
    * `user:teams:read`
    * `user:reports:read`
    * `user:estimates:read`
  </Step>

  <Step title="Connect via the widget">
    When your end user opens the Connect widget, they will enter the Client ID and Client Secret, then be redirected to FreshBooks to authorize the connection.
  </Step>
</Steps>

## Usage

```bash theme={null}
# List invoices (AR + AP merged) from FreshBooks
curl "https://api.routemcp.io/api/v1/accounting/invoice?provider=freshbooks" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "X-End-User-Id: user-123"

# Create a bill (AP) — set type=ACCOUNTS_PAYABLE
curl -X POST "https://api.routemcp.io/api/v1/accounting/invoice?provider=freshbooks" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -H "X-End-User-Id: user-123" \
  -d '{ "type": "ACCOUNTS_PAYABLE", "contact": "urn:freshbooks:contact:vendor:42", "total_amount": 850.00, "due_date": "2026-06-01" }'

# Update by URN
curl -X PATCH "https://api.routemcp.io/api/v1/accounting/invoice/urn:freshbooks:invoice:ar:1234?provider=freshbooks" \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -H "X-End-User-Id: user-123" \
  -d '{ "memo": "Approved by ops" }'
```

## Notes

* Pass `type: "ACCOUNTS_PAYABLE"` on `invoice` and `payment` create to dispatch to FreshBooks's `/bills/bills` and `/bill_payments/bill_payments` endpoints. For vendor contacts, set `is_supplier: true`. AR / AP routing is encoded in the URN (`urn:freshbooks:invoice:ar:<id>` vs `urn:freshbooks:invoice:ap:<id>`).
* Canonical `DELETE` translates to a soft delete (`PUT` with `vis_state: 1`) on most resources. `project` is the exception — it uses a true hard `DELETE`.
* Pass canonical `status: "SUBMITTED"` on `invoice` create to land it as Sent (the adapter chains an `action_mark_as_sent` PUT after the initial POST). Omit `status` to leave it as Draft.
* `address` and `phone_number` ids are discoverable inline on `contact.addresses[].id` and `contact.phone_numbers[].id`. Listing them at the top level returns 405 — read them inline from the parent or use `GET /address/{urn}`.