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).

ResourceList pagingCreate / updateDeletePDFAttachments
Contacts, Invoices, CreditNotes, BankTransactions, ManualJournals, PurchaseOrderspage, pageSizeyesvia statusInvoices, CreditNotes, PurchaseOrdersyes
Quotespageyesvia statusyesyes
Paymentspage, pageSizecreatedelete-paymentnono
BankTransfersall at oncecreatenonoyes
Accounts, Items, TrackingCategoriesall at onceyesdelete-recordnoAccounts
TaxRatesall at onceyesnonono
Organisationreadnononono

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.