Xero in Agent Builder

The Xero step lets an agent read and change records in one Xero organisation as part of a run. It can list overdue sales invoices, raise a draft invoice when a job is finished, email an approved invoice, record a payment, or download an invoice PDF for a later email step. Each step does one thing, picked from 54 actions, and hands what Xero sends back to the next step. A download hands on the file, so a later Outlook step can attach it.

app.centrus.ai/app/agents/workflow-builder

Agents

Build modular AI workflows with reusable nodes

Invoice when a job finishes

1,240 / 10,000 creditsValidateResetRunsSettingsUpdate & Publish

Job finished

Job status changed

Read the job

Get job

Raise the invoice

Create invoice

2

Email accounts

1 action enabled

AI builderMap

1. 1Xero in the Integration group of the Nodes panel.
2. 2The step on the canvas. Its summary shows the action, Create invoice.
3. 3Connection: the Xero sign-in this agent uses, shown by the email address that signed in.
4. 4Endpoint: the action the step performs, chosen from the full list.
5. 5The action's fields. The contact id is Northgate Housing in Xero. The job reference comes from the BigChange step, and the invoice stays a draft.

Centrus works alongside Xero. Invoices, bills, contacts and payments stay in Xero, and the agent reads and updates them there. A sales invoice is what the action lines call ACCREC, and a supplier bill is ACCPAY. The step does not listen for changes in Xero. To start a run you use a schedule, an email, or an alert from another system such as BigChange. To ask about the same records in a conversation, see Xero in chat. Connecting chat does not connect this step.

Open the agent in Agent Builder and find Xero in the Integration group of the Nodes panel, under Sage Intacct. Drag it onto the canvas and connect the step before it to its left-hand side. Until you choose an action, its summary on the canvas reads No endpoint selected.

Read the job

Get job

Xero

No endpoint selected

2

1. 1Xero in the Integration group. Drag it onto the canvas.
2. 2The new step. It reads No endpoint selected until you choose an action in its Details panel.

On a phone, Agent Builder shows the canvas only. The Nodes panel is hidden on screens narrower than 768 pixels and the Details panel on screens narrower than 1,024 pixels, so you can follow an agent's steps on a phone but need a tablet or computer to add a Xero step or change its settings.

09:41

Centrus

Agents

Build modular AI workflows with reusable nodes

Chase overdue invoices

Save and Publish

Job finished

Job status changed

Read the job

Get job

Raise the invoice

Create invoice

Email accounts

1 action enabled

The Xero connection belongs to this agent alone. It is separate from the organisation's Xero connection in chat, so connecting one does not connect the other. One connection covers every Xero step in the agent, so you only sign in once per agent. There is one organisation per agent, and no list of extra Xero accounts on the step.

You do not paste a key. Connect opens Xero's own sign-in page. Sign in as a Xero user who can see the organisation the agent should use, and allow access. You need that user's Xero login, not an API key from Xero's developer site. If you cannot sign in, ask the person who administers Xero at your organisation.

1. 1Save the agent with Save draft. Until it has been saved once, the Connection section reads Save this workflow as a draft first, then connect the account. and Connect is greyed out.
2. 2Select the Xero step. In the Details panel, open Connection and click Connect.
3. 3On Xero's sign-in page, enter the email and password and log in. Allow Centrus access when Xero asks.
4. 4If that login can see only one organisation, you return to the agent and a message reads Xero connected for this agent. Connection then reads Connected, followed by the email address that signed in.
5. 5If that login can see more than one organisation, a message reads Select a Xero organisation on the Xero node to finish connecting. The Select a Xero organisation window lists them. Choose one and click Continue. A message then reads Xero organisation selected.

login.xero.com

Log in to Xero

Email

Email

Password

Password

2

Log in3

1

Select a Xero organisation

4

This Xero login can access more than one organisation. Choose which one this agent should use.

Meridian FM5

Meridian FM

Meridian Property Services

Continue

1. 1Xero's sign-in page, which Connect opens. It is not a credentials form in Centrus.
2. 2The email and password for the Xero user.
3. 3Log in. After this, Xero asks you to allow access, then sends you back to the agent.
4. 4Select a Xero organisation. This window appears only when the login can see more than one organisation.
5. 5The organisation this agent will use. Continue saves that choice.

A login that can see only one organisation connects as soon as you return. You do not see the organisation window. Try a dry run straight after connecting, as described under Test before it goes live, so you know the organisation is the one you expected.

Another agent. Xero does not offer Copy from existing agent. Signing in on this agent does not reuse the sign-in from an agent you built earlier, and it does not reuse the chat connection. Each agent has its own sign-in and its own organisation.

Sharing and copying the agent. When you share an agent, its Xero connection stays with it, and everyone who runs it uses that connection rather than their own chat connection. When you duplicate an agent, the steps are copied but the connection is not, so sign in to Xero again on the copy. For the details, see Share an agent.

Disconnecting. Disconnect removes the sign-in from this agent only, and also removes that connection inside Xero. Its Xero steps stop working until someone connects it again. Other agents keep their own sign-ins, and the organisation's Xero connection in chat is left as it is. How chat connects is covered in Xero in chat and Integrations overview.

Select the step and open Endpoint in the Details panel. The section's own line reads Choose the Xero action this node should call (invoices, bills, contacts, quotes, purchase orders, repeating templates). Endpoint tool type holds all 54 actions in one list that starts with List invoices. The list has no search box and no headings, so the tables at the end of this guide are the quickest way to find the exact name you need.

Keep Set endpoint fields here. Let AI populate endpoint fields hides the fields so that an AI can fill them, but on a step in the agent's main flow nothing fills them in when the step runs. To have an AI choose the values, attach the step to an AI step as a tool instead, as described below.

Each action then shows its own fields in a box titled with the action's name. A required field has an asterisk. The title on a field is not always the Xero name. Where the field has a help line, the title is the first sentence of that line, so Status on Create invoice is titled DRAFT (default) or AUTHORISED. Where there is no help line, the name is split at each capital letter, so ContactID is shown as Contact I D and InvoiceID as Invoice I D. The same words appear again as the empty field's hint.

To use a value from an earlier step, open Step data references at the top of the Details panel and click a field to copy its reference, then paste it into a text field. In the overview agent, Reference holds the job reference from Read the job, so the draft can be matched back to J-10482, the boiler service at Riverside House for Northgate Housing. Contact I D holds that customer's contact id in Xero. A BigChange contact id is not a Xero contact id, so look the contact up with List contacts or Get Contact and paste the id Xero returns. Amount and Currency rate on Record payment are number fields, so a reference pasted into them is turned into a number and lost. Use a fixed number there, or attach the step to an AI step as a tool.

Create invoice leaves the invoice as a draft unless you set the status field to AUTHORISED. A draft is the safer default: someone can check it in Xero before it is approved. Email invoice only sends an invoice that is already AUTHORISED, and the email goes out as the Xero user who signed this agent in. Line items is one text box, not a row for each line. For an invoice with several lines, attach the step to an Intelligence step so the AI fills the lines on the call.

What the step passes on. A single read or write passes on one item. A list action passes on one item per record, so six overdue invoices become six items, and the step's summary reads Found 6 invoices. Later steps reach their fields through Step data references, and an AI step reads all of the items together. Get invoice PDF passes on the file. If its invoice id field is empty, it uses the invoice id on the item it received, which is what you want inside a Loop. To download or email one record per item, put the step inside a Loop, described in Conditions, loops and approvals.

As a tool for an AI step. Connect a Xero step to the Tools side of an Intelligence step and its Details panel changes. Instead of one endpoint, Actions lets you choose several, with a search box, and the AI decides when to call each one and fills in the fields itself. The step's summary on the canvas lists up to three actions, then shows the first one and a count if there are more.

Job finished

Job status changed

Decide the invoice

Invoices and drafts

List invoices, Get invoice, Create invoice

1

1. 1The Xero step attached to the Intelligence step as a tool.
2. 2Actions: the Xero actions the AI may call.
3. 3Pause for approval: each call the AI makes waits for someone to approve it in the Runs panel.

Pause for approval appears on every Xero step but only applies to calls an AI makes, so it has no effect on a step in the main flow. To ask someone before a main-flow step changes Xero, put an Approval step in front of it. Do not give an Intelligence step a wide list such as every invoice in the organisation. The whole list would be loaded into the AI. Use the Ingest step for those, as described under Limits and good to know.

Xero has no trigger of its own. Nothing in Xero, such as a new invoice or a payment, starts the agent by itself. You start the run from somewhere else and then use the Xero step. Two patterns cover most agents. A Schedule trigger runs it at a time you choose, for example 08:00 every Monday to chase overdue invoices. An alert from another system, such as the BigChange webhook, runs it when a job changes, and the Xero step raises the invoice. Setting up schedules is covered in Choose how an agent starts. Setting up another system's alert is covered in Start an agent from a system alert.

Job finished

Job status changed

Raise the invoice

Create invoice

1. 1Connection on the BigChange webhook. This is the BigChange REST connection, not Xero. Xero has no trigger of its own.
2. 2Event types: the events that start a run. Only Job status changed is ticked.
3. 3Set this up in BigChange: the steps to follow in BigChange and the address to paste there.
4. 4Simulate webhook: runs the agent once with a sample alert. A Xero write in the steps after it still changes Xero.

What the Xero step should read from the alert. The BigChange trigger hands on data.entityId, the id of the job that changed. The usual pattern is a BigChange REST Get job in between, with Job ID or reference set to {{ trigger.json.data.entityId }}, and then the Xero Create invoice step using the job's contact and reference. The webhook uses the agent's BigChange REST connection, so an agent that raises a Xero invoice from a finished job needs both connections. The events, the status filter and what each alert contains are in BigChange REST in Agent Builder.

A supplier invoice that arrives by email is the same idea with a different start. Email received can pass the message to a Xero Create Bill step. That trigger is covered in Start an agent when an email arrives. A simulated BigChange alert is a real run: Create invoice and Record payment do change Xero, and the run uses credits. Alerts and schedules only start runs once the agent is published. Simulate webhook and Run now work on drafts.

Job finished

Job status changed

Read the job

Get job

Raise the invoice

Create invoice

Email accounts

1 action enabled

Invoice when a job finishes raises a draft sales invoice when a visit is completed. Job finished is a BigChange webhook with Job status changed ticked, and the status filter in BigChange set to the completed statuses. Read the job uses Get job with {{ trigger.json.data.entityId }}, so the agent has the job reference, for example J-10482 for a boiler service at Riverside House for Northgate Housing, with Dylan Hughes as the engineer. Raise the invoice uses Create invoice, with that reference in Reference, Northgate Housing's Xero contact id in the contact field, and the status left as DRAFT. Email accounts tells Sarah Price in accounts that the draft is waiting in Xero. It does not send the invoice to the customer. Each finished job costs four credits.

Monday at 08:00

Weekly · Mon at 08:00

Overdue invoices

List invoices · outstanding

Write the chase list

Email accounts

1 action enabled

Monday overdue chase emails accounts a list of unpaid sales invoices at 08:00 every Monday. Overdue invoices uses List invoices with the outstanding box ticked and the date field set to DueDate, so Xero returns authorised invoices that still have an amount due. Write the chase list reads them together and groups them by contact, and Email accounts sends the result to accounts@meridianfm.co.uk. The list costs 1 credit however many invoices it returns, up to the page of 100 described under Limits and good to know.

Monday at 08:00

Weekly · Mon at 08:00

Overdue invoices

List invoices · outstanding

Each invoice

Batch size 1

Download the PDF

Get invoice PDF

Email accounts

1 action enabled

Overdue invoice PDFs sends the same Monday list as PDF files. Download the PDF sits inside a Loop so it runs once per invoice. Leave the invoice id field empty: the step uses the invoice id on the current item, and the file name comes back as invoice, then that id, then .pdf. Email accounts attaches the PDFs. The list costs 1 credit. Each PDF costs another credit, so twelve invoices cost twelve credits for that step.

A dry run is the safe way to try a Xero step. Open Runs in the toolbar, click Run now and choose Dry run (no actions performed). Read actions such as List invoices, Get invoice and Get invoice PDF call Xero for real, so you see real rows and real files. Write actions, such as Create invoice, Email invoice and Record payment, are skipped, and the step's summary starts with DRY RUN and says what it would have done, so nothing in Xero changes. Run for real performs every action, including the writes.

{
  "handles": { "main": 6 },
  "items": {
    "main": [
      {
        "InvoiceNumber": "INV-10482",
        "Status": "AUTHORISED",
        "AmountDue": 1860,
        "DueDate": "2026-09-28",
        "Reference": "J-10482",
        "Contact": { "Name": "Northgate Housing" }
      }
    ]
  }
}

Open a step in the run to see its output. A download's summary is Downloaded followed by the file name. The panel shows the first 50 items of each output, and later steps still receive all of them. A dry run costs 1 credit for the whole run. A simulated BigChange alert is not a dry run, so test write actions with Run now first. For Run now, dry runs and the Runs panel in full, see Test an agent before it goes live.

A Xero step costs 1 automation credit each time it runs successfully, whatever the action and however large the PDF. A step that fails costs nothing. When the step is a tool, each call the AI makes costs 1 credit. Xero has no trigger. A run started by a schedule or by a BigChange webhook still costs 1 credit for the run, like any other run, and those triggers themselves are free.

Inside a Loop, the step is charged on every pass, so a Loop over 40 invoices that downloads each PDF costs 40 credits for that step. A single list action is usually cheaper than fetching records one at a time, but a PDF still has to be downloaded one at a time. For allowances, limits and how to see what each run cost, see Automation credits and usage limits.

• 100 rows per list. A list step asks Xero for one page of up to 100 rows. The step has no field for a further page. For a longer set, use the Ingest step, described under Large lists.
• Dates are year first. Record payment requires Date as 2026-10-09. The same shape works in Date and Due Date on Create invoice. On List invoices, leave the date boxes empty and use the outstanding box when you want unpaid invoices. The date field's title is Default Date. Type DueDate in it to filter by due date. Date window takes a short code such as this_week, last_30_days, last_month or this_year. The canvas summary then reads List invoices, then that code, or List invoices · outstanding when only the outstanding box is ticked.
• Drafts, approval and email. Create invoice and Create Bill save a draft unless you set the status to AUTHORISED. Email invoice sends only an AUTHORISED invoice, as the Xero user who connected the agent. Delete Repeating Invoice removes the template. There is no undo from Centrus. There is no action that voids or deletes a sales invoice, a bill, a quote, a purchase order or a contact.
• 20 MB per PDF, about 8 MB per read. A PDF larger than 20 MB fails. The message states the limit in bytes (20,971,520) and the size Xero returned. A single read that returns more than about 8 MB also fails. Narrow the filters or use Ingest. A call is given 60 seconds.
• Credit notes and cash. Credit notes, bank transactions, overpayments and prepayments can be listed and opened. They cannot be created from this step. Record payment needs an invoice id, an account code or account id from List accounts, an amount greater than 0, and a date.
• Per-user integration mode. The Connection section says the step still uses the agent's own connection, because Xero has no per-user credentials. In that mode the step fails when it runs, with a message saying the action is not supported. Keep agents that use Xero on the agent's own connection.
• Two connections for a job invoice. An agent that starts from a BigChange alert needs BigChange REST for the webhook and for Get job, and Xero for the invoice. Connecting one does not connect the other. Chat's Xero connection is a third, separate sign-in.

• Xero is not connected to this agent. Open the step's Connection section and click Connect. If you have duplicated the agent, the copy needs its own sign-in. A Xero connection in chat, or a BigChange connection on the same agent, does not count.
• Xero is not connected to this agent. Please reconnect. Centrus cannot refresh the saved sign-in. Disconnect, then connect again.
• Select a Xero organisation before using this integration. The sign-in can see more than one organisation and none was chosen. Open the Xero step and complete Select a Xero organisation, then Continue.
• You return to the agents list and nothing is connected. Xero did not accept the sign-in, or the login authorised no organisation. The message during connect is No Xero organisations were authorised for this login. Sign in again with a user who can open the right organisation.
• That Xero organisation is not available on this connection. The organisation you chose is not on this sign-in. Connect again and pick one from the list Xero returns.
• Xero 401, or Xero followed by another number. Xero refused the call. Reconnect the step. If the number is 400, read the rest of the message: it is Xero's own reason, often a missing contact, a bad date, or a status Xero will not accept.
• InvoiceID is required. Get invoice, Email invoice and the PDF actions need an invoice id. Inside a Loop, Get invoice PDF can take it from the current item when the field is empty. The other actions cannot.
• AccountCode or AccountID is required. Amount must be greater than 0. Date must be YYYY-MM-DD. These three come from Record payment. Use an account from List accounts, an amount above zero, and a date written year first.
• No action selected. The step has no action yet. Choose one under Endpoint tool type.
• A field will not take a reference. Amount and Currency rate are number fields. Use a fixed number, or let an AI fill them by using the step as a tool. Text fields such as Contact I D, Invoice I D and Reference can hold a reference.
• The invoice is created but the customer never receives it. Create invoice saves a draft and does not email anyone. Email invoice only sends an AUTHORISED invoice. Approve it first, or set the status to AUTHORISED on create, then add Email invoice.
• A list stops at 100 invoices. That is one page. Use Ingest for more, or narrow the outstanding box and the dates.
• An alert never starts the agent. Xero does not listen for alerts. Check the schedule, or the BigChange webhook on the same agent: the agent must be published, the event type ticked, and the webhook added in BigChange. See BigChange REST in Agent Builder.

The Xero step offers 54 actions: 40 read from Xero and 14 change it. Every call goes to https://api.xero.com/api.xro/2.0. A PDF is a GET of the same record, returned as a file. Creating a sales invoice, bill, quote, purchase order, contact, repeating invoice or payment uses PUT. Updating a record, emailing an invoice, and deleting a repeating invoice use POST. Bills use the invoices path. The action lines call a sales invoice ACCREC and a bill ACCPAY.