Docs
Open Lodol
DocumentationIntegrationsAPI

Xero

App · Accounting & Finance · 20 actions

Manage a Xero organisation's contacts, invoices, bills, quotes, credit notes and items, and read its chart of accounts and tax rates.

Actions

ActionWhat it does
Archive or restore a contactArchive a contact so it can no longer be used on new transactions, or set it back to active.
Create a contactCreate a customer or supplier contact.
Create a credit noteRaise a credit note against a customer or a supplier.
Create a quoteRaise a quote for a contact.
Create an invoiceRaise a sales invoice or a bill against a contact.
Create an itemCreate an untracked item: a saved product or service whose code fills in a line's description, price and account.
Delete an itemDelete an item.
Delete or void an invoiceTake an invoice out of use.
Get a contactRead one contact in full, including its addresses, contact people and outstanding balances.
Get an invoiceRead one invoice in full, with its line items, payments and credit notes applied.
Get the organisationRead the connected Xero organisation: its name, country, base currency, financial year end and lock dates.
List accountsList the organisation's chart of accounts.
List contactsFind contacts by name, email, contact code or company number, or page through all of them.
List credit notesPage through the organisation's credit notes, newest change first.
List invoicesFind invoices and bills by status, contact, invoice number or reference.
List itemsList the organisation's saved products and services.
List quotesFind quotes by status, contact, number or quote date.
List tax ratesList the organisation's tax rates and the tax type codes line items use to override the default rate.
Update a contactChange a contact's details.
Update an invoiceChange an invoice or move it between draft, awaiting approval and approved.

Archive or restore a contact

Archive a contact so it can no longer be used on new transactions, or set it back to active. An archived contact keeps its name, so the name stays taken.

Inputs

Contact IDcontact_idtextRequired
The Xero ContactID of the contact.
Statusstatustext
Archive the contact, or restore it to active.One of: ACTIVE (Active (usable on transactions)), ARCHIVED (Archived (hidden and unusable on new transactions)). Default: ARCHIVED.

Outputs

AccountNumbertext
AccountsPayableTaxTypetext
AccountsReceivableTaxTypetext
Addresseslist
Balancesobject
BankAccountDetailstext
BatchPaymentsobject
BrandingThemeobject
CompanyNumbertext
ContactGroupslist
ContactIDtext
ContactNumbertext
ContactPersonslist
ContactStatustext
DefaultCurrencytext
Discountnumber
EmailAddresstext
FirstNametext
HasAttachmentstrue/false
IsCustomertrue/false
IsSuppliertrue/false
LastNametext
MergedToContactIDtext
Nametext
PaymentTermsobject
Phoneslist
PurchasesDefaultAccountCodetext
PurchasesDefaultLineAmountTypetext
PurchasesTrackingCategorieslist
SalesDefaultAccountCodetext
SalesDefaultLineAmountTypetext
SalesTrackingCategorieslist
TaxNumbertext
TaxNumberTypetext
TrackingCategoryNametext
TrackingOptionNametext
UpdatedDateUTCtext
Websitetext
XeroNetworkKeytext
Example output
{
  "ContactID": "e0e0e0e0-1111-2222-3333-444455556666",
  "ContactStatus": "ARCHIVED",
  "DefaultCurrency": "GBP",
  "EmailAddress": "ap@acme.example",
  "FirstName": "Ada",
  "IsCustomer": true,
  "IsSupplier": false,
  "LastName": "Lovelace",
  "Name": "Acme Ltd",
  "Phones": [
    {
      "PhoneNumber": "020 7946 0000",
      "PhoneType": "DEFAULT"
    }
  ],
  "UpdatedDateUTC": "2026-08-14T09:12:30.940Z"
}

Create a contact

Create a customer or supplier contact. Xero refuses a name another contact already holds, archived ones included.

Inputs

NamenametextRequired
The contact or organisation name. Must be unique in Xero, and cannot contain angle brackets or repeated spaces.
Emailemailtext
The contact's primary email address.
First namefirst_nametext
The main contact person's first name.
Last namelast_nametext
The main contact person's last name.
Phone numberphonetext
A phone number for the contact.
Phone typephone_typetext
Which of Xero's four phone slots the number goes in.One of: DEFAULT (Main), MOBILE, DDI (Direct dial), FAX. Default: DEFAULT.
Contact codecontact_numbertext
Your own identifier for this contact, shown as Contact Code in Xero. 'Get a contact' accepts it in place of the id.
Account numberaccount_numbertext
A user-defined account number for the contact.
Tax numbertax_numbertext
The contact's tax number: ABN, GST number, VAT number or tax ID depending on your Xero region.
Company numbercompany_numbertext
The contact's company registration number.
Default currencydefault_currencytext
ISO currency code used when invoicing this contact, e.g. GBP.
Address line 1address_line1text
First line of the contact's address.
Address line 2address_line2text
Second line of the contact's address.
Citycitytext
City or town.
Regionregiontext
State, province or region.
Postal codepostal_codetext
Postcode or ZIP code.
Countrycountrytext
Country name (letters only, as Xero requires).
Address typeaddress_typetext
Which address this is. Invoices are addressed to the postal one.One of: POBOX (Postal (the address invoices are addressed to)), STREET. Default: POBOX.

Outputs

AccountNumbertext
AccountsPayableTaxTypetext
AccountsReceivableTaxTypetext
Addresseslist
Balancesobject
BankAccountDetailstext
BatchPaymentsobject
BrandingThemeobject
CompanyNumbertext
ContactGroupslist
ContactIDtext
ContactNumbertext
ContactPersonslist
ContactStatustext
DefaultCurrencytext
Discountnumber
EmailAddresstext
FirstNametext
HasAttachmentstrue/false
IsCustomertrue/false
IsSuppliertrue/false
LastNametext
MergedToContactIDtext
Nametext
PaymentTermsobject
Phoneslist
PurchasesDefaultAccountCodetext
PurchasesDefaultLineAmountTypetext
PurchasesTrackingCategorieslist
SalesDefaultAccountCodetext
SalesDefaultLineAmountTypetext
SalesTrackingCategorieslist
TaxNumbertext
TaxNumberTypetext
TrackingCategoryNametext
TrackingOptionNametext
UpdatedDateUTCtext
Websitetext
XeroNetworkKeytext
Example output
{
  "ContactID": "e0e0e0e0-1111-2222-3333-444455556666",
  "ContactStatus": "ACTIVE",
  "DefaultCurrency": "GBP",
  "EmailAddress": "ap@acme.example",
  "FirstName": "Ada",
  "IsCustomer": true,
  "IsSupplier": false,
  "LastName": "Lovelace",
  "Name": "Acme Ltd",
  "Phones": [
    {
      "PhoneNumber": "020 7946 0000",
      "PhoneType": "DEFAULT"
    }
  ],
  "UpdatedDateUTC": "2026-08-14T09:12:30.940Z"
}

Create a credit note

Raise a credit note against a customer or a supplier. Xero does not allow discounts on credit note lines.

Inputs

Contact IDcontact_idtext
The Xero ContactID to raise this against. Get one from 'Create a contact' or 'List contacts'.
Contact namecontact_nametext
Used only when no Contact ID is given: the contact with exactly this name is looked up first, and only its id is sent. The contact itself is never changed.
Typecredit_note_typetext
Whether this credits a customer or a supplier.One of: ACCRECCREDIT (Customer credit note (against a sales invoice)), ACCPAYCREDIT (Supplier credit note (against a bill)). Default: ACCRECCREDIT.
Statusstatustext
The status to create the credit note in.One of: DRAFT, SUBMITTED (Awaiting approval), AUTHORISED (Approved). Default: DRAFT.
Line descriptiondescriptiontext
What the line is for. Required unless an item code is given.
Quantityquantitynumber
How many units. Defaults to 1.At least 0. Default: 1.
Unit amountunit_amountnumber
The price per unit, before tax.
Accountaccount_codetext
The account this line posts to. Optional on a draft, required before it can be approved.
Item codeitem_codetext
A saved item's code, which fills the line's description, price and account from the item.
Tax ratetax_typetext
Overrides the tax rate the account would otherwise apply.
Line items (advanced)line_itemslist
A list of line objects for a multi-line document, e.g. [{"description": "Design", "quantity": 2, "unit_amount": 150}]. When given it replaces the single-line fields above.
Amounts include tax?line_amount_typestext
Whether the amounts above include tax. Defaults to excluding it.One of: Exclusive (Amounts exclude tax), Inclusive (Amounts include tax), NoTax (No tax).
Credit note datedatedate
The date the credit note is issued. Defaults to today.
Credit note numbercredit_note_numbertext
Your own number. Left blank, Xero generates one.
Referencereferencetext
An additional reference. Customer credit notes only.
Currencycurrency_codetext
ISO currency code. Defaults to the organisation's base currency.

Outputs

Allocationslist
BrandingThemeIDtext
CISDeductionnumber
Contactobject
CreditNoteIDtext
CreditNoteNumbertext
CurrencyCodetext
CurrencyRatenumber
Datetext
DateStringtext
FullyPaidOnDatetext
HasAttachmentstrue/false
LineAmountTypestext
LineItemslist
Referencetext
RemainingCreditnumber
SentToContacttrue/false
Statustext
StatusAttributeStringtext
SubTotalnumber
Totalnumber
TotalTaxnumber
Typetext
UpdatedDateUTCtext
UpdatedDateUTCStringtext
Example output
{
  "Contact": {
    "ContactID": "e0e0e0e0-1111-2222-3333-444455556666",
    "Name": "Acme Ltd"
  },
  "CreditNoteID": "cccc3333-dddd-4444-eeee-5555ffff6666",
  "CreditNoteNumber": "CN-0003",
  "CurrencyCode": "GBP",
  "Date": "2026-09-02T00:00:00Z",
  "LineAmountTypes": "Exclusive",
  "LineItems": [
    {
      "AccountCode": "200",
      "Description": "Onsite project management",
      "LineAmount": 125.0,
      "LineItemID": "52208ff9-528a-4985-a9ad-b2b1d4210e38",
      "Quantity": 1,
      "TaxAmount": 50.0,
      "TaxType": "OUTPUT2",
      "UnitAmount": 125.0
    }
  ],
  "RemainingCredit": 150.0,
  "Status": "DRAFT",
  "SubTotal": 125.0,
  "Total": 150.0,
  "TotalTax": 25.0,
  "Type": "ACCRECCREDIT",
  "UpdatedDateUTC": "2026-09-02T11:02:00.000Z"
}

Create a quote

Raise a quote for a contact. Created as a draft unless it is sent straight away.

Inputs

Contact IDcontact_idtext
The Xero ContactID to raise this against. Get one from 'Create a contact' or 'List contacts'.
Contact namecontact_nametext
Used only when no Contact ID is given: the contact with exactly this name is looked up first, and only its id is sent. The contact itself is never changed.
Statusstatustext
Save the quote as a draft, or mark it as sent.One of: DRAFT, SENT. Default: DRAFT.
Line descriptiondescriptiontext
What the line is for. Required unless an item code is given.
Quantityquantitynumber
How many units. Defaults to 1.At least 0. Default: 1.
Unit amountunit_amountnumber
The price per unit, before tax.
Accountaccount_codetext
The account this line posts to. Optional on a draft, required before it can be approved.
Item codeitem_codetext
A saved item's code, which fills the line's description, price and account from the item.
Tax ratetax_typetext
Overrides the tax rate the account would otherwise apply.
Discount %discount_ratenumber
A percentage discount on this line, 0-100.From 0.0 to 100.0.
Line items (advanced)line_itemslist
A list of line objects for a multi-line document, e.g. [{"description": "Design", "quantity": 2, "unit_amount": 150}]. When given it replaces the single-line fields above.
Amounts include tax?line_amount_typestext
Whether the amounts above include tax. Defaults to excluding it.One of: Exclusive (Amounts exclude tax), Inclusive (Amounts include tax), NoTax (No tax).
Quote datedatedate
The date the quote is issued. Xero requires one; today's date is used when this is left blank.
Expiry dateexpiry_datedate
The date the quote stops being valid.
Quote numberquote_numbertext
Your own quote number. Left blank, Xero generates one.
Referencereferencetext
An additional reference for the quote.
Titletitletext
A title shown on the quote, max 100 characters.
Summarysummarytext
A summary shown on the quote, max 3000 characters.
Termstermstext
The quote's terms, max 4000 characters.
Currencycurrency_codetext
ISO currency code. Defaults to the organisation's base currency.

Outputs

BrandingThemeIDtext
Contactobject
CurrencyCodetext
CurrencyRatenumber
Datetext
DateStringtext
ExpiryDatetext
ExpiryDateStringtext
LineAmountTypestext
LineItemslist
QuoteIDtext
QuoteNumbertext
Referencetext
Statustext
StatusAttributeStringtext
SubTotalnumber
Summarytext
Termstext
Titletext
Totalnumber
TotalDiscountnumber
TotalTaxnumber
UpdatedDateUTCtext
Example output
{
  "Contact": {
    "ContactID": "e0e0e0e0-1111-2222-3333-444455556666",
    "Name": "Acme Ltd"
  },
  "CurrencyCode": "GBP",
  "Date": "2026-09-01T00:00:00Z",
  "ExpiryDate": "2026-09-15T00:00:00Z",
  "LineAmountTypes": "Exclusive",
  "LineItems": [
    {
      "AccountCode": "200",
      "Description": "Onsite project management",
      "LineAmount": 250.0,
      "LineItemID": "52208ff9-528a-4985-a9ad-b2b1d4210e38",
      "Quantity": 2,
      "TaxAmount": 50.0,
      "TaxType": "OUTPUT2",
      "UnitAmount": 125.0
    }
  ],
  "QuoteID": "bbbb2222-cccc-3333-dddd-4444eeee5555",
  "QuoteNumber": "QU-0007",
  "Status": "DRAFT",
  "SubTotal": 250.0,
  "Title": "Website refresh",
  "Total": 300.0,
  "TotalTax": 50.0,
  "UpdatedDateUTC": "2026-09-01T10:16:00.000Z"
}

Create an invoice

Raise a sales invoice or a bill against a contact. Created as a draft unless a different status is chosen; approving it posts journals and needs an account on every line.

Inputs

Contact IDcontact_idtext
The Xero ContactID to raise this against. Get one from 'Create a contact' or 'List contacts'.
Contact namecontact_nametext
Used only when no Contact ID is given: the contact with exactly this name is looked up first, and only its id is sent. The contact itself is never changed.
Typeinvoice_typetext
A sales invoice you are owed, or a bill you owe.One of: ACCREC (Sales invoice (money owed to you)), ACCPAY (Bill (money you owe)). Default: ACCREC.
Statusstatustext
The status to create the invoice in.One of: DRAFT, SUBMITTED (Awaiting approval), AUTHORISED (Approved and awaiting payment). Default: DRAFT.
Line descriptiondescriptiontext
What the line is for. Required unless an item code is given.
Quantityquantitynumber
How many units. Defaults to 1.At least 0. Default: 1.
Unit amountunit_amountnumber
The price per unit, before tax.
Accountaccount_codetext
The account this line posts to. Optional on a draft, required before it can be approved.
Item codeitem_codetext
A saved item's code, which fills the line's description, price and account from the item.
Tax ratetax_typetext
Overrides the tax rate the account would otherwise apply.
Discount %discount_ratenumber
A percentage discount on this line, 0-100.From 0.0 to 100.0.
Line items (advanced)line_itemslist
A list of line objects for a multi-line document, e.g. [{"description": "Design", "quantity": 2, "unit_amount": 150}]. When given it replaces the single-line fields above.
Amounts include tax?line_amount_typestext
Whether the amounts above include tax. Defaults to excluding it.One of: Exclusive (Amounts exclude tax), Inclusive (Amounts include tax), NoTax (No tax).
Invoice datedatedate
The date the invoice is issued. Defaults to today.
Due datedue_datedate
The date payment is due.
Invoice numberinvoice_numbertext
Your own invoice number. Left blank, Xero generates the next one from your invoice settings.
Referencereferencetext
An additional reference shown on the invoice.
Currencycurrency_codetext
ISO currency code, e.g. GBP. Defaults to the organisation's base currency.
Source document URLurltext
A link Xero shows on the invoice, back to whatever raised it.

Outputs

AmountCreditednumber
AmountDuenumber
AmountPaidnumber
BrandingThemeIDtext
CISDeductionnumber
Contactobject
CreditNoteslist
CurrencyCodetext
CurrencyRatenumber
Datetext
DateStringtext
DueDatetext
DueDateStringtext
EnteredTotalnumber
ExpectedPaymentDatetext
FullyPaidOnDatetext
HasAttachmentstrue/false
InvoiceIDtext
InvoiceNumbertext
LineAmountTypestext
LineItemslist
Overpaymentslist
Paymentslist
PlannedPaymentDatetext
Prepaymentslist
Referencetext
RepeatingInvoiceIDtext
RoundingAmountnumber
SalesTaxCalculationTypeCodetext
SentToContacttrue/false
Statustext
StatusAttributeStringtext
SubTotalnumber
Totalnumber
TotalDiscountnumber
TotalTaxnumber
Typetext
UpdatedDateUTCtext
UpdatedDateUTCStringtext
Urltext
Warningslist
Example output
{
  "AmountDue": 300.0,
  "AmountPaid": 0.0,
  "Contact": {
    "ContactID": "e0e0e0e0-1111-2222-3333-444455556666",
    "Name": "Acme Ltd"
  },
  "CurrencyCode": "GBP",
  "Date": "2026-09-01T00:00:00Z",
  "DueDate": "2026-09-30T00:00:00Z",
  "InvoiceID": "aaaa1111-bbbb-2222-cccc-3333dddd4444",
  "InvoiceNumber": "INV-0042",
  "LineAmountTypes": "Exclusive",
  "LineItems": [
    {
      "AccountCode": "200",
      "Description": "Onsite project management",
      "LineAmount": 250.0,
      "LineItemID": "52208ff9-528a-4985-a9ad-b2b1d4210e38",
      "Quantity": 2,
      "TaxAmount": 50.0,
      "TaxType": "OUTPUT2",
      "UnitAmount": 125.0
    }
  ],
  "Status": "DRAFT",
  "SubTotal": 250.0,
  "Total": 300.0,
  "TotalTax": 50.0,
  "Type": "ACCREC",
  "UpdatedDateUTC": "2026-09-01T10:15:00.000Z"
}

Create an item

Create an untracked item: a saved product or service whose code fills in a line's description, price and account. Tracked inventory items are not created here.

Inputs

Item codecodetextRequired
Your code for the item. Must be unique, max 30 characters.
Namenametext
The item's name, max 50 characters.
Sales descriptiondescriptiontext
The description used when the item is sold.
Purchase descriptionpurchase_descriptiontext
The description used when the item is bought.
Sale pricesales_unit_pricenumber
What the item sells for, per unit.At least 0.
Sales accountsales_account_codetext
The account a sale of this item posts to.
Sales tax ratesales_tax_typetext
The tax rate applied when the item is sold.
Purchase pricepurchase_unit_pricenumber
What the item costs to buy, per unit.At least 0.
Purchase accountpurchase_account_codetext
The account a purchase of this item posts to.
Purchase tax ratepurchase_tax_typetext
The tax rate applied when the item is bought.
Available on salesis_soldtrue/false
Whether the item can be used on sales invoices.Default: true.
Available on purchasesis_purchasedtrue/false
Whether the item can be used on bills.Default: true.

Outputs

Codetext
Descriptiontext
InventoryAssetAccountCodetext
IsPurchasedtrue/false
IsSoldtrue/false
IsTrackedAsInventorytrue/false
ItemIDtext
Nametext
PurchaseDescriptiontext
PurchaseDetailsobject
QuantityAvailablenumber
QuantityOnBackOrdernumber
QuantityOnHandnumber
SalesDetailsobject
TotalCostPoolnumber
UpdatedDateUTCtext
Example output
{
  "Code": "CONSULT-DAY",
  "Description": "One day of consulting",
  "IsPurchased": false,
  "IsSold": true,
  "IsTrackedAsInventory": false,
  "ItemID": "dddd4444-eeee-5555-ffff-6666aaaa7777",
  "Name": "Consulting day",
  "SalesDetails": {
    "AccountCode": "200",
    "TaxType": "OUTPUT2",
    "UnitPrice": 750.0
  },
  "UpdatedDateUTC": "2026-08-30T08:00:00.000Z"
}

Delete an item

Delete an item. Xero cannot restore one afterwards; documents that already used it keep their lines.

Inputs

Item ID or codeitem_idtextRequired
The Xero ItemID, or the item's code.

Outputs

deletedtrue/false
item_idtext
Example output
{
  "deleted": true,
  "item_id": "dddd4444-eeee-5555-ffff-6666aaaa7777"
}

Delete or void an invoice

Take an invoice out of use. A draft or awaiting-approval invoice is deleted; an approved one with no payments against it is voided. Xero refuses the other way round.

Inputs

Invoice ID or numberinvoice_idtextRequired
The Xero InvoiceID, or the invoice number.
Delete or voidstatustext
Which of Xero's two ways out of an invoice to use.One of: DELETED (Delete (only a draft or awaiting-approval invoice)), VOIDED (Void (an approved invoice with no payments applied)). Default: DELETED.

Outputs

AmountCreditednumber
AmountDuenumber
AmountPaidnumber
BrandingThemeIDtext
CISDeductionnumber
Contactobject
CreditNoteslist
CurrencyCodetext
CurrencyRatenumber
Datetext
DateStringtext
DueDatetext
DueDateStringtext
EnteredTotalnumber
ExpectedPaymentDatetext
FullyPaidOnDatetext
HasAttachmentstrue/false
InvoiceIDtext
InvoiceNumbertext
LineAmountTypestext
LineItemslist
Overpaymentslist
Paymentslist
PlannedPaymentDatetext
Prepaymentslist
Referencetext
RepeatingInvoiceIDtext
RoundingAmountnumber
SalesTaxCalculationTypeCodetext
SentToContacttrue/false
Statustext
StatusAttributeStringtext
SubTotalnumber
Totalnumber
TotalDiscountnumber
TotalTaxnumber
Typetext
UpdatedDateUTCtext
UpdatedDateUTCStringtext
Urltext
Warningslist
Example output
{
  "AmountDue": 300.0,
  "AmountPaid": 0.0,
  "Contact": {
    "ContactID": "e0e0e0e0-1111-2222-3333-444455556666",
    "Name": "Acme Ltd"
  },
  "CurrencyCode": "GBP",
  "Date": "2026-09-01T00:00:00Z",
  "DueDate": "2026-09-30T00:00:00Z",
  "InvoiceID": "aaaa1111-bbbb-2222-cccc-3333dddd4444",
  "InvoiceNumber": "INV-0042",
  "LineAmountTypes": "Exclusive",
  "LineItems": [
    {
      "AccountCode": "200",
      "Description": "Onsite project management",
      "LineAmount": 250.0,
      "LineItemID": "52208ff9-528a-4985-a9ad-b2b1d4210e38",
      "Quantity": 2,
      "TaxAmount": 50.0,
      "TaxType": "OUTPUT2",
      "UnitAmount": 125.0
    }
  ],
  "Status": "DELETED",
  "SubTotal": 250.0,
  "Total": 300.0,
  "TotalTax": 50.0,
  "Type": "ACCREC",
  "UpdatedDateUTC": "2026-09-01T10:15:00.000Z"
}

Get a contact

Read one contact in full, including its addresses, contact people and outstanding balances.

Inputs

Contact ID or codecontact_idtextRequired
The Xero ContactID, or the contact code you set on it.

Outputs

AccountNumbertext
AccountsPayableTaxTypetext
AccountsReceivableTaxTypetext
Addresseslist
Balancesobject
BankAccountDetailstext
BatchPaymentsobject
BrandingThemeobject
CompanyNumbertext
ContactGroupslist
ContactIDtext
ContactNumbertext
ContactPersonslist
ContactStatustext
DefaultCurrencytext
Discountnumber
EmailAddresstext
FirstNametext
HasAttachmentstrue/false
IsCustomertrue/false
IsSuppliertrue/false
LastNametext
MergedToContactIDtext
Nametext
PaymentTermsobject
Phoneslist
PurchasesDefaultAccountCodetext
PurchasesDefaultLineAmountTypetext
PurchasesTrackingCategorieslist
SalesDefaultAccountCodetext
SalesDefaultLineAmountTypetext
SalesTrackingCategorieslist
TaxNumbertext
TaxNumberTypetext
TrackingCategoryNametext
TrackingOptionNametext
UpdatedDateUTCtext
Websitetext
XeroNetworkKeytext
Example output
{
  "ContactID": "e0e0e0e0-1111-2222-3333-444455556666",
  "ContactStatus": "ACTIVE",
  "DefaultCurrency": "GBP",
  "EmailAddress": "ap@acme.example",
  "FirstName": "Ada",
  "IsCustomer": true,
  "IsSupplier": false,
  "LastName": "Lovelace",
  "Name": "Acme Ltd",
  "Phones": [
    {
      "PhoneNumber": "020 7946 0000",
      "PhoneType": "DEFAULT"
    }
  ],
  "UpdatedDateUTC": "2026-08-14T09:12:30.940Z"
}

Get an invoice

Read one invoice in full, with its line items, payments and credit notes applied.

Inputs

Invoice ID or numberinvoice_idtextRequired
The Xero InvoiceID, or the invoice number e.g. INV-0042.

Outputs

AmountCreditednumber
AmountDuenumber
AmountPaidnumber
BrandingThemeIDtext
CISDeductionnumber
Contactobject
CreditNoteslist
CurrencyCodetext
CurrencyRatenumber
Datetext
DateStringtext
DueDatetext
DueDateStringtext
EnteredTotalnumber
ExpectedPaymentDatetext
FullyPaidOnDatetext
HasAttachmentstrue/false
InvoiceIDtext
InvoiceNumbertext
LineAmountTypestext
LineItemslist
Overpaymentslist
Paymentslist
PlannedPaymentDatetext
Prepaymentslist
Referencetext
RepeatingInvoiceIDtext
RoundingAmountnumber
SalesTaxCalculationTypeCodetext
SentToContacttrue/false
Statustext
StatusAttributeStringtext
SubTotalnumber
Totalnumber
TotalDiscountnumber
TotalTaxnumber
Typetext
UpdatedDateUTCtext
UpdatedDateUTCStringtext
Urltext
Warningslist
Example output
{
  "AmountDue": 300.0,
  "AmountPaid": 0.0,
  "Contact": {
    "ContactID": "e0e0e0e0-1111-2222-3333-444455556666",
    "Name": "Acme Ltd"
  },
  "CurrencyCode": "GBP",
  "Date": "2026-09-01T00:00:00Z",
  "DueDate": "2026-09-30T00:00:00Z",
  "InvoiceID": "aaaa1111-bbbb-2222-cccc-3333dddd4444",
  "InvoiceNumber": "INV-0042",
  "LineAmountTypes": "Exclusive",
  "LineItems": [
    {
      "AccountCode": "200",
      "Description": "Onsite project management",
      "LineAmount": 250.0,
      "LineItemID": "52208ff9-528a-4985-a9ad-b2b1d4210e38",
      "Quantity": 2,
      "TaxAmount": 50.0,
      "TaxType": "OUTPUT2",
      "UnitAmount": 125.0
    }
  ],
  "Status": "DRAFT",
  "SubTotal": 250.0,
  "Total": 300.0,
  "TotalTax": 50.0,
  "Type": "ACCREC",
  "UpdatedDateUTC": "2026-09-01T10:15:00.000Z"
}

Get the organisation

Read the connected Xero organisation: its name, country, base currency, financial year end and lock dates.

Inputs

None.

Outputs

APIKeytext
Addresseslist
BaseCurrencytext
Classtext
CountryCodetext
CreatedDateUTCtext
DefaultPurchasesTaxtext
DefaultSalesTaxtext
Editiontext
EmployerIdentificationNumbertext
EndOfYearLockDatetext
FinancialYearEndDaynumber
FinancialYearEndMonthnumber
IsDemoCompanytrue/false
LegalNametext
LineOfBusinesstext
Nametext
OrganisationEntityTypetext
OrganisationIDtext
OrganisationStatustext
OrganisationTypetext
PaysTaxtrue/false
PeriodLockDatetext
Phoneslist
RegistrationNumbertext
SalesTaxBasistext
SalesTaxPeriodtext
ShortCodetext
TaxNumbertext
Timezonetext
Versiontext
Example output
{
  "BaseCurrency": "GBP",
  "Class": "DEMO",
  "CountryCode": "GB",
  "CreatedDateUTC": "2026-01-05T09:00:00.000Z",
  "Edition": "BUSINESS",
  "FinancialYearEndDay": 31,
  "FinancialYearEndMonth": 3,
  "IsDemoCompany": true,
  "LegalName": "Demo Company (UK) Ltd",
  "Name": "Demo Company (UK)",
  "OrganisationID": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "OrganisationStatus": "ACTIVE",
  "Timezone": "UTC"
}

List accounts

List the organisation's chart of accounts. Use it to find the account code a line item should post to.

Inputs

Account typeaccount_typetext
Only return accounts of this type.One of: BANK (Bank account), CURRENT (Current asset), CURRLIAB (Current liability), DEPRECIATN (Depreciation), DIRECTCOSTS (Direct costs), EQUITY, EXPENSE, FIXED (Fixed asset), INVENTORY (Inventory asset), LIABILITY, and 7 more.
Statusstatustext
Only return accounts in this status.One of: ACTIVE, ARCHIVED.
Limitlimitnumber
How many records to return. Xero sends them all in one response, so this trims the result.From 1 to 1000. Default: 100.
Changed sincemodified_sincedate and time
Only return records created or changed after this moment.

Outputs

accountslist
countnumber
total_countnumber
Example output
{
  "accounts": [
    {
      "AccountID": "4f2a3169-8454-4012-a642-05a88ef32982",
      "Class": "REVENUE",
      "Code": "200",
      "EnablePaymentsToAccount": false,
      "Name": "Sales",
      "Status": "ACTIVE",
      "TaxType": "OUTPUT2",
      "Type": "REVENUE"
    },
    {
      "AccountID": "8a1b9c5d-3f2e-4a7b-9c8d-1e2f3a4b5c6d",
      "Class": "EXPENSE",
      "Code": "400",
      "EnablePaymentsToAccount": false,
      "Name": "Advertising",
      "Status": "ACTIVE",
      "TaxType": "INPUT2",
      "Type": "EXPENSE"
    }
  ],
  "count": 2,
  "total_count": 2
}

List contacts

Find contacts by name, email, contact code or company number, or page through all of them.

Inputs

Searchsearch_termtext
Case-insensitive search across name, first and last name, contact number, company number and email.
Contact IDscontact_idslist
Return only these contacts, by their Xero ids.
Include archivedinclude_archivedtrue/false
Also return contacts that have been archived.Default: false.
Summary onlysummary_onlytrue/false
Return a lighter, faster record without addresses, balances, contact groups or contact people.Default: false.
Sort byordertext
How to order the results.One of: Name ASC (Name (A–Z)), Name DESC (Name (Z–A)), UpdatedDateUTC DESC (Recently updated first), UpdatedDateUTC ASC (Least recently updated first).
Pagepagenumber
Which page of results to return. Starts at 1.At least 1. Default: 1.
Page sizepage_sizenumber
How many results per page (1-1000). Defaults to 100.From 1 to 1000. Default: 100.
Changed sincemodified_sincedate and time
Only return records created or changed after this moment.

Outputs

contactslist
countnumber
has_moretrue/false
item_countnumber
pagenumber
page_countnumber
page_sizenumber
Example output
{
  "contacts": [
    {
      "ContactID": "e0e0e0e0-1111-2222-3333-444455556666",
      "ContactStatus": "ACTIVE",
      "DefaultCurrency": "GBP",
      "EmailAddress": "ap@acme.example",
      "FirstName": "Ada",
      "IsCustomer": true,
      "IsSupplier": false,
      "LastName": "Lovelace",
      "Name": "Acme Ltd",
      "Phones": [
        {
          "PhoneNumber": "020 7946 0000",
          "PhoneType": "DEFAULT"
        }
      ],
      "UpdatedDateUTC": "2026-08-14T09:12:30.940Z"
    }
  ],
  "count": 1,
  "has_more": false,
  "item_count": 1,
  "page": 1,
  "page_count": 1,
  "page_size": 100
}

List credit notes

Page through the organisation's credit notes, newest change first. Every result carries its line items and allocations.

Inputs

Sort byordertext
How to order the results.One of: UpdatedDateUTC DESC (Recently updated first), UpdatedDateUTC ASC (Least recently updated first).
Pagepagenumber
Which page of results to return. Starts at 1.At least 1. Default: 1.
Page sizepage_sizenumber
How many results per page (1-1000). Defaults to 100.From 1 to 1000. Default: 100.
Changed sincemodified_sincedate and time
Only return records created or changed after this moment.

Outputs

countnumber
credit_noteslist
has_moretrue/false
item_countnumber
pagenumber
page_countnumber
page_sizenumber
Example output
{
  "count": 1,
  "credit_notes": [
    {
      "Contact": {
        "ContactID": "e0e0e0e0-1111-2222-3333-444455556666",
        "Name": "Acme Ltd"
      },
      "CreditNoteID": "cccc3333-dddd-4444-eeee-5555ffff6666",
      "CreditNoteNumber": "CN-0003",
      "CurrencyCode": "GBP",
      "Date": "2026-09-02T00:00:00Z",
      "LineAmountTypes": "Exclusive",
      "LineItems": [
        {
          "AccountCode": "200",
          "Description": "Onsite project management",
          "LineAmount": 125.0,
          "LineItemID": "52208ff9-528a-4985-a9ad-b2b1d4210e38",
          "Quantity": 1,
          "TaxAmount": 50.0,
          "TaxType": "OUTPUT2",
          "UnitAmount": 125.0
        }
      ],
      "RemainingCredit": 150.0,
      "Status": "DRAFT",
      "SubTotal": 125.0,
      "Total": 150.0,
      "TotalTax": 25.0,
      "Type": "ACCRECCREDIT",
      "UpdatedDateUTC": "2026-09-02T11:02:00.000Z"
    }
  ],
  "has_more": false,
  "item_count": 1,
  "page": 1,
  "page_count": 1,
  "page_size": 100
}

List invoices

Find invoices and bills by status, contact, invoice number or reference. Every result carries its line items.

Inputs

Statusesstatuseslist
Only return invoices in these statuses.One or more of: DRAFT, SUBMITTED (Awaiting approval), AUTHORISED (Approved and awaiting payment), PAID, VOIDED, DELETED.
Contact IDscontact_idslist
Only return invoices for these contacts.
Invoice numbersinvoice_numberslist
Only return invoices with these exact numbers.
Searchsearch_termtext
Case-insensitive search across invoice number and reference.
Only ones created herecreated_by_my_apptrue/false
Only return invoices this Xero connection created.Default: false.
Sort byordertext
How to order the results.One of: Date DESC (Invoice date, newest first), Date ASC (Invoice date, oldest first), UpdatedDateUTC DESC (Recently updated first), UpdatedDateUTC ASC (Least recently updated first).
Pagepagenumber
Which page of results to return. Starts at 1.At least 1. Default: 1.
Page sizepage_sizenumber
How many results per page (1-1000). Defaults to 100.From 1 to 1000. Default: 100.
Changed sincemodified_sincedate and time
Only return records created or changed after this moment.

Outputs

countnumber
has_moretrue/false
invoiceslist
item_countnumber
pagenumber
page_countnumber
page_sizenumber
Example output
{
  "count": 1,
  "has_more": false,
  "invoices": [
    {
      "AmountDue": 300.0,
      "AmountPaid": 0.0,
      "Contact": {
        "ContactID": "e0e0e0e0-1111-2222-3333-444455556666",
        "Name": "Acme Ltd"
      },
      "CurrencyCode": "GBP",
      "Date": "2026-09-01T00:00:00Z",
      "DueDate": "2026-09-30T00:00:00Z",
      "InvoiceID": "aaaa1111-bbbb-2222-cccc-3333dddd4444",
      "InvoiceNumber": "INV-0042",
      "LineAmountTypes": "Exclusive",
      "LineItems": [
        {
          "AccountCode": "200",
          "Description": "Onsite project management",
          "LineAmount": 250.0,
          "LineItemID": "52208ff9-528a-4985-a9ad-b2b1d4210e38",
          "Quantity": 2,
          "TaxAmount": 50.0,
          "TaxType": "OUTPUT2",
          "UnitAmount": 125.0
        }
      ],
      "Status": "DRAFT",
      "SubTotal": 250.0,
      "Total": 300.0,
      "TotalTax": 50.0,
      "Type": "ACCREC",
      "UpdatedDateUTC": "2026-09-01T10:15:00.000Z"
    }
  ],
  "item_count": 1,
  "page": 1,
  "page_count": 1,
  "page_size": 100
}

List items

List the organisation's saved products and services.

Inputs

Limitlimitnumber
How many records to return. Xero sends them all in one response, so this trims the result.From 1 to 1000. Default: 100.
Changed sincemodified_sincedate and time
Only return records created or changed after this moment.

Outputs

countnumber
itemslist
total_countnumber
Example output
{
  "count": 1,
  "items": [
    {
      "Code": "CONSULT-DAY",
      "Description": "One day of consulting",
      "IsPurchased": false,
      "IsSold": true,
      "IsTrackedAsInventory": false,
      "ItemID": "dddd4444-eeee-5555-ffff-6666aaaa7777",
      "Name": "Consulting day",
      "SalesDetails": {
        "AccountCode": "200",
        "TaxType": "OUTPUT2",
        "UnitPrice": 750.0
      },
      "UpdatedDateUTC": "2026-08-30T08:00:00.000Z"
    }
  ],
  "total_count": 1
}

List quotes

Find quotes by status, contact, number or quote date.

Inputs

Statusstatustext
Only return quotes in this status.One of: DRAFT, SENT, ACCEPTED, DECLINED, INVOICED, DELETED.
Contact IDcontact_idtext
Only return quotes for this contact.
Quote numberquote_numbertext
Matches any part of the quote number, so 'QU-01' finds QU-0100 as well as QU-0101.
Dated fromdate_fromdate
Only return quotes issued on or after this date.
Dated todate_todate
Only return quotes issued on or before this date.
Sort byordertext
How to order the results.One of: UpdatedDateUTC DESC (Recently updated first), UpdatedDateUTC ASC (Least recently updated first).
Pagepagenumber
Which page of results to return. Starts at 1.At least 1. Default: 1.
Page sizepage_sizenumber
How many results per page (1-1000). Defaults to 100.From 1 to 1000. Default: 100.
Changed sincemodified_sincedate and time
Only return records created or changed after this moment.

Outputs

countnumber
has_moretrue/false
item_countnumber
pagenumber
page_countnumber
page_sizenumber
quoteslist
Example output
{
  "count": 1,
  "has_more": false,
  "item_count": 1,
  "page": 1,
  "page_count": 1,
  "page_size": 100,
  "quotes": [
    {
      "Contact": {
        "ContactID": "e0e0e0e0-1111-2222-3333-444455556666",
        "Name": "Acme Ltd"
      },
      "CurrencyCode": "GBP",
      "Date": "2026-09-01T00:00:00Z",
      "ExpiryDate": "2026-09-15T00:00:00Z",
      "LineAmountTypes": "Exclusive",
      "LineItems": [
        {
          "AccountCode": "200",
          "Description": "Onsite project management",
          "LineAmount": 250.0,
          "LineItemID": "52208ff9-528a-4985-a9ad-b2b1d4210e38",
          "Quantity": 2,
          "TaxAmount": 50.0,
          "TaxType": "OUTPUT2",
          "UnitAmount": 125.0
        }
      ],
      "QuoteID": "bbbb2222-cccc-3333-dddd-4444eeee5555",
      "QuoteNumber": "QU-0007",
      "Status": "DRAFT",
      "SubTotal": 250.0,
      "Title": "Website refresh",
      "Total": 300.0,
      "TotalTax": 50.0,
      "UpdatedDateUTC": "2026-09-01T10:16:00.000Z"
    }
  ]
}

List tax rates

List the organisation's tax rates and the tax type codes line items use to override the default rate.

Inputs

Statusstatustext
Only return tax rates in this status.One of: ACTIVE (Active (usable on transactions)), DELETED, ARCHIVED (Archived (used historically, not usable now)).
Limitlimitnumber
How many records to return. Xero sends them all in one response, so this trims the result.From 1 to 1000. Default: 100.

Outputs

countnumber
tax_rateslist
total_countnumber
Example output
{
  "count": 2,
  "tax_rates": [
    {
      "DisplayTaxRate": 20.0,
      "EffectiveRate": 20.0,
      "Name": "20% (VAT on Income)",
      "ReportTaxType": "OUTPUT2",
      "Status": "ACTIVE",
      "TaxComponents": [
        {
          "IsCompound": false,
          "Name": "VAT",
          "Rate": 20.0
        }
      ],
      "TaxType": "OUTPUT2"
    },
    {
      "DisplayTaxRate": 0.0,
      "EffectiveRate": 0.0,
      "Name": "Zero Rated Income",
      "Status": "ACTIVE",
      "TaxComponents": [
        {
          "IsCompound": false,
          "Name": "Zero Rated",
          "Rate": 0.0
        }
      ],
      "TaxType": "ZERORATEDOUTPUT"
    }
  ],
  "total_count": 2
}

Update a contact

Change a contact's details. Anything left blank keeps the value Xero already holds.

Inputs

Contact IDcontact_idtextRequired
The Xero ContactID of the contact to change.
Namenametext
A new name for the contact.
Emailemailtext
The contact's primary email address.
First namefirst_nametext
The main contact person's first name.
Last namelast_nametext
The main contact person's last name.
Phone numberphonetext
A phone number for the contact.
Phone typephone_typetext
Which of Xero's four phone slots the number goes in.One of: DEFAULT (Main), MOBILE, DDI (Direct dial), FAX. Default: DEFAULT.
Contact codecontact_numbertext
Your own identifier for this contact, shown as Contact Code in Xero. 'Get a contact' accepts it in place of the id.
Account numberaccount_numbertext
A user-defined account number for the contact.
Tax numbertax_numbertext
The contact's tax number: ABN, GST number, VAT number or tax ID depending on your Xero region.
Company numbercompany_numbertext
The contact's company registration number.
Default currencydefault_currencytext
ISO currency code used when invoicing this contact, e.g. GBP.
Address line 1address_line1text
First line of the contact's address.
Address line 2address_line2text
Second line of the contact's address.
Citycitytext
City or town.
Regionregiontext
State, province or region.
Postal codepostal_codetext
Postcode or ZIP code.
Countrycountrytext
Country name (letters only, as Xero requires).
Address typeaddress_typetext
Which address this is. Invoices are addressed to the postal one.One of: POBOX (Postal (the address invoices are addressed to)), STREET. Default: POBOX.

Outputs

AccountNumbertext
AccountsPayableTaxTypetext
AccountsReceivableTaxTypetext
Addresseslist
Balancesobject
BankAccountDetailstext
BatchPaymentsobject
BrandingThemeobject
CompanyNumbertext
ContactGroupslist
ContactIDtext
ContactNumbertext
ContactPersonslist
ContactStatustext
DefaultCurrencytext
Discountnumber
EmailAddresstext
FirstNametext
HasAttachmentstrue/false
IsCustomertrue/false
IsSuppliertrue/false
LastNametext
MergedToContactIDtext
Nametext
PaymentTermsobject
Phoneslist
PurchasesDefaultAccountCodetext
PurchasesDefaultLineAmountTypetext
PurchasesTrackingCategorieslist
SalesDefaultAccountCodetext
SalesDefaultLineAmountTypetext
SalesTrackingCategorieslist
TaxNumbertext
TaxNumberTypetext
TrackingCategoryNametext
TrackingOptionNametext
UpdatedDateUTCtext
Websitetext
XeroNetworkKeytext
Example output
{
  "ContactID": "e0e0e0e0-1111-2222-3333-444455556666",
  "ContactStatus": "ACTIVE",
  "DefaultCurrency": "GBP",
  "EmailAddress": "billing@acme.example",
  "FirstName": "Ada",
  "IsCustomer": true,
  "IsSupplier": false,
  "LastName": "Lovelace",
  "Name": "Acme Ltd",
  "Phones": [
    {
      "PhoneNumber": "020 7946 0000",
      "PhoneType": "DEFAULT"
    }
  ],
  "UpdatedDateUTC": "2026-08-14T09:12:30.940Z"
}

Update an invoice

Change an invoice or move it between draft, awaiting approval and approved. Supplying line items replaces every line on the invoice.

Inputs

Invoice IDinvoice_idtextRequired
The Xero InvoiceID of the invoice to change.
Statusstatustext
Move the invoice to this status. Use 'Delete or void an invoice' to take one out of use.One of: DRAFT, SUBMITTED (Awaiting approval), AUTHORISED (Approved and awaiting payment).
Contact IDcontact_idtext
The Xero ContactID to raise this against. Get one from 'Create a contact' or 'List contacts'.
Contact namecontact_nametext
Used only when no Contact ID is given: the contact with exactly this name is looked up first, and only its id is sent. The contact itself is never changed.
Invoice datedatedate
A new issue date for the invoice.
Due datedue_datedate
A new due date for the invoice.
Invoice numberinvoice_numbertext
A new invoice number.
Referencereferencetext
A new reference for the invoice.
Source document URLurltext
A link Xero shows on the invoice.
Mark as sentsent_to_contacttrue/false
Show the invoice as sent in Xero. Only an approved invoice can be marked sent.
Line items (replaces all lines)line_itemslist
A complete new list of lines. Every existing line whose LineItemID is missing from this list is deleted, so include the ones you want to keep.
Amounts include tax?line_amount_typestext
Whether the line amounts include tax.One of: Exclusive (Amounts exclude tax), Inclusive (Amounts include tax), NoTax (No tax).

Outputs

AmountCreditednumber
AmountDuenumber
AmountPaidnumber
BrandingThemeIDtext
CISDeductionnumber
Contactobject
CreditNoteslist
CurrencyCodetext
CurrencyRatenumber
Datetext
DateStringtext
DueDatetext
DueDateStringtext
EnteredTotalnumber
ExpectedPaymentDatetext
FullyPaidOnDatetext
HasAttachmentstrue/false
InvoiceIDtext
InvoiceNumbertext
LineAmountTypestext
LineItemslist
Overpaymentslist
Paymentslist
PlannedPaymentDatetext
Prepaymentslist
Referencetext
RepeatingInvoiceIDtext
RoundingAmountnumber
SalesTaxCalculationTypeCodetext
SentToContacttrue/false
Statustext
StatusAttributeStringtext
SubTotalnumber
Totalnumber
TotalDiscountnumber
TotalTaxnumber
Typetext
UpdatedDateUTCtext
UpdatedDateUTCStringtext
Urltext
Warningslist
Example output
{
  "AmountDue": 300.0,
  "AmountPaid": 0.0,
  "Contact": {
    "ContactID": "e0e0e0e0-1111-2222-3333-444455556666",
    "Name": "Acme Ltd"
  },
  "CurrencyCode": "GBP",
  "Date": "2026-09-01T00:00:00Z",
  "DueDate": "2026-09-30T00:00:00Z",
  "InvoiceID": "aaaa1111-bbbb-2222-cccc-3333dddd4444",
  "InvoiceNumber": "INV-0042",
  "LineAmountTypes": "Exclusive",
  "LineItems": [
    {
      "AccountCode": "200",
      "Description": "Onsite project management",
      "LineAmount": 250.0,
      "LineItemID": "52208ff9-528a-4985-a9ad-b2b1d4210e38",
      "Quantity": 2,
      "TaxAmount": 50.0,
      "TaxType": "OUTPUT2",
      "UnitAmount": 125.0
    }
  ],
  "Reference": "PO-91422",
  "Status": "DRAFT",
  "SubTotal": 250.0,
  "Total": 300.0,
  "TotalTax": 50.0,
  "Type": "ACCREC",
  "UpdatedDateUTC": "2026-09-01T10:15:00.000Z"
}

xeno-canto

Previous Page

XIVAPI

Next Page

On this page

ActionsArchive or restore a contactCreate a contactCreate a credit noteCreate a quoteCreate an invoiceCreate an itemDelete an itemDelete or void an invoiceGet a contactGet an invoiceGet the organisationList accountsList contactsList credit notesList invoicesList itemsList quotesList tax ratesUpdate a contactUpdate an invoice