Skip to content
Docs
Finance & accounting

Xero

Let hires look up customers and invoices, see who owes what, draft and send invoices, record payments and keep notes in Xero.

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

With Xero, a hire can:

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

1. Make an app in Xero

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

  1. Sign in at developer.xero.com with your Xero login and open My Apps → New app.
  2. App name: Roster. Integration type: Auth code with PKCE (or Web app if you prefer one with a secret).
  3. Company or application URL: your Roster address.
  4. Redirect URI: the address Roster shows on the Xero connection. It ends in /api/integrations/xero/oauth/callback.
  5. Click Create app, then copy the Client id. For a Web app, also generate and copy a Client secret.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for Xero and choose it.
  2. Paste the OAuth app client ID. Leave the secret empty for a PKCE app; paste it for a Web app.
  3. Organisation: leave it empty if you'll approve one Xero organisation. If you'll approve more than one, put the name of the one hires should use, as Xero shows it.
  4. Click Connect, then Connect with Xero on the new connection.
  5. Xero asks which organisation to allow and what Roster may do. Choose it and click Allow access. Back in Roster, the connection says Connected with Xero.

What hires do in Xero shows as the Xero user who allowed access.

What Roster asks Xero for

PermissionWhy
InvoicesRead invoices; draft, approve, send and note them (only hires allowed to)
PaymentsSee payments; record new ones (only hires allowed to)
Contacts: readFind customers and what they owe
Settings: readFind your bank accounts when recording a payment
Offline accessStay connected without you signing in again

3. Give hires access

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

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

Drafting and sending are separate. A draft stays a draft until someone sends it. Sending a draft approves it first, which is when Xero counts it as owed, then Xero emails it to the customer's email address.

A hire with Read and write can also ask to void an approved invoice that has no payments. That always waits for a person's approval: the hire asks in the thread with the invoice and the reason, and when the approver says yes, Roster voids exactly that invoice, once (more). Nobody can turn that asking off.

A payment goes into a bank account: if you have one, the hire uses it; if you have several, it asks which.

Watching invoices

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

If something goes wrong

  • "Isn't connected yet": press Connect with Xero on the connection.
  • "Several Xero organisations are connected": set the Organisation on the connection.
  • Xero says the redirect URI is invalid: the address in your Xero app must be exactly the one Roster shows.
  • Xero's limits: Xero allows 60 requests a minute and 5,000 a day per organisation. When they're used up, the hire says so and tries again later.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Xero 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 the app you made in the Xero developer portal. A PKCE app has no secret: leave that empty.

Requested scopes:

  • offline_access
  • accounting.invoices
  • accounting.payments
  • accounting.contacts.read
  • accounting.settings.read

Connection fields

Xero connection fields
FieldWhat to provide
OAuth app client ID
clientId
Optional		From the app you made in the Xero developer portal. A PKCE app has no secret: leave that empty.
OAuth app client secret
clientSecret
Optional · sealed secret		Use the value for your account or connection.
Organisation
organisation
Optional		Only if you approved more than one Xero organisation: its name as Xero shows it. Empty: the one you approved.

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

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

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

list_contactsRead only

Customers in Xero with what each owes and how much is overdue, optionally matching words in their name or email, or only those owing.

Approval: Uses your workspace and hire approval settings.

Arguments for list_contacts
ArgumentTypeDetails
searchOptionalstringwords in the name, email or account number
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 name, email or account number",
      "type": "string"
    },
    "owing": {
      "default": "any",
      "type": "string",
      "enum": [
        "any",
        "unpaid",
        "overdue"
      ]
    },
    "limit": {
      "default": 30,
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  }
}
list_invoicesRead only

Sales invoices, newest first, filtered by status (draft, unpaid, overdue, paid, void), customer, invoice date and words in the number or reference.

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 history and notes.

Approval: Uses your workspace and hire approval settings.

Arguments for get_invoice
ArgumentTypeDetails
invoiceRequiredstringthe invoice number, e.g. INV-0012, 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. INV-0012, or its id"
    }
  },
  "required": [
    "invoice"
  ]
}
create_draft_invoiceRead and write

Create a draft sales invoice for a customer. Nothing is sent or approved: it stays a draft 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_dateOptionalstringyyyy-mm-dd; needed before it can be sent, unless the customer has payment terms
referenceOptionalstringa PO or order number
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": "yyyy-mm-dd; needed before it can be sent, unless the customer has payment terms",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "reference": {
      "description": "a PO or order number",
      "type": "string",
      "maxLength": 255
    }
  },
  "required": [
    "customer",
    "lines"
  ]
}
send_invoiceRead and write

Email an invoice to the customer from Xero. A draft is approved first (it then counts as owed). Xero sends it to the contact's email address.

Approval: Uses your workspace and hire approval settings.

Arguments for send_invoice
ArgumentTypeDetails
invoiceRequiredstringthe invoice number, e.g. INV-0012, 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. INV-0012, or its id"
    }
  },
  "required": [
    "invoice"
  ]
}
record_paymentRead and write

Record a payment the customer made against an approved invoice, into a bank account (by code or name; the only bank account if there's one).

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 bank account's code or name in Xero
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 bank account's code or name in Xero",
      "type": "string"
    }
  },
  "required": [
    "invoice",
    "amount"
  ]
}
list_paymentsRead only

Payments received from customers, 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: approved, unpaid 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 note to an invoice's history in Xero, e.g. what the customer said when chased. Only people in Xero see it.

Approval: Uses your workspace and hire approval settings.

Arguments for add_note
ArgumentTypeDetails
invoiceRequiredstringthe invoice number, e.g. INV-0012, 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. INV-0012, or its id"
    },
    "note": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000
    }
  },
  "required": [
    "invoice",
    "note"
  ]
}
void_invoiceRead and writeApproval required · locked

Void an approved invoice in Xero that has no payments: it stays on record but is no longer owed. It always waits for a person's approval: Roster asks in the thread and voids exactly this invoice, once, when they approve.

Approval: Always asks for approval. This requirement cannot be turned off.

Arguments for void_invoice
ArgumentTypeDetails
invoiceRequiredstringthe invoice number, e.g. INV-0012, or its id
reasonRequiredstringwhy, kept in the invoice's history
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. INV-0012, or its id"
    },
    "reason": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "why, kept in the invoice's history"
    }
  },
  "required": [
    "invoice",
    "reason"
  ]
}

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

Wave

Invoices, receipts and small-business accounting in Wave.

Zoho Books

Let hires look up customers and invoices, see who owes what, draft and send invoices, record payments and keep notes in Zoho Books.

On this page

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