> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/freshbooks.md).

# FreshBooks

Connect to FreshBooks for invoicing and accounting workflows.

### Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector  | Authentication |
| ---------- | -------------- |
| FreshBooks | OAuth sign-in  |

#### FreshBooks

Connect to FreshBooks to manage invoices, expenses, clients, and estimates.

**Set up in FreshBooks**

1. Use a FreshBooks account with access to the records and operations that your workflow needs.
2. Register or select the OAuth application described in the fields below. Add the redirect URI displayed in StackAI to that application and retain its client ID and secret, where required.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **FreshBooks**.
2. Complete the connector configuration below. If you do not have access to these settings, ask your StackAI administrator to configure the connector.
3. Select **Connect**, sign in to the provider account, and review the requested access. Complete authorization to return to StackAI.
4. Complete the fields marked for use after sign-in, such as the business or account selection.
5. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connector configuration**

| StackAI field | Required  | What to enter                                                                                                                                |
| ------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| OAuth Scopes  | Read-only | Permissions required for the selected FreshBooks accounting operations. This value is shown for reference; it is not an editable credential. |
| Client ID     | Yes       | Client ID from your FreshBooks developer application. [Provider instructions](https://my.freshbooks.com/#/developer).                        |
| Client Secret | Yes       | Client secret from your FreshBooks developer application. Keep it confidential.                                                              |
| Redirect URI  | Read-only | Use this redirect URI when configuring your OAuth application. This value is shown for reference; it is not an editable credential.          |

**Connection fields**

| StackAI field       | Required                 | What to enter                                                                         |
| ------------------- | ------------------------ | ------------------------------------------------------------------------------------- |
| FreshBooks Business | Optional / as applicable | Choose an active FreshBooks business after authorizing. Select this after signing in. |

#### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

### Use an action

1. Add the required **FreshBooks** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

### Actions

#### Create Invoice

Create a draft invoice with one or more line items in FreshBooks.

**Inputs**

| Field         | Type            | Required | Description                                                                 |
| ------------- | --------------- | -------- | --------------------------------------------------------------------------- |
| Customer ID   | select (string) | Yes      | FreshBooks client ID to invoice. Options load from the selected connection. |
| Invoice lines | array           | Yes      | One or more repeated invoice line items.                                    |
| Currency code | string          | Yes      | Three-letter invoice currency code.                                         |
| Issue date    | string          | No       | Date shown on the invoice. Defaults to today when left blank.               |
| Notes         | textarea        | No       | Optional invoice notes.                                                     |

**Outputs**

| Field          | Type   | Description                              |
| -------------- | ------ | ---------------------------------------- |
| Invoice ID     | string | FreshBooks ID for the new draft invoice. |
| Invoice number | string | Invoice number assigned by FreshBooks.   |
| Status         | string | Display status of the created invoice.   |
| Currency code  | string | Currency stored on the invoice.          |

#### Create Estimate

Create a draft FreshBooks estimate with line items.

**Inputs**

| Field                | Type            | Required | Description                                                                             |
| -------------------- | --------------- | -------- | --------------------------------------------------------------------------------------- |
| Customer ID          | select (string) | Yes      | FreshBooks client receiving the estimate. Options load from the selected connection.    |
| Estimate lines       | array           | Yes      | One or more normal estimate line items.                                                 |
| Currency             | string          | Yes      | Three-letter estimate currency code.                                                    |
| Show advanced fields | boolean         | No       | Reveal issue date, recipient, PO, language, discount, notes, and terms. Default: false. |
| Issue date           | string          | No       | Date shown on the estimate. Defaults to today when left blank.                          |
| Recipient email      | string          | No       | Email associated with the estimate recipient.                                           |
| PO number            | string          | No       | Purchase order number for the estimate.                                                 |
| Language             | string          | No       | Language used for the estimate.                                                         |
| Discount value       | number          | No       | Non-negative discount value applied by FreshBooks.                                      |
| Notes                | textarea        | No       | Notes displayed on the estimate.                                                        |
| Terms                | textarea        | No       | Terms displayed on the estimate.                                                        |

**Outputs**

| Field           | Type   | Description                               |
| --------------- | ------ | ----------------------------------------- |
| Estimate ID     | string | FreshBooks ID for the new draft estimate. |
| Estimate number | string | Estimate number assigned by FreshBooks.   |
| Status          | string | Display status of the created estimate.   |
| Currency        | string | Currency code of the created estimate.    |
| Issue date      | string | Issue date of the created estimate.       |

#### List Clients

Find FreshBooks clients to invoice.

**Inputs**

| Field          | Type    | Required | Description                                      |
| -------------- | ------- | -------- | ------------------------------------------------ |
| Search clients | string  | No       | Optional client name search.                     |
| Limit          | integer | No       | Target number of clients to return. Default: 25. |
| Cursor         | integer | No       | Continue from this result offset.                |

**Outputs**

| Field       | Type          | Description                  |
| ----------- | ------------- | ---------------------------- |
| Clients     | object\_array | Clients matching the search. |
| Next cursor | integer       | Offset for the next page.    |

#### Create Expense

Create a FreshBooks expense.

**Inputs**

| Field            | Type            | Required | Description                                                                                  |
| ---------------- | --------------- | -------- | -------------------------------------------------------------------------------------------- |
| Amount           | number          | Yes      | Expense amount.                                                                              |
| Expense category | select (string) | Yes      | FreshBooks expense category. Options load from the selected connection.                      |
| Expense date     | string          | Yes      | Date the expense occurred.                                                                   |
| Staff ID         | select (string) | Yes      | FreshBooks staff member who incurred the expense. Options load from the selected connection. |
| Currency         | string          | Yes      | Three-letter currency code.                                                                  |
| Vendor           | string          | No       | Optional vendor.                                                                             |
| Notes            | textarea        | No       | Optional notes.                                                                              |

**Outputs**

| Field      | Type   | Description                    |
| ---------- | ------ | ------------------------------ |
| Expense ID | string | Created FreshBooks expense ID. |

#### Create Client

Create a client in FreshBooks.

**Inputs**

| Field                | Type     | Required | Description                                                                  |
| -------------------- | -------- | -------- | ---------------------------------------------------------------------------- |
| First name           | string   | No       | Client's first name.                                                         |
| Last name            | string   | No       | Client's last name.                                                          |
| Organization         | string   | No       | Client organization.                                                         |
| Email                | string   | No       | Client email address.                                                        |
| Show advanced fields | boolean  | No       | Reveal currency, language, billing address, and note fields. Default: false. |
| Currency             | string   | No       | Preferred three-letter currency code.                                        |
| Language             | string   | No       | Preferred client language.                                                   |
| Billing street       | string   | No       | First billing-address line.                                                  |
| Billing street 2     | string   | No       | Second billing-address line.                                                 |
| Billing city         | string   | No       | Billing city.                                                                |
| Billing province     | string   | No       | Billing state or province.                                                   |
| Billing postal code  | string   | No       | Billing postal or ZIP code.                                                  |
| Billing country      | string   | No       | Billing country.                                                             |
| Note                 | textarea | No       | Internal note about the client.                                              |

**Outputs**

| Field        | Type   | Description                             |
| ------------ | ------ | --------------------------------------- |
| Client ID    | string | Created FreshBooks client ID.           |
| Name         | string | Created client display name.            |
| Organization | string | Created client's organization.          |
| Email        | string | Created client's email address.         |
| Currency     | string | Created client's default currency code. |

#### List Expense Categories

List FreshBooks expense categories.

**Inputs**

| Field  | Type    | Required | Description                                         |
| ------ | ------- | -------- | --------------------------------------------------- |
| Limit  | integer | No       | Target number of categories to return. Default: 25. |
| Cursor | integer | No       | Offset returned by an earlier call.                 |

**Outputs**

| Field       | Type          | Description                    |
| ----------- | ------------- | ------------------------------ |
| Categories  | object\_array | FreshBooks expense categories. |
| Next cursor | integer       | Offset for the next page.      |

#### List Staff

List FreshBooks staff members.

**Inputs**

| Field  | Type    | Required | Description                                            |
| ------ | ------- | -------- | ------------------------------------------------------ |
| Limit  | integer | No       | Target number of staff members to return. Default: 25. |
| Cursor | integer | No       | Offset returned by an earlier call.                    |

**Outputs**

| Field       | Type          | Description               |
| ----------- | ------------- | ------------------------- |
| Staff       | object\_array | FreshBooks staff members. |
| Next cursor | integer       | Offset for the next page. |

#### List Payments

List and filter FreshBooks invoice payments.

**Inputs**

| Field                 | Type            | Required | Description                                                                                 |
| --------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------- |
| Client                | select (string) | No       | Only return payments from one FreshBooks client. Options load from the selected connection. |
| Show advanced filters | boolean         | No       | Reveal invoice, date, amount, currency, type, and credit filters. Default: false.           |
| Invoice ID            | string          | No       | Only return payments for one invoice.                                                       |
| Paid on or after      | string          | No       | Include payments on or after this date.                                                     |
| Paid before           | string          | No       | Include payments strictly before this date.                                                 |
| Minimum amount        | number          | No       | Include payments at or above this amount.                                                   |
| Amount below          | number          | No       | Include payments strictly below this amount.                                                |
| Currency              | string          | No       | Only return payments in this currency.                                                      |
| Payment type          | string          | No       | Only return payments with this exact type.                                                  |
| Converted from credit | boolean         | No       | Filter by whether a payment was converted from client credit.                               |
| Limit                 | integer         | No       | Target number of payments to return. Default: 25.                                           |
| Cursor                | integer         | No       | Continue from this payment offset.                                                          |

**Outputs**

| Field       | Type          | Description                                              |
| ----------- | ------------- | -------------------------------------------------------- |
| Payments    | object\_array | Payments matching the selected filters.                  |
| Next cursor | integer       | Offset for the next payment page, if more results exist. |

### Important behavior

If an operation is denied, check the connection’s granted permissions and the account’s access in the provider. Reauthorize the connection when it needs additional permissions.

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/freshbooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
