Paging defaults and what the response tells you
When you ask Xero for invoices with a page number, it returns 100 invoices per call by default; the page size can be raised up to 1,000, and paging includes each invoice's line items, which avoids one call per invoice. The response carries a pagination object with the page, the page size, the page count and the item count. Older advice was to keep fetching pages until one came back empty. The pagination object lets you check completeness directly: after reading every page, the number of invoices collected should equal the item count.
Incremental reads with If-Modified-Since
For a recurring sync Xero describes the If-Modified-Since header, with a UTC timestamp, as the way to ask only for what was created or modified since the last read. If nothing has changed since that time Xero replies 304. On invoices, range operators are optimised for only three fields, the date, the due date and the amount due, and Xero advises keeping where filters as simple as possible because long, complex queries can cause time-outs. Together these shape an efficient design: a full read to start, then small incremental reads.
- Use a UTC timestamp and record the time zone of any report built from it.
- Prefer the header for incremental reads.
- Keep filters simple when paging.
How a report ends up incomplete
The commonest cause is reading page one only, which gives exactly 100 rows unless the page size was raised. The next is advancing the watermark when a run failed halfway: the next run asks only for changes after a time later than the invoices it never read. Others are a page size changed between runs, a window that excludes invoices modified while the run was in progress, and a status change such as voiding, which you should test rather than assume how your incremental read reports it.
- Set the watermark to the start time of the last fully successful run, not the end time.
- Re-read a small overlap and deduplicate by invoice identifier.
- Compare occasionally with a full read to catch drift.
A completeness check you can keep
Store, for each run, the item count the response reported, the number of invoices actually written, and the time range. If the two counts differ, mark the run failed and keep the previous output. If the request limits are hit, honour the wait value Xero returns; the related guide on rate limits explains pacing. A sheet or report built this way can show its own proof of completeness.
What fits, what does not, and how it is accepted
Complete reading is part of the job "Make a scheduled finance export to Google Sheets complete, current and honest on failure" (£245, an untested published price confirmed after your enquiry, with payment after the agreed checks pass and you sign off), accepted when a synthetic source that exceeds one page shows every row and a count that matches the source. It is also what the standing drift check relies on.
This guide does not decide which invoices belong in a report or what they mean for your accounts, and does not change anything in Xero. It is written from vendor documentation read on 11 October 2026 and nothing was run against a live organisation. Send invented examples and counts first, never credentials, bank details, invoices or customer records; real records are handled only after written agreement through a secure handoff.
Sources and limits
- Xero Accounting API: invoices Checked 2026-10-11.
- When the page parameter is used by itself, 100 invoices are returned per call by default, and the pageSize parameter sets the number per call (the page's example is page=1&pageSize=250).
- By using paging, all the line item details for each invoice are returned, which may avoid the need to retrieve each invoice individually.
- The optimised where filters on invoices include Date, DueDate and AmountDue, which also support range operators; the optimisation of the or operator is restricted to the InvoiceId field.
- Xero Accounting API: HTTP requests and responses Checked 2026-10-11.
- The default page size is 100, with a maximum of 1,000 and a minimum of 1; a value outside the range is adjusted to the nearest supported page size.
- A pagination object with page, pageSize, pageCount and itemCount is returned with paged results, and it supersedes the older advice to keep fetching pages until one comes back empty.
- Xero recommends keeping where filters as simple as possible because long, complex where queries can cause time-outs.
- Xero: filtering and efficient retrieval Checked 2026-10-11.
- For incremental syncs Xero describes the If-Modified-Since header, with a UTC timestamp, which returns only resources created or modified since that time, and a 304 Not Modified response when nothing has changed.
- Xero: limits FAQ Checked 2026-10-11.
- At the time checked the FAQ states per-connected-organisation limits of 60 calls per minute, 5 concurrent calls and a daily limit (5,000 per 24 hours), plus 10,000 calls per minute across all organisations for an app.
- Going over a limit returns HTTP 429 with a Retry-After header giving seconds to wait; responses carry headers showing the remaining daily, minute and app-minute allowance.
- Xero suggests combining creates or updates in one request (about 50 items is practical under the 3.5MB size cap), paging (100 records at a time) and the If-Modified-Since header.