Skip to content
Docs
Finance & accounting

QuickBooks Online

Let hires look up customers and invoices, see who owes what, create and send invoices, record payments and keep notes in QuickBooks Online.

Explore 9 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With QuickBooks Online, a hire can:

  • find customers and see what each one owes,
  • list invoices by status (not sent yet, unpaid, overdue, paid, void), customer, date and number,
  • read an invoice with its lines, payments and notes,
  • see who owes what and how late (current, 1–30, 31–60, 61–90 and over 90 days),
  • create an invoice without sending it, send it by email, record a payment, and add a note.

It works with your real company or with an Intuit sandbox company for trying things out.

1. Make an app at Intuit

Roster connects as an app you own, so you choose what it can reach and can disconnect it at any time in QuickBooks.

  1. Sign in at developer.intuit.com and open My Hub → App dashboard. Create an app for QuickBooks Online with the Accounting scope.
  2. Open the app's Settings → Redirect URIs and add the address Roster shows on the QuickBooks connection. It ends in /api/integrations/quickbooks/oauth/callback. For your real company, add it under the production settings.
  3. Copy the Client ID and Client Secret: the development keys for a sandbox, the production keys for your real company. Intuit asks a few questions about your app before it shows production keys.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for QuickBooks and choose it.
  2. Paste the OAuth app client ID and OAuth app client secret.
  3. Environment: Production for your company, Sandbox for a test company.
  4. Click Connect, then Connect with QuickBooks Online on the new connection.
  5. Intuit asks which company to connect. Choose it and click Connect. Back in Roster, the connection says Connected with QuickBooks Online, and Company ID is filled in.

To switch to another company, press Reconnect and choose it.

What Roster asks Intuit for

PermissionWhy
AccountingRead customers, invoices and payments; create and send invoices, record payments and add notes (only hires allowed to)

3. Give hires access

On the hire's Tools tab, click Give access on QuickBooks Online:

  • Read only: it can look up customers, invoices and payments and see who owes what. It can't change anything, create or send.
  • Read and write: it can also create and send invoices, record payments and add notes.

QuickBooks has no draft invoices. When a hire "drafts" an invoice, it creates it without emailing it: the customer sees nothing until someone sends it, but QuickBooks counts it as owed straight away. Creating and sending are still separate, so you can check an invoice before it goes out.

QuickBooks has no comments on invoices either: a hire's note is added, with the date, to the invoice's private note, which customers don't see.

Watching invoices

A hire's responsibility can watch QuickBooks: it's woken when invoices change (paid, sent, edited) or fall overdue, with the list. Checking costs nothing when nothing changed.

If something goes wrong

  • "Doesn't know which company yet": press Connect with QuickBooks Online on the connection.
  • Intuit says the redirect URI is invalid: the address in your Intuit app must be exactly the one Roster shows, under the same environment (development or production) as your keys.
  • Nothing found in a sandbox: make sure Environment is Sandbox and you used the development keys.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect QuickBooks Online and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

OAuth 2.0

From your app in the Intuit developer portal: development keys for a sandbox, production keys for your real company.

Requested scopes:

  • com.intuit.quickbooks.accounting

Connection fields

QuickBooks Online connection fields
FieldWhat to provide
OAuth app client ID
clientId
Optional		From your app in the Intuit developer portal: development keys for a sandbox, production keys for your real company.
OAuth app client secret
clientSecret
Optional · sealed secret		Use the value for your account or connection.
Environment
environment
Optional		Your real company, or an Intuit sandbox company for trying things out.

Choices: Production (your company) (production); Sandbox (for testing) (sandbox).

Starts with: production.

Company ID
realmId
Optional		Filled in when you connect: the QuickBooks company you chose.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

No additional fields.

Actions

9 actions: 5 only read and 4 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

9 of 9 actions. Open an action for its arguments and full input schema.

list_contactsRead only

Customers in QuickBooks with what each owes, optionally matching words in their name, or only those owing or overdue.

Approval: Uses your workspace and hire approval settings.

Arguments for list_contacts
ArgumentTypeDetails
searchOptionalstringwords in the customer's name
owingOptional"any" | "unpaid" | "overdue"See input schema below.Default: "any"
limitOptionalintegerSee input schema below.Default: 30
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "search": {
      "description": "words in the customer's name",
      "type": "string"
    },
    "owing": {
      "default": "any",
      "type": "string",
      "enum": [
        "any",
        "unpaid",
        "overdue"
      ]
    },
    "limit": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  }
}
list_invoicesRead only

Invoices, newest first, filtered by status (draft = not emailed yet, unpaid, overdue, paid, void), customer, invoice date and invoice number.

Approval: Uses your workspace and hire approval settings.

Arguments for list_invoices
ArgumentTypeDetails
statusOptional"any" | "draft" | "unpaid" | "overdue" | "paid" | "void"unpaid: sent and not fully paid; overdue: unpaid and past its due dateDefault: "any"
customerOptionalstringa customer's name or id
fromOptionalstringinvoice date on or after, yyyy-mm-dd
toOptionalstringinvoice date on or before, yyyy-mm-dd
searchOptionalstringwords in the invoice number or reference
limitOptionalintegerSee input schema below.Default: 30
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "status": {
      "default": "any",
      "description": "unpaid: sent and not fully paid; overdue: unpaid and past its due date",
      "type": "string",
      "enum": [
        "any",
        "draft",
        "unpaid",
        "overdue",
        "paid",
        "void"
      ]
    },
    "customer": {
      "description": "a customer's name or id",
      "type": "string"
    },
    "from": {
      "description": "invoice date on or after, yyyy-mm-dd",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "to": {
      "description": "invoice date on or before, yyyy-mm-dd",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "search": {
      "description": "words in the invoice number or reference",
      "type": "string"
    },
    "limit": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  }
}
get_invoiceRead only

One invoice in full: customer, dates, line items, totals, payments received and its notes.

Approval: Uses your workspace and hire approval settings.

Arguments for get_invoice
ArgumentTypeDetails
invoiceRequiredstringthe invoice number, e.g. 1037, or its id
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "invoice": {
      "type": "string",
      "minLength": 1,
      "description": "the invoice number, e.g. 1037, or its id"
    }
  },
  "required": [
    "invoice"
  ]
}
create_draft_invoiceRead and write

Create an invoice for a customer without emailing it. QuickBooks has no drafts: it counts as owed from now, but the customer sees nothing until someone sends it.

Approval: Uses your workspace and hire approval settings.

Arguments for create_draft_invoice
ArgumentTypeDetails
customerRequiredstringthe customer's name or id
linesRequiredobject[]See input schema below.
dateOptionalstringinvoice date, yyyy-mm-dd; default today
due_dateOptionalstringdefault: the customer's terms
messageOptionalstringa message shown to the customer on the invoice
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "customer": {
      "type": "string",
      "minLength": 1,
      "description": "the customer's name or id"
    },
    "lines": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "minLength": 1,
            "description": "what was sold, as it should read on the invoice"
          },
          "quantity": {
            "default": 1,
            "type": "number",
            "exclusiveMinimum": 0
          },
          "rate": {
            "type": "number",
            "minimum": 0,
            "description": "price per unit, before tax"
          },
          "item": {
            "description": "a product or service id or code from the accounting system",
            "type": "string"
          },
          "account": {
            "description": "an income account code, where the system needs one",
            "type": "string"
          }
        },
        "required": [
          "description",
          "rate"
        ]
      }
    },
    "date": {
      "description": "invoice date, yyyy-mm-dd; default today",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "due_date": {
      "description": "default: the customer's terms",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "message": {
      "description": "a message shown to the customer on the invoice",
      "type": "string",
      "maxLength": 1000
    }
  },
  "required": [
    "customer",
    "lines"
  ]
}
send_invoiceRead and write

Email an invoice to the customer from QuickBooks, to its billing email or to an address given (which then becomes its billing email).

Approval: Uses your workspace and hire approval settings.

Arguments for send_invoice
ArgumentTypeDetails
invoiceRequiredstringthe invoice number, e.g. 1037, or its id
toOptionalstringdefault: the invoice's billing email
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "invoice": {
      "type": "string",
      "minLength": 1,
      "description": "the invoice number, e.g. 1037, or its id"
    },
    "to": {
      "description": "default: the invoice's billing email",
      "type": "string",
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    }
  },
  "required": [
    "invoice"
  ]
}
record_paymentRead and write

Record a payment the customer made against an invoice (into Undeposited Funds unless an account is given).

Approval: Uses your workspace and hire approval settings.

Arguments for record_payment
ArgumentTypeDetails
invoiceRequiredstringthe invoice number or id
amountRequirednumberSee input schema below.
dateOptionalstringwhen it was paid; default today
referenceOptionalstringthe bank or cheque reference
accountOptionalstringthe id of the account it was deposited to
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "invoice": {
      "type": "string",
      "minLength": 1,
      "description": "the invoice number or id"
    },
    "amount": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "date": {
      "description": "when it was paid; default today",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "reference": {
      "description": "the bank or cheque reference",
      "type": "string",
      "maxLength": 100
    },
    "account": {
      "description": "the id of the account it was deposited to",
      "type": "string",
      "pattern": "^\\d+$"
    }
  },
  "required": [
    "invoice",
    "amount"
  ]
}
list_paymentsRead only

Payments received, newest first, optionally from one customer.

Approval: Uses your workspace and hire approval settings.

Arguments for list_payments
ArgumentTypeDetails
customerOptionalstringa customer's name or id
limitOptionalintegerSee input schema below.Default: 30
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "customer": {
      "description": "a customer's name or id",
      "type": "string"
    },
    "limit": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  }
}
receivables_summaryRead only

Who owes what and how late: open invoices totalled by age (current, 1-30, 31-60, 61-90, over 90 days) and the customers most overdue.

Approval: Uses your workspace and hire approval settings.

This action takes no arguments.

Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}
add_noteRead and write

Add a dated line to an invoice's private note in QuickBooks (it has no comments), e.g. what the customer said when chased. Customers don't see it.

Approval: Uses your workspace and hire approval settings.

Arguments for add_note
ArgumentTypeDetails
invoiceRequiredstringthe invoice number, e.g. 1037, or its id
noteRequiredstringSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "invoice": {
      "type": "string",
      "minLength": 1,
      "description": "the invoice number, e.g. 1037, or its id"
    },
    "note": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000
    }
  },
  "required": [
    "invoice",
    "note"
  ]
}

Watches and incoming events

  • This integration supports a responsibility that watches for changes. The guide above explains what it checks and how to limit it.
  • No incoming webhook handler is declared for this integration.

Limits and troubleshooting

  • Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
  • Expired or revoked access: reconnect or replace the key on the connection.
  • Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
  • The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

Oracle NetSuite

Financials, orders, inventory and records in NetSuite.

Sage Accounting

Invoices, VAT returns and bank reconciliation in Sage Accounting.

On this page

1. Make an app at Intuit2. Connect it in RosterWhat Roster asks Intuit for3. Give hires accessIf something goes wrongTools and permissions reference