Xero Integration Playbook
A customised playbook for building your Xero API integration, to get your team on the right track.
Is your team building a custom Xero integration? Do you want to get it right the first time, without wasting time and money on rework?
Our Xero API Integration Playbook is a customised playbook for building a reliable custom Xero integration. It includes specific guidance for your requirements and environment. It also includes all the best practices we developed from years of building and maintaining Xero integrations.
It includes topics such as authentication, query optimisation, incremental vs bulk data ingest, handling rate limits and errors, and a list of best practices to ensure your Xero integration is reliable.
The playbook is delivered within 10 business days of data discovery, for a fixed price, for any programming language.
Who is this for?
Any development team who is building a custom Xero integration and wants to get it right the first time.
The Xero API is documented thoroughly, but there’s no guide that tells you how to build a high quality, reliable integration with it. Especially with the new paid API tiers, it’s important to use the Xero API efficiently to keep costs down.
What kind of integration are you building?
The playbook is tailored to the type of integration you’re building. Common ones we see are:
- Import and export. One-way data transfer, such as pushing invoices from your system into Xero, or pulling contacts and transactions out for another system.
- Two-way sync. Keeping data in sync between your application and Xero.
- Dashboards and reporting. Reading financial data from Xero to power an internal dashboard or embed reporting in your product.
- Consolidated reporting. Pulling data from multiple Xero organisations into one view, common for franchises, multi-entity groups, and accounting firms.
- Workflow automation. Reacting to events in Xero, such as a paid invoice triggering fulfilment, or creating Xero records when something happens in your system.
- A Xero-connected product. A SaaS product that connects to each customer’s own Xero organisation, including Xero App Store listings.
How we tailor your playbook
We start with your integration requirements and use our experience with Xero to recommend approaches for your build.
Your requirements
What you're building, what data moves where, and how often it needs to update.
We work through the decisions
We check what Xero supports, locate your data and recommend approaches that fit your build.
Guidance for your team
Our proven Xero guidance, adapted with recommendations and examples for your integration.
What the playbook covers
A playbook written for your requirements and environment. It covers:
- Xero setup for your administrator: creating the app, choosing the right scopes, and handing credentials over securely
- Which OAuth approach fits your situation and why, with setup instructions for your environment
- Token storage and lifecycle, including secure credential storage and secret rotation
- How to query the data types agreed at kickoff, with sample API calls and server-side filtering
- Efficiently ingesting data from Xero, including incremental and bulk approaches
- Reliably writing data to Xero, including idempotency and validation error handling
- API client pseudocode your developers can implement directly in your language
- Advice on where the integration sits in your application, e.g. manual refresh vs a background process
- Best practices around: tenant selection, retries, rate limit handling, date handling, and error handling for common Xero API issues
- A testing and verification checklist, including how to exercise each path against the Xero demo company before going live
The playbook is delivered as a shared Google Doc within 10 business days of completing data discovery.
Pseudocode and examples in the playbook are included to explain best practice approaches. They are not a spec.
What’s not included
The playbook doesn’t include implementation, code or schema review, debugging, or the design of your application’s internals.
Calls
The engagement includes four video calls:
- Kickoff call (60 minutes). We confirm your requirements, your environment, and how we’ll work together.
- Document review call (60 minutes). We go through the playbook with your team. This call happens within one week of delivery.
- Two support calls (30 minutes each). These are typically used to discuss the more complex aspects of the playbook. You can use these any time in the 30-day support period.
Unused calls expire at the end of the support period.
30 days of support included
The 30 days start the day after we deliver the playbook. Support covers questions about the playbook: what a section means, why we recommended an approach, and how it applies to a specific issue you have.
You can ask questions as comments in the Google Doc or by email. We respond within one business day. You also have the two support calls.
We keep the playbook updated during this period as things are clarified.
How it works
- Book a call.
- On the initial call, we’ll find out what data you need from Xero and what you need to send to it. We’ll check the Xero API can do it before we quote.
- If it’s a good fit, we’ll send an invoice and schedule a kickoff call.
- On the kickoff call, we’ll confirm your requirements, your environment, and how we’ll work together.
- Data discovery. You send us examples of the data you need, e.g. the reports or spreadsheets you use today, and we confirm where each piece of data lives in Xero. We recommend giving us read-only access to your Xero organisation for this. You can send a data export instead, but it may not contain everything we need to give a proper assessment.
- We’ll send you the playbook within 10 business days of completing data discovery.
- Within one week of delivery, we’ll have a call to go through the playbook with your team.
- Your team builds from the playbook, with 30 days of support from us.
What’s included
Analysis of your integration
We assess your requirements, confirm where the data lives in Xero, and recommend approaches for authentication and data transfer that fit your build.
Your customised playbook
A shared Google Doc written for your requirements and environment, delivered within 10 business days of data discovery and kept updated through the support period.
Four video calls
A 60-minute kickoff, a 60-minute document review with your team, and two 30-minute support calls to use any time in the support period.
30 days of support
Ask questions as comments in the Google Doc or by email, with a response within one business day, starting the day after delivery.
Price
$3,500 AUD ex GST
FAQ
Xero’s API documentation has grown over time and become harder to follow. The playbook gives your developers a single thread to follow, tailored to your requirements and environment. It connects the relevant parts, from authentication and data queries to error handling and testing.
Start by identifying the data you need to move, which direction it needs to travel, and how often it needs to update. Then confirm the Xero API supports those requirements. Our playbook takes you through these decisions and provides guidance on authentication, data transfer, rate limits, error handling, and testing for your environment.
Our customised Xero Integration Playbook costs $3,500 AUD excluding GST. This includes a playbook written for your requirements and environment, four video calls, and 30 days of support. Implementation is priced separately.
We need to understand your application, your environment, and the data you want to move between your system and Xero. Examples of your current reports or spreadsheets help us confirm exactly what you need.
It includes sample API calls and pseudocode to explain the recommended approaches. Your developers handle implementation, adapt the examples to your application, and use the testing checklist to verify their work.
You get 30 days of support starting the day after delivery. Your team can ask questions by email or in the Google Doc, with a response within one business day. Two 30-minute support calls are also included.
It depends on whether your integration is for a single organisation or many, and where it runs. For most single-organisation integrations, the standard authorisation code flow with a stored refresh token is right, but the details of token storage and refresh are where implementations go wrong. The playbook specifies the flow for your situation and exactly how to handle the token lifecycle in your environment.
For most transactional data types, voiding or deleting a record updates its modified timestamp, so it shows up in your next incremental sync (using If-Modified-Since) with a status of VOIDED or DELETED. Your sync needs to treat those statuses as delete markers and update or remove the record in your own data store, rather than only handling new and changed records. Some data types are removed without leaving a delete marker, and those need a periodic reconciliation pass instead.
Xero enforces per-minute, per-day, and concurrent request limits per tenant, plus an app-wide minute limit. Your integration ideally needs to avoid these limits or intelligently handle throttled responses. The playbook includes a bulk ingest design that stays within the limits and degrades sensibly when it hits them.
Yes. The guidance is language-agnostic and the pseudocode is written to be implemented in whatever your team uses. The environment-specific parts, like token storage and background processing, are written taking your environment into account.
That’s fine, and it’s common. The kickoff call covers what you’ve built so far, and the playbook addresses the gaps and any parts worth reworking before they cause problems.
Yes, but that’s a separate engagement with its own scope and pricing. The playbook is the first step. Book a call and we’ll work out which path fits.
Ready to start?
Book a call and we’ll confirm the playbook fits what you’re building.