Xero API Reality Check: Tracking Categories Need Context

Clean Accounting Is Not The Same As Operating Truth

Xero can be a clean accounting ledger.

That is a good thing.

For many service businesses, especially outside the U.S., Xero is a strong accounting system. It can hold contacts, invoices, bills, payments, bank activity, accounts, tracking categories, projects, and reporting.

It also has public developer documentation for APIs, webhooks, OAuth, and limits.

But clean accounting data is not automatically operating truth.

The owner still wants to know:

• which location, crew, job, client, or service line made money
• which completed work is not billed
• which invoice is collectible
• which tracking category is wrong
• which field-system status changed cash
• which payments, bills, and payroll events change the 13-week forecast

The Level view:

Xero can be clean and still not answer the operating question unless field-system data, tracking categories, projects, reports, and cash evidence are reconciled.

Source and claim note: Xero's developer documentation covers its API platform. Xero also publishes documentation for API limits and webhooks. The operating-finance framework below is Level's view from accounting, field-system, tracking-category, cash, and close reviews.

What Xero Usually Knows

Xero can be the accounting source for:

That is useful.

But operating context usually sits elsewhere.

Field software knows the job, visit, technician, customer site, scope, completion status, and service workflow. Payroll knows labor timing. PDFs and emails know proof. The owner knows which customer or contract is strategically important.

Xero receives part of that story.

The finance layer has to reconcile the rest.

The Tracking Category Problem

Tracking categories are powerful because they give Xero dimensional reporting.

They are also easy to misuse.

If the business wants to analyze region, crew, service line, job type, customer type, property, and salesperson, the team has to decide which dimensions belong in Xero and which belong in the external data layer.

If the team changes definitions midyear, reporting breaks.

If field-system categories do not map cleanly into Xero categories, reporting breaks.

If a bill is coded without the right tracking category, job margin breaks.

If a payment is applied to the wrong contact, AR analysis breaks.

The issue is not that tracking categories are bad.

The issue is that categories need ownership.

A practical decision rule:

For the seven dimensions above, region and service line often pass this test, while crew, salesperson, and property often fail it. Before you design the structure, Xero documents two active tracking categories and four total including archived categories. Its recommendation of no more than 100 options per category is a performance guideline, not a hard 100-option cap (tracking API, product help). Seven dimensions therefore cannot each occupy a separate active tracking category. Keep the others in a keyed external mapping rather than packing unstable attributes into one option name.

Webhooks Tell You Something Changed

Webhooks are useful.

They do not decide whether the number is correct.

When something changes in the accounting system, the data layer still has to ask:

• does this change tie to a field-system event?
• did the customer or supplier mapping stay correct?
• did the tracking category match the operating dimension?
• did the change affect AR, AP, cash, margin, or forecast?
• does the owner need to act?

That is the difference between integration and finance.

The webhook is a signal.

The reconciliation layer turns the signal into a decision.

Xero-Specific Constraints (Checked October 7, 2026)

Sources: Xero's maintained webhook schema, current tier-specific FAQ, invoice endpoint, and request and pagination documentation. The limits page and webhook overview remain useful build references. Check the live tier and schema again before implementation.

Do not call every polling difference a lost webhook. A payment may have no independently subscribed event, an invoice may change when payment is applied, or the app may lack the scope to read it. Classify the discrepancy first:

1. For one week, retain event IDs, tenant, type, arrival time and the result of the associated read. Handle retries idempotently and verify the webhook signature using Xero's current instructions.
2. Run a scheduled, fully paginated reconciliation pull for the required resources. Use supported modification filters where available, with an overlap window and periodic broader reconciliation. Compare both identifiers and relevant financial fields.
3. Separate records outside subscribed event coverage, failed reads or exhausted limits, delayed or duplicate events, and genuinely missing covered notifications. Only the last category establishes a missed-event candidate.
4. Independently tie open AR, bills, payments and bank evidence to the accounting reports. Matching the event log does not prove the finance totals.

For a read-only AI exception review, use this bounded prompt:

Compare the supplied Xero invoice export, payment export, field-job register and tracking map for the same tenant and dates. Return record IDs, the mismatch, the supporting source rows and the next verification step. Keep missing data separate from a confirmed missing invoice or payment. Propose no posting, category change, invoice send or write-off. Ask a reviewer to resolve uncertain mappings.

Use a browser or report export when an authorized UI reveals a needed report or mapping that the available API does not return. Record the tenant, report settings, export time and control totals. If browser extraction drops rows, changes filters or loses stable identifiers, stop and reconcile the export before analysis. This is an operating playbook, not a claim that an AI browser has completed a measured Xero integration.

The Field-System Context Problem

A service business running Xero plus Jobber, ServiceM8, Tradify, ServiceTitan, or another field system has two kinds of truth.

The field system knows work.

Xero knows accounting.

The owner needs a combined view.

Examples:

• field system says job complete; Xero has no invoice
• Xero has invoice; field system says backup is missing
• Xero has payment; field system still marks customer overdue
• field system has recurring visit; Xero revenue is not tied to visit economics
• Xero has bill; field system job cost is not updated
• Xero tracking category says region; field system says site

None of those are solved by a generic dashboard.

They require mapping and review.

What Level Builds Around Xero

Level keeps Xero as the accounting ledger and builds the operating layer around it.

That usually means:

1. Map field-system clients, jobs, properties, invoices, and visits to Xero contacts, invoices, tracking categories, or projects.
2. Define which dimensions belong in Xero and which live outside it.
3. Reconcile completed work to invoices.
4. Reconcile invoices to proof and collectability.
5. Reconcile bills and payroll timing to margin.
6. Monitor webhook signals for exceptions, not noise.
7. Build weekly owner actions around cash, margin, AR, billing, and job/customer profitability.

The goal is not "more data."

The goal is one trusted operating view.

For the broader architecture, read the API is not enough for finance automation and the 13-week cash forecast is a data-layer test. For field-system gaps, read the numbers your field software does not show you and use the cash-gap calculator.

The Owner Test

Pick one tracking category and ask whether it still means what the owner thinks it means.

For example:

• if it is region, does every invoice and bill have region?
• if it is service line, does payroll follow service line?
• if it is location, does the field system use the same location structure?
• if it is division, do recurring reports use the same division definition?
• if it is project, does the project tie to field work and cash?

This test exposes definition and coverage gaps quickly.

The accounting file can be clean and the reporting definition can still be weak.

The owner does not need ten more charts.

The owner needs category discipline:

1. what does the category mean?
2. who owns the definition?
3. which systems feed it?
4. what happens when a transaction is missing it?
5. which owner decision depends on it?

For benchmark context, compare margin and cash movement against contractor benchmarks even if Xero is not the only system involved.

What Owners Should Ask

If you use Xero, ask:

1. Which tracking categories are strategic?
2. Who owns category definitions?
3. Which field-system dimensions do not fit in Xero?
4. Which invoices are missing field-system proof?
5. Which completed jobs have not reached Xero?
6. Which bills or payroll costs are missing operating context?
7. Which webhook events become owner actions?
8. Which number do we not trust?

If the team cannot answer, the issue is not Xero alone.

It is the finance data layer around Xero.

FAQ

Does Xero have APIs and webhooks?

Xero publishes developer documentation for its API platform, including API limits and webhooks.

Are tracking categories enough for service-business reporting?

They can be useful, but most operating questions also need field-system context, payroll timing, documents, projects, customer/site mapping, and review.

Should a service business switch from Xero to another accounting system?

Not automatically. Many businesses need cleaner mapping, tracking-category discipline, field-system reconciliation, and cash reporting before they need a new ledger.

Get A Free Data-Layer Audit

Show us the Xero report or tracking category you do not trust.

Level will map Xero, field-system data, reports, PDFs, payroll, and cash timing into a cleaner owner view.

Get your free audit

Related Reading

• The API Is Not Enough for Finance Automation
• The 13-week cash forecast is a data-layer test
• The 8 numbers your field management software does not show you
• Why your field software is not fixing your cash flow