Xero Accounting API records: list (one page or all), get, create,
update, upsert and delete, plus invoice PDF and email, status
changes, attachments and the organisation. Every function takes the
resource name as Xero spells it in the URL ("Invoices",
"BankTransactions"; case-insensitive) and an optional opts Map
(see ::xero::api).
| Resource | List paging | Create / update | Delete | Attachments | |
|---|---|---|---|---|---|
| Contacts, Invoices, CreditNotes, BankTransactions, ManualJournals, PurchaseOrders | page, pageSize | yes | via status | Invoices, CreditNotes, PurchaseOrders | yes |
| Quotes | page | yes | via status | yes | yes |
| Payments | page, pageSize | create | delete-payment | no | no |
| BankTransfers | all at once | create | no | no | yes |
| Accounts, Items, TrackingCategories | all at once | yes | delete-record | no | Accounts |
| TaxRates | all at once | yes | no | no | no |
| Organisation | read | no | no | no | no |
Writes. create-records (PUT) and upsert-records (POST) take
one record or a Vec (up to 50 per request is a good batch size; Xero
caps request size at 3.5 MB). Pass opts.summarize-errors: false to
get a 200 with per-record ValidationErrors instead of one 400 for
the whole batch, then read them with element-errors. Pass
opts.idempotency-key to make a write safe to retry.
Statuses. Invoices, credit notes and bills are not deleted:
void-invoice voids an authorised one, delete-draft-invoice
deletes a draft. Contacts are archived (archive-contact).
::acc ::xero::accounting
contact first(::acc/create-records("Contacts", {Name: "Acme Corp", EmailAddress: "ap@acme.example"}))
invoice first(::acc/create-records("Invoices", {
Type: "ACCREC",
Contact: {ContactID: contact.ContactID},
LineItems: [{Description: "Consulting", Quantity: 10, UnitAmount: 150, AccountCode: "200"}],
Date: "2026-11-01",
DueDate: "2026-11-30",
Status: "AUTHORISED"
}, {idempotency-key: "order-4411-invoice"}))
::acc/email-invoice(invoice.InvoiceID)
pdf ::acc/invoice-pdf(invoice.InvoiceID)
Values
RESOURCES
RESOURCES: Map {
Accounts: {
key: "Accounts",
id: "AccountID",
paged: false,
page-size: false,
ops: [
"list",
"get",
"create",
"update",
"delete"
],
pdf: false,
attachments: true
},
BankTransactions: {
key: "BankTransactions",
id: "BankTransactionID",
paged: true,
page-size: true,
ops: [
"list",
"get",
"create",
"update",
"upsert"
],
pdf: false,
attachments: true
},
BankTransfers: {
key: "BankTransfers",
id: "BankTransferID",
paged: false,
page-size: false,
ops: [
"list",
"get",
"create"
],
pdf: false,
attachments: true
},
Contacts: {
key: "Contacts",
id: "ContactID",
paged: true,
page-size: true,
ops: [
"list",
"get",
"create",
"update",
"upsert"
],
pdf: false,
attachments: true
},
CreditNotes: {
key: "CreditNotes",
id: "CreditNoteID",
paged: true,
page-size: true,
ops: [
"list",
"get",
"create",
"update",
"upsert"
],
pdf: true,
attachments: true
},
Invoices: {
key: "Invoices",
id: "InvoiceID",
paged: true,
page-size: true,
ops: [
"list",
"get",
"create",
"update",
"upsert"
],
pdf: true,
attachments: true
},
Items: {
key: "Items",
id: "ItemID",
paged: false,
page-size: false,
ops: [
"list",
"get",
"create",
"update",
"upsert",
"delete"
],
pdf: false,
attachments: false
},
ManualJournals: {
key: "ManualJournals",
id: "ManualJournalID",
paged: true,
page-size: true,
ops: [
"list",
"get",
"create",
"update",
"upsert"
],
pdf: false,
attachments: true
},
Organisation: {
key: "Organisations",
id: "OrganisationID",
paged: false,
page-size: false,
ops: [
"list"
],
pdf: false,
attachments: false
},
Payments: {
key: "Payments",
id: "PaymentID",
paged: true,
page-size: true,
ops: [
"list",
"get",
"create"
],
pdf: false,
attachments: false
},
PurchaseOrders: {
key: "PurchaseOrders",
id: "PurchaseOrderID",
paged: true,
page-size: true,
ops: [
"list",
"get",
"create",
"update",
"upsert"
],
pdf: true,
attachments: true
},
Quotes: {
key: "Quotes",
id: "QuoteID",
paged: true,
page-size: false,
ops: [
"list",
"get",
"create",
"update",
"upsert"
],
pdf: true,
attachments: true
},
TaxRates: {
key: "TaxRates",
id: "TaxType",
paged: false,
page-size: false,
ops: [
"list",
"get",
"create",
"upsert"
],
pdf: false,
attachments: false
},
TrackingCategories: {
key: "TrackingCategories",
id: "TrackingCategoryID",
paged: false,
page-size: false,
ops: [
"list",
"get",
"create",
"update",
"delete"
],
pdf: false,
attachments: false
}
}
The supported resources: URL name to {key, id, paged, page-size, ops, pdf, attachments}. key is the collection key in requests and
responses; ops lists list, get, create, update, upsert,
delete.
WRITE_PARAM_KEYS
WRITE_PARAM_KEYS: Map {
summarize-errors: "summarizeErrors",
unitdp: "unitdp"
}
Functions
archive-contact
fn (contact-id: Str): Map
fn (contact-id: Str, opts: Map): Map
Archive a contact (ContactStatus: "ARCHIVED").
Example
contact ::xero::accounting/archive-contact("6d2b51ce-0a4f-4a8b-9f7a-3c1e2d4b5a69")
contact.ContactStatus
canonical-name
fn (name: Str): Str
The canonical resource name ("invoices" gives "Invoices"), or an Err
listing the supported names.
Example
::xero::accounting/canonical-name("invoices") // "Invoices"
check-file-name
fn (name: Str): Str
A file name for an attachment, or an Err: non-empty, at most 255
characters, no / or \.
Example
::xero::accounting/check-file-name("receipt.pdf") // "receipt.pdf"
is-err(::xero::accounting/check-file-name("a/b.pdf")) // true
compact
fn (record: Map): Map
Drop null values from a record (one level), so unset optionals are omitted rather than sent as null.
Example
::xero::accounting/compact({Name: "Acme", EmailAddress: null}) // {Name: "Acme"}
create-records
fn (resource: Str, records: Map | Vec): Vec
fn (resource: Str, records: Map | Vec, opts: Map): Vec
PUT /{resource} - create one record or a Vec; returns the created
records. See the namespace doc for summarize-errors and
idempotency-key.
Example
rows ::xero::accounting/create-records("Contacts", {Name: "Acme Corp"})
first(rows).ContactID
// A batch that reports errors per record
batch ::xero::accounting/create-records("Contacts", [{Name: "Acme"}, {Name: "Globex"}], {summarize-errors: false})
::xero::accounting/element-errors("Contacts", batch)
delete-draft-invoice
fn (invoice-id: Str): Map
fn (invoice-id: Str, opts: Map): Map
Delete a draft or submitted invoice (Status: "DELETED").
Example
invoice ::xero::accounting/delete-draft-invoice("243216c5-369e-4056-ac67-05388f86dc81")
invoice.Status
delete-payment
fn (payment-id: Str): Map
fn (payment-id: Str, opts: Map): Map
POST /Payments/{id} with Status: "DELETED" - remove a payment (its
invoice becomes unpaid again). Returns the payment.
Example
payment ::xero::accounting/delete-payment("8a2c1f30-5b7d-4e19-9c44-1d6f0b3e7a12")
payment.Status
delete-record
fn (resource: Str, id: Str): Bool
fn (resource: Str, id: Str, opts: Map): Bool
DELETE /{resource}/{id} for Accounts, Items and TrackingCategories. Returns true. Transactions are voided or deleted by status instead.
Example
::xero::accounting/delete-record("Items", "5c7e2a10-9b34-4f6d-8e21-7a4d0c1b3f55")
element-errors
fn (resource: Str, body: Any): Vec
Per-record validation errors from a write made with
summarize-errors: false (pure): [{index, id, messages}] for each
record whose HasValidationErrors is true or that carries
ValidationErrors. id is the record's id field when Xero returned
one. Pass the response body ({Invoices: [...]}) or its Vec.
Example
::xero::accounting/element-errors("Invoices", {Invoices: [
{InvoiceID: "a1", HasValidationErrors: false},
{InvoiceID: "b2", HasValidationErrors: true, ValidationErrors: [{Message: "Contact is required"}]}
]}) // [{index: 1, id: "b2", messages: ["Contact is required"]}]
email-invoice
fn (invoice-id: Str): Bool
fn (invoice-id: Str, opts: Map): Bool
POST /Invoices/{id}/Email - email a sales invoice (ACCREC, status SUBMITTED, AUTHORISED or PAID) to its contact, using the organisation's email template. Returns true. Xero limits how many invoice emails an organisation can send per day.
Example
::xero::accounting/email-invoice("243216c5-369e-4056-ac67-05388f86dc81")
get-attachment
fn (resource: Str, id: Str, file-name: Str, mime-type: Str): Bytes
fn (resource: Str, id: Str, file-name: Str, mime-type: Str, opts: Map): Bytes
GET /{resource}/{id}/Attachments/{file-name} - the file as Bytes
(mime-type is sent as Accept).
Example
file ::xero::accounting/get-attachment("Invoices", "243216c5-369e-4056-ac67-05388f86dc81", "receipt-4411.pdf", "application/pdf")
length(file)
get-organisation
fn (): Map
fn (opts: Map): Map
GET /Organisation - the connected organisation (name, base currency, country, financial year end, ...).
Example
org ::xero::accounting/get-organisation()
org.BaseCurrency
get-record
fn (resource: Str, id: Str): Map
fn (resource: Str, id: Str, opts: Map): Map
GET /{resource}/{id} - one record (the first of the returned
collection), or an Err. For TaxRates the id is the TaxType.
Example
invoice ::xero::accounting/get-record("Invoices", "243216c5-369e-4056-ac67-05388f86dc81")
invoice.Status
// From another organisation
contact ::xero::accounting/get-record("Contacts", "6d2b51ce-0a4f-4a8b-9f7a-3c1e2d4b5a69", {tenant-id: "c2cc9b6e-9458-4c7d-93cc-f02b81b0594f"})
contact.Name
invoice-pdf
fn (invoice-id: Str): Bytes
fn (invoice-id: Str, opts: Map): Bytes
An invoice (or bill) as PDF Bytes.
Example
pdf ::xero::accounting/invoice-pdf("243216c5-369e-4056-ac67-05388f86dc81")
length(pdf)
list-all
fn (resource: Str): Vec
fn (resource: Str, params: Map): Vec
fn (resource: Str, params: Map, limit: Int?): Vec
fn (resource: Str, params: Map, limit: Int?, opts: Map): Vec
Every record of a list, following pages (from page 1), or at most
limit (null for no limit). Unpaged resources return in one call.
Paged resources use pageSize: 1000 unless params.pageSize says
otherwise. Each page is a call against the per-minute and daily
limits.
Example
invoices ::xero::accounting/list-all("Invoices", {Statuses: ["AUTHORISED"]})
length(invoices)
// At most 250 contacts, from one organisation
contacts ::xero::accounting/list-all("Contacts", {order: "Name"}, 250, {tenant-id: "c2cc9b6e-9458-4c7d-93cc-f02b81b0594f"})
map(contacts, %.Name)
list-attachments
fn (resource: Str, id: Str): Vec
fn (resource: Str, id: Str, opts: Map): Vec
GET /{resource}/{id}/Attachments - [{AttachmentID, FileName, Url, MimeType, ContentLength, IncludeOnline}].
Example
files ::xero::accounting/list-attachments("Invoices", "243216c5-369e-4056-ac67-05388f86dc81")
map(files, %.FileName)
list-page
fn (resource: Str): Page
fn (resource: Str, params: Map): Page
fn (resource: Str, params: Map, opts: Map): Page
GET /{resource} - one page (page 1 unless params.page is set).
params are Xero's own: where, order, page, pageSize,
IDs, Statuses, ContactIDs, InvoiceNumbers, searchTerm,
includeArchived, summaryOnly, unitdp, createdByMyApp.
opts.if-modified-since returns only records changed since then.
page ::xero::accounting/list-page("Invoices", {Statuses: ["AUTHORISED"], pageSize: 500})
page.next-page
list-params
fn (info: Map, params: Map, page: Int?): Map
The query params for one list page (pure): page (1-based; only for
paged resources) and pageSize (1-1000; only where supported), plus
every other param (where, order, IDs, Statuses,
ContactIDs, searchTerm, includeArchived, summaryOnly, ...)
with nulls dropped.
Example
info ::xero::accounting/resource-info("Invoices")
::xero::accounting/list-params(info, {Statuses: ["PAID"], pageSize: 5000, where: null}, 2) // {Statuses: ["PAID"], page: 2, pageSize: 1000}
online-invoice-url
fn (invoice-id: Str): Str
fn (invoice-id: Str, opts: Map): Str
GET /Invoices/{id}/OnlineInvoice - the customer-facing online invoice URL (sales invoices that are not drafts).
Example
url ::xero::accounting/online-invoice-url("243216c5-369e-4056-ac67-05388f86dc81")
println(url)
record-pdf
fn (resource: Str, id: Str): Bytes
fn (resource: Str, id: Str, opts: Map): Bytes
GET /{resource}/{id} as application/pdf (Invoices, CreditNotes,
PurchaseOrders, Quotes). Returns Bytes.
Example
pdf ::xero::accounting/record-pdf("CreditNotes", "1f3a9d42-6c7e-4b18-a5d0-2e8c4f7b6a31")
length(pdf)
require-op
fn (name: Str, op: Str): Map
The resource info when the resource supports op, else an Err.
Example
::xero::accounting/require-op("Invoices", "upsert").name // "Invoices"
is-err(::xero::accounting/require-op("Payments", "update")) // true
resource-info
fn (name: Str): Map
{name, key, id, paged, page-size, ops, pdf, attachments} for a
resource, or an Err.
Example
info ::xero::accounting/resource-info("invoices")
info.id // "InvoiceID"
info.paged // true
to-page
fn (info: Map, body: Any, page: Int?, size: Int): Page
Turn a list response into a Page (pure).
Example
info ::xero::accounting/resource-info("Contacts")
page ::xero::accounting/to-page(info, {Contacts: [{Name: "Acme"}]}, 1, 100)
page.items // [{Name: "Acme"}]
page.next-page // null
update-record
fn (resource: Str, id: Str, fields: Map): Map
fn (resource: Str, id: Str, fields: Map, opts: Map): Map
POST /{resource}/{id} - update one record with the fields in fields
(others are left as they are); returns it.
Example
invoice ::xero::accounting/update-record("Invoices", "243216c5-369e-4056-ac67-05388f86dc81", {Reference: "PO-4411"}, {idempotency-key: "po-4411-ref"})
invoice.Reference
upload-attachment
fn (resource: Str, id: Str, file-name: Str, content: Bytes | Str, mime-type: Str): Map
fn (resource: Str, id: Str, file-name: Str, content: Bytes | Str, mime-type: Str, opts: Map): Map
PUT /{resource}/{id}/Attachments/{file-name} - attach a file
(Bytes, or a Str sent as UTF-8) with its MIME type. Xero allows up
to 10 attachments of at most 25 MB each per record. opts.include-online: true shows it on the online invoice (Invoices, CreditNotes). Returns
the attachment record.
invoice-id "243216c5-369e-4056-ac67-05388f86dc81"
receipt ::hot::file/read-file-bytes("receipt-4411.pdf")
::xero::accounting/upload-attachment("Invoices", invoice-id, "receipt-4411.pdf", receipt, "application/pdf")
upsert-records
fn (resource: Str, records: Map | Vec): Vec
fn (resource: Str, records: Map | Vec, opts: Map): Vec
POST /{resource} - create or update one record or a Vec (records with an id are updated); returns the records.
Example
rows ::xero::accounting/upsert-records("Contacts", {ContactID: "6d2b51ce-0a4f-4a8b-9f7a-3c1e2d4b5a69", EmailAddress: "ap@acme.example"})
first(rows).EmailAddress
void-invoice
fn (invoice-id: Str): Map
fn (invoice-id: Str, opts: Map): Map
Void an authorised invoice or bill (Status: "VOIDED"). Paid invoices
must have their payments removed first.
Example
invoice ::xero::accounting/void-invoice("243216c5-369e-4056-ac67-05388f86dc81")
invoice.Status
write-body
fn (info: Map, records: Map | Vec): Map
The write body for one record or a Vec: {Invoices: [ ... ]} with nulls
dropped (pure).
Example
info ::xero::accounting/resource-info("Contacts")
::xero::accounting/write-body(info, {Name: "Acme", EmailAddress: null}) // {Contacts: [{Name: "Acme"}]}
write-params
fn (opts: Map): Map
Query params for a write from opts (pure): summarize-errors becomes
summarizeErrors, unitdp stays.
Example
::xero::accounting/write-params({summarize-errors: false, tenant-id: "ignored"}) // {summarizeErrors: false}
Types
Page
Page type {
items: Vec,
page: Int?,
next-page: Int?,
pagination: Map?,
warnings: Vec?,
not-modified: Bool,
response: Any
}
One list page: items, page (null for unpaged resources),
next-page (null on the last page), pagination (Xero's
{page, pageSize, pageCount, itemCount} when sent), warnings,
not-modified (true for a 304 with If-Modified-Since) and the
raw response.