What Xero gives an integration builder
Xero documents stable identifiers (a contact's ContactID and a ContactNumber you can set through the API), a unique invoice number for sales invoices, an Idempotency-Key header that is kept for six minutes, paging with a pagination object, an If-Modified-Since header for incremental reads, per-organisation limits with a Retry-After response, a chart of accounts with active and archived accounts, lock dates, and a demo company that resets itself after 28 days. A trustworthy sync uses these deliberately; most failures come from using text that changes or limits that nobody read.
- Identity: store ContactID or your own number in ContactNumber; do not match on names alone.
- Limits: 60 calls a minute and 5 concurrent calls per organisation at the time checked, with a daily limit.
- Connection: refresh tokens lapse after 60 days of non-use.
Failure families and where to go next
Customers split across contacts, orders missing after a busy run, lines posting to the wrong account, foreign invoices with the wrong rate, expense bills without receipts, duplicate invoices after a retry and a sync that has quietly stopped are different failures with different fixes. Each has a guide that explains the mechanism, a safe first investigation and the point at which a paid, bounded job fits.
- Duplicate contacts: the contact identity guide and the contact job.
- Missing orders: the rate-limit guide and its pacing and checkpoint job.
- Wrong accounts: the mapping-table guide and its fixed-price job.
- Wrong currency or rate: the currency direction guide and job.
- Duplicate invoices: the request-key guide and the retry-safety job.
- A sync that stopped: the refresh-token guide and the standing health service.
A safe test looks like this
Test against the Xero demo company, never live records. Use invented customers, orders and amounts; do not send invoices; expect the demo data to disappear when it resets. Keep counts and identifiers from each step so you can show what changed. Lock dates and bank-reconciled transactions are decisions for the organisation's administrator and accountant.
Choose the actual outcome
Fixing one known failure is a bounded job. Several failures at once, in an order that matters, is a project. Watching a sync month after month is a standing service. None of them includes bookkeeping, tax or audit advice, changes to posted or locked records or live changes under our control; your authorised account holder applies changes. Prices on the linked pages are untested published prices, and nothing starts without a written agreement.
- The first enquiry uses invented examples, not credentials, invoices or customer records.
- Real records are shared only after agreement, through a secure handoff.
Sources and limits
- Xero Accounting API: contacts Checked 2026-10-11.
- ContactID is the identifier Xero recommends for referencing a contact, and Xero warns contact name may stop being unique in future.
- ContactNumber (up to 50 characters) can be set through the API and is shown in the Xero interface as Contact Code; AccountNumber is user-defined and is not stated to be unique.
- A PUT only creates and returns an error if an existing contact matches the name or contact number, while a POST can create or update.
- Archived contacts are left out of contact lists unless includeArchived is requested.
- 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.
- Xero: OAuth 2.0 FAQ Checked 2026-10-11.
- Access tokens last 30 minutes and unused refresh tokens expire after 60 days, after which the user must authorise the app again.
- Each successful refresh returns a new refresh token that must be stored in place of the old one.
- If a refresh request gets no response, the previous refresh token can be retried for 30 minutes before the user must re-authorise.
- Xero: idempotent requests Checked 2026-10-11.
- Xero accepts an Idempotency-Key header on POST, PUT and PATCH requests and ignores it on other methods.
- A key is kept for six minutes from its first use, may be at most 128 characters, is checked per app, and re-using it with a different request returns a 400.
- An error cached against a key is returned again on re-run, and idempotency is checked after rate limits so repeated calls still count toward them.
- Xero advises checking with a GET whether a resource was already created before retrying with a new key.
- Xero: account and payment mapping Checked 2026-10-11.
- Integrations should let users choose accounts from a filtered list, exclude accounts with status ARCHIVED, and not hard-code an account such as the sales account.
- Users can change their chart of accounts after set-up, so Xero advises validating stored mappings, before each call for infrequent integrations, and sending the user back to fix a missing or archived account.
- Payment accounts are filtered by account type BANK or by EnablePaymentsToAccount.
- Xero: the demo company Checked 2026-10-11.
- Data added to the demo company is deleted when it resets automatically after 28 days, and it can be reset manually.
- Invoices cannot be sent from the demo company, and only the person who adds data can see it.