Xero: Retrieves sales invoices or purchase bills

← Accounting operations · Get started

Operation xero.getinvoices

Provider route: GET /api.xro/2.0/Invoices. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/xero with npm, or alter-sdk-xero with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { XeroIntegration } from "@alter-ai/xero";

async function execute(input: Parameters<XeroIntegration["accounting"]["getInvoices"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new XeroIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.accounting.getInvoices(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_xero import XeroIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = XeroIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.accounting.get_invoices(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
query	object	Optional	Additional keys: not allowed
query.where	string	Optional
query.order	string	Optional
query.IDs	array	Optional
query.IDs[]	string	Each item	Format: uuid
query.InvoiceNumbers	array	Optional
query.InvoiceNumbers[]	string	Each item
query.ContactIDs	array	Optional
query.ContactIDs[]	string	Each item	Format: uuid
query.Statuses	array	Optional
query.Statuses[]	string	Each item
query.page	integer	Optional
query.includeArchived	boolean	Optional
query.createdByMyApp	boolean	Optional
query.unitdp	integer	Optional
query.summaryOnly	boolean	Optional	Default: false
query.pageSize	integer	Optional
query.searchTerm	string	Optional
headers	object	Required within parent	Additional keys: not allowed
headers.xero-tenant-id	string	Required within parent
headers.If-Modified-Since	string	Optional	Format: date-time

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Retrieves sales invoices or purchase bills — response body

Referenced models: Retrieves sales invoices or purchase bills — response body

Schemas

22 more schemas are linked from the tables above, on the schema pages.

Retrieves sales invoices or purchase bills — response body

Field	Type	Presence	Description and constraints
$	object	Root
Invoices	array	Optional
Invoices[]	Model	Each item	Expand Deletes an Allocation from a Prepayment — response body — Invoice
Warnings	array	Optional	Displays array of warning messages from the API
Warnings[]	Model	Each item	Expand Retrieves journals — response body — Warnings item
pagination	Model	Optional	Expand Retrieves prepayments — response body — pagination

Referenced models: Retrieves prepayments — response body — pagination, Deletes an Allocation from a Prepayment — response body — Invoice, Retrieves journals — response body — Warnings item

Retrieves prepayments — response body — pagination

Field	Type	Presence	Description and constraints
$	object	Root
itemCount	JSON	Optional
itemCount (anyOf 1)	integer	Alternative
itemCount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
page	JSON	Optional
page (anyOf 1)	integer	Alternative
page (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
pageCount	JSON	Optional
pageCount (anyOf 1)	integer	Alternative
pageCount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
pageSize	JSON	Optional
pageSize (anyOf 1)	integer	Alternative
pageSize (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Retrieves journals — response body — Warnings item

Field	Type	Presence	Description and constraints
$	object	Root
Message	string	Optional	Validation error message

Deletes an Allocation from a Prepayment — response body — Invoice Currency Code

Field	Type	Presence	Description and constraints
$	string	Root	3 letter alpha code for the currency – see list of currency codes Known values: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BYR, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EEK, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MRU, MUR, MVR, MWK, MXN, MXV, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SKK, SLE, SLL, SOS, SRD, STD, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VEF, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, YER, ZAR, ZMW, ZMK, ZWD

create Contact Attachment By File Name — response body — Attachments item

Field	Type	Presence	Description and constraints
$	object	Root
AttachmentID	string	Optional	Unique ID for the file Format: uuid
ContentLength	JSON	Optional
ContentLength (anyOf 1)	integer	Alternative	Length of the file content
ContentLength (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
FileName	string	Optional	Name of the file
IncludeOnline	boolean	Optional	Include the file with the online invoice
MimeType	string	Optional	Type of file
Url	string	Optional	URL to the file on xero.com

Deletes an Allocation from a Prepayment — response body — Invoice Invoice Addresses item

Field	Type	Presence	Description and constraints
$	object	Root
AddressLine1	string	Optional	First line of a physical address
AddressLine2	string	Optional	Second line of a physical address
AddressLine3	string	Optional	Third line of a physical address
AddressLine4	string	Optional	Fourth line of a physical address
City	string	Optional	City of a physical address
Country	string	Optional	Country of a physical address
InvoiceAddressType	string	Optional	Indicates whether the address is defined as origin (FROM) or destination (TO) Known values: FROM, TO
PostalCode	string	Optional	Postal code of a physical address
Region	string	Optional	Region or state of a physical address

Deletes an Allocation from a Prepayment — response body — Invoice Line Items item

Field	Type	Presence	Description and constraints
$	object	Root
AccountCode	string	Optional	See Accounts
AccountID	string	Optional	The associated account ID related to this line item Format: uuid
Description	string	Optional	Description needs to be at least 1 char long. A line item with just a description (i.e no unit amount or quantity) can be created by specifying just a <Description> element that contains at least 1 character
DiscountAmount	JSON	Optional
DiscountAmount (anyOf 1)	number	Alternative	Discount amount being applied to a line item. Only supported on ACCREC invoices and quotes. ACCPAY invoices and credit notes in Xero do not support discounts. Format: double
DiscountAmount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
DiscountRate	JSON	Optional
DiscountRate (anyOf 1)	number	Alternative	Percentage discount being applied to a line item (only supported on ACCREC invoices – ACC PAY invoices and credit notes in Xero do not support discounts Format: double
DiscountRate (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
Item	Model	Optional	Expand Deletes an Allocation from a Prepayment — response body — Invoice Line Items item Item
ItemCode	string	Optional	See Items
LineAmount	JSON	Optional
LineAmount (anyOf 1)	number	Alternative	If you wish to omit either the Quantity or UnitAmount you can provide a LineAmount and Xero will calculate the missing amount for you. The line amount reflects the discounted price if either a DiscountRate or DiscountAmount has been used i.e. LineAmount = Quantity * Unit Amount * ((100 - DiscountRate)/100) or LineAmount = (Quantity * UnitAmount) - DiscountAmount Format: double
LineAmount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
LineItemID	string	Optional	LineItem unique ID Format: uuid
Quantity	JSON	Optional
Quantity (anyOf 1)	number	Alternative	LineItem Quantity Format: double
Quantity (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
RepeatingInvoiceID	string	Optional	The Xero identifier for a Repeating Invoice Format: uuid
SalesTaxCodeId	JSON	Optional
SalesTaxCodeId (anyOf 1)	number	Alternative	The ID of the sales tax code
SalesTaxCodeId (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
TaxAmount	JSON	Optional
TaxAmount (anyOf 1)	number	Alternative	The tax amount is auto calculated as a percentage of the line amount (see below) based on the tax rate. This value can be overriden if the calculated <TaxAmount> is not correct. Format: double
TaxAmount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
TaxBreakdown	array	Optional	An array of tax components defined for this line item
TaxBreakdown[]	Model	Each item	Expand Deletes an Allocation from a Prepayment — response body — Invoice Line Items item Tax Breakdown item
TaxType	string	Optional	The tax type from TaxRates
Taxability	string	Optional	The type of taxability Known values: TAXABLE, NON_TAXABLE, EXEMPT, PART_TAXABLE, NOT_APPLICABLE
Tracking	array	Optional	Optional Tracking Category – see Tracking. Any LineItem can have a maximum of 2 <TrackingCategory> elements.
Tracking[]	Model	Each item	Expand Deletes an Allocation from a Prepayment — response body — Invoice Line Items item Tracking item
UnitAmount	JSON	Optional
UnitAmount (anyOf 1)	number	Alternative	LineItem Unit Amount Format: double
UnitAmount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Referenced models: Deletes an Allocation from a Prepayment — response body — Invoice Line Items item Item, Deletes an Allocation from a Prepayment — response body — Invoice Line Items item Tracking item, Deletes an Allocation from a Prepayment — response body — Invoice Line Items item Tax Breakdown item

Creates contacts to a specific contact group — response body — Contacts item Contact Persons item

Field	Type	Presence	Description and constraints
$	object	Root
EmailAddress	string	Optional	Email address of person
FirstName	string	Optional	First name of person
IncludeInEmails	boolean	Optional	boolean to indicate whether contact should be included on emails with invoices etc.
LastName	string	Optional	Last name of person

Policy, approvals and errors

SDK function policy ID: xero.getinvoices. Catalog operation: getInvoices. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Official provider source