younifyd
Menu

Connectors

Xero

Work with the Xero Accounting API — accounts, bank transactions, contacts, credit notes, invoices, items, and payments. Covers OAuth auth, the required xero-tenant-id field, Xero's PUT/POST verbs, and the plural-key response envelope.

On this page

Connecting Xero

Every action needs a Xero connection configured with OAuth 2.0 (authorization-code) credentials and the accounting.transactions, accounting.contacts, and accounting.settings scopes (read or read-write as needed). The access token is sent as a Bearer token automatically. Requests go to https://api.xero.com/api.xro/2.0.

The xero-tenant-id header

Xero requires an xero-tenant-id header on every request to say which connected organisation to act on. It's a required field on every action — set it to your organisation's tenant id (from Xero's GET /connections endpoint, or the Xero app's tenant list). Without it, requests fail with 403.

How Xero actions are structured

Each action is one operation of the Xero Accounting API. They all appear under a single Xero group in the picker (plus a Generic Request group). Names read like "Get Invoices" (list), "Create Invoices" (PUT), "Update Or Create Invoices" (POST), "Get Invoice" (one), "Update Invoice", "Delete Account".

Xero's REST verbs are unusual:

  • GET /<Resource> — list, with optional filtering.
  • PUT /<Resource> — create one or more records.
  • POST /<Resource> — create-or-update one or more records (upsert): include a record's id to update it, omit it to create.
  • GET /<Resource>/{id}, POST /<Resource>/{id}, DELETE /<Resource>/{id} — operate on one record by id (each takes an <Resource>ID field, e.g. InvoiceID, AccountID).

Common fields on every action: xero-tenant-id (required, above), the resource id for by-id actions, a Request Body structured field plus Override Request Body / Request Body (Raw), Additional Headers, Additional Query Parameters, Forward All Headers.

Filtering and paging

Xero's filter/sort/page controls (where, order, page, Statuses, IDs, If-Modified-Since, summarizeErrors, unitdp) are declared as shared $ref parameters. They now resolve to real fields where the spec attaches them; where one isn't offered as a field, add it via Additional Query Parameters (or Additional Headers for If-Modified-Since). Examples: where Status=="AUTHORISED", order Date DESC, page 1.

Reading the response

Every action's result is at {{<stepReference>.response...}} (see Step Reference): {{<stepReference>.response.status}}, {{<stepReference>.response.statusText}}, {{<stepReference>.response.headers.<name>}}, and {{<stepReference>.response.data.<field>}} for the body.

Xero wraps everything — even a single record — in a plural key named after the resource, alongside Id, Status, ProviderName, DateTimeUTC:

  • A list or single-record read: {{<stepReference>.response.data.Invoices}} is the array (e.g. {{<stepReference>.response.data.Invoices[0].InvoiceID}}, {{<stepReference>.response.data.Invoices[0].Total}}, {{<stepReference>.response.data.Invoices[0].AmountDue}}).
  • A create/update: the same shape, with the created/updated records in the plural array and their new GUIDs (InvoiceID, ContactID, AccountID, …).
  • Validation problems come back as 200 with per-record ValidationErrors — check {{<stepReference>.response.data.Invoices[0].ValidationErrors}}, not just the HTTP status. Set Additional Query Parameters summarizeErrors = false to get every record's errors rather than a single top-level failure.
  • Paged list responses also carry {{<stepReference>.response.data.pagination.pageCount}} / .itemCount when the page query parameter is used.

A non-2xx response does not fail the step — it's returned with the real status code and Xero's error body ({{<stepReference>.response.data.Message}}, {{<stepReference>.response.data.Elements}}) under data.

Accounts

The chart of accounts.

  • Get Accounts — GET /Accounts. {{<stepReference>.response.data.Accounts}} — each has AccountID, Code, Name, Type, Status, TaxType.
  • Create Account — PUT /Accounts. Body: { "Accounts": [ { "Code": "200", "Name": "Sales", "Type": "REVENUE" } ] } (Xero's Account object).
  • Get Account / Update Account / Delete Account — GET / POST / DELETE /Accounts/{AccountID}, each with an AccountID field.

Bank Transactions

Spent and received money not tied to an invoice.

  • Get Bank Transactions — GET /BankTransactions.
  • Create Bank Transactions — PUT /BankTransactions.
  • Update Or Create Bank Transactions — POST /BankTransactions (include BankTransactionID in the body to update).
  • Get Bank Transaction / Update Bank Transaction — GET / POST /BankTransactions/{BankTransactionID}.

Key fields: Type (SPEND / RECEIVE), Contact, BankAccount ({ "AccountID": "<id>" }), LineItems, Date, Reference.

Contacts

Customers and suppliers.

  • Get Contacts — GET /Contacts. Filter via Additional Query Parameters where = Name.Contains("Acme") or EmailAddress == "ap@acme.example".
  • Create Contacts — PUT /Contacts. Body: { "Contacts": [ { "Name": "Acme Ltd", "EmailAddress": "ap@acme.example" } ] }.
  • Update Or Create Contacts — POST /Contacts (include ContactID in the body to update).
  • Get Contact / Update Contact — GET / POST /Contacts/{ContactID}, each with a ContactID field.
  • Get Contact By Contact Number — GET /Contacts/{ContactNumber}, with a ContactNumber field.
  • Get Contact CISSettings — GET /Contacts/{ContactID}/CISSettings (UK construction-scheme settings).

Credit Notes

  • Get Credit Notes / Create Credit Notes (PUT) / Update Or Create Credit Notes (POST) — on /CreditNotes.
  • Get Credit Note / Update Credit Note — GET / POST /CreditNotes/{CreditNoteID}.
  • Get Credit Note As Pdf — GET /CreditNotes/{CreditNoteID}/pdf — the response body is the raw PDF; read it from {{<stepReference>.response.data}}.
  • Create Credit Note Allocation — PUT /CreditNotes/{CreditNoteID}/Allocations. Body: { "Allocations": [ { "Invoice": { "InvoiceID": "<id>" }, "Amount": 50.00 } ] }.
  • Delete Credit Note Allocations — DELETE /CreditNotes/{CreditNoteID}/Allocations/{AllocationID}.

Invoices

Sales invoices (Type ACCREC) and purchase bills (Type ACCPAY).

  • Get Invoices — GET /Invoices. Filter via Additional Query Parameters where = Status == "AUTHORISED" or Contact.ContactID == Guid("<id>"); sort order = Date DESC; page page = 1.
  • Create Invoices — PUT /Invoices. Body: { "Invoices": [ { "Type": "ACCREC", "Contact": { "ContactID": "<id>" }, "LineItems": [ { "Description": "Consulting", "Quantity": 1, "UnitAmount": 500, "AccountCode": "200" } ], "Date": "2026-08-30", "DueDate": "2026-09-30" } ] }.
  • Update Or Create Invoices — POST /Invoices (include InvoiceID in the body to update, e.g. set Status to AUTHORISED or VOIDED).
  • Get Invoice / Update Invoice — GET / POST /Invoices/{InvoiceID}.
  • Get Invoice As Pdf — GET /Invoices/{InvoiceID}/pdf (raw PDF body).
  • Email Invoice — POST /Invoices/{InvoiceID}/Email (empty body — sends to the contact).
  • Get Online Invoice — GET /Invoices/{InvoiceID}/OnlineInvoice — {{<stepReference>.response.data.OnlineInvoices[0].OnlineInvoiceUrl}}.

Items

Products and services.

  • Get Items / Create Items (PUT) / Update Or Create Items (POST) — on /Items. Create body: { "Items": [ { "Code": "WIDGET", "Name": "Widget", "SalesDetails": { "UnitPrice": 20.0, "AccountCode": "200" } } ] }.
  • Get Item / Update Item / Delete Item — GET / POST / DELETE /Items/{ItemID}.

Payments

Payments against invoices and credit notes.

  • Get Payments — GET /Payments.
  • Create Payments — PUT /Payments (batch).
  • Create Payment — POST /Payments (single). Body: { "Invoice": { "InvoiceID": "<id>" }, "Account": { "AccountID": "<bankAccountId>" }, "Amount": 500.00, "Date": "2026-08-30" }.
  • Get Payment — GET /Payments/{PaymentID}.
  • Delete Payment — POST /Payments/{PaymentID} with body { "Status": "DELETED" } (Xero reverses a payment via a status update, not DELETE).

Generic Request

Five actions — Generic GET / POST / PUT / PATCH / DELETE Request — for any Xero endpoint the dedicated actions don't cover (Attachments, History, and the excluded areas: Bank Transfers, Purchase Orders, Quotes, Manual Journals, Reports, Tracking Categories, Tax Rates, Organisation, Users, …).

  • path — required, relative to /api.xro/2.0, e.g. /Invoices/<id>/Attachments, /Reports/BalanceSheet, /Organisation.
  • Request Body (Raw) — the JSON body for PUT / POST.
  • Add the xero-tenant-id Additional Header here (the generic actions have no dedicated field for it).

Example

Get Invoices, xero-tenant-id set, Additional Query Parameters where = Status=="AUTHORISED"&&Type=="ACCREC" and order = Date DESC — list authorised sales invoices, newest first.

Also applies here

Step Name

What it's for

Every step in a workflow gets a name — either one you set or a default based on the connector and action (e.g. "Get Order Details", "Send Welcome Email"). It's shown throughout the UI and in your execution history, and it's also the source for the step's Reference — a camelCase identifier auto-generated from the name (e.g. "Get Order Details" → getOrderDetails) — which is what you actually use in {{...}} expressions to read this step's output from later steps. See Step Reference.

Rules

  • Must be at least 2 characters, and 50 characters or fewer.
  • Must be unique within the workflow — reusing a name that's already taken will be rejected, with a suggested alternative (e.g. "Get Order Details 2").
  • Can't be empty.

Tips

  • Prefer a descriptive, human-readable name over a generic one — "Get Order Details" is easier to work with later than "HTTP Request 2", especially once a workflow has a dozen steps.
  • Renaming a step updates every reference to it elsewhere in the workflow automatically.

Step Reference

Syntax

Any input field can reference earlier data using {{expression}}. The expression is evaluated as JSONata — so simple dot-paths and more advanced queries (filters, functions) both work.

Referencing a step's output

Use the step's Reference — a camelCase identifier auto-generated from its Name (e.g. "Get Order Details" → getOrderDetails), shown read-only wherever the step's fields are configured — followed by the field path. Elsewhere in these docs this general pattern is written as {{<stepReference>.field.path}}:

{{getOrderDetails.response.data.id}}
{{getOrderDetails.response.status}}

The raw display name won't work here even though it's what you see in the UI — {{Get Order Details.response.data.id}} isn't valid, since a bare name containing spaces isn't a single JSONata identifier. Always use the camelCase Reference.

You can also reference steps by position instead of by reference:

{{steps[0].response.data.id}}

Referencing trigger data

{{trigger.headers.authorization}}
{{trigger.body.customerId}}
{{trigger.query.page}}
{{trigger.params.orderId}}
{{trigger.method}}
{{trigger.path}}

Referencing workflow variables

{{variables.myVariable}}

See Variables for the full list of variable types and more examples, including connection-type variables.

Referencing runtime variables

A separate, mutable namespace written by the Variable connector while a run is in progress — not the same as the workflow-level variables above:

{{runtimeVariables.myVariable}}

Notes

  • If an expression can't be resolved (a typo in a step name, a field that doesn't exist), it resolves to an empty string rather than failing the workflow — check your execution history if a value comes through blank.
  • Object values are automatically JSON-stringified when interpolated into a string field.

Execution Settings

Fire-and-forget

When enabled, the workflow doesn't wait for this step to complete before moving to the next one. Use it for steps whose result nothing downstream depends on — logging, analytics, notifications — so they don't add latency to the steps that matter.

Continue on error

When enabled, a failure in this step doesn't stop the workflow — execution continues to the next step. The failure is still recorded in the execution history; this just controls whether it's fatal.

Combine the two for steps that are genuinely optional to the outcome: fire-and-forget so they don't add latency, continue-on-error so a failure in them (e.g. an analytics endpoint being briefly down) doesn't take down an otherwise-successful workflow run.

Caching

What it does

When enabled, a step's result is cached for a configurable TTL (time-to-live, in seconds). If the step runs again with the same effective cache key before the TTL expires, the cached result is returned instead of re-running the step.

Configuring it

  • Enabled — turn caching on or off for this step.
  • TTL — how long (in seconds) a cached result stays valid.
  • Cache key template — an expression (supporting the same {{...}} step reference syntax used elsewhere) that determines what counts as "the same call". By default this is based on the step's resolved input; a custom template lets you cache more narrowly or broadly than that.

When to use it

Good candidates are steps that call something slow or rate-limited but return the same answer for the same input within a short window — a lookup against a rarely-changing external system, for example. Skip it for steps whose result must always be fresh (anything involving live inventory, pricing, or payment state).

Locking

What it does

When enabled, only one execution of this step (for a given lock key) can run at a time. If a second execution tries to run the same step while a lock is held, it waits until the lock is released or the hold period elapses.

Configuring it

  • Enabled — turn locking on or off for this step.
  • Lock key — an expression (supporting the same {{...}} step reference syntax used elsewhere) that determines what counts as "the same resource". By default the lock is scoped to the step itself; a custom key lets you lock per-customer, per-order, or any other identifier that needs serialized access.
  • Period — how long (in seconds) the lock is held before it's automatically released, in case an execution doesn't complete normally.

When to use it

Use it whenever concurrent executions could race on the same resource — e.g. two workflow runs both trying to update the same order's status at once. A lock key scoped to the order id ensures only one of them proceeds at a time.