A structured guide tailored to your Xero integration, for your developers to build from independently.
If your developers can build the integration themselves but need guidance on the Xero API, we’ll write a playbook for their project.
The Xero Integration Playbook is a structured guide tailored to your requirements and environment. Your team uses it to design, build, test and deploy the integration independently, with calls and support for questions about the document.
It covers authentication, efficient data queries, incremental and bulk data transfer, rate limits and error handling, based on our experience building and maintaining Xero integrations.
The playbook is delivered within 10 business days of data discovery, for a fixed price, for any programming language.
Who is this for?
Development teams who want a guide for the Xero parts of their project and can take responsibility for the design and implementation.
We’ll connect the relevant API guidance to your requirements, e.g. which data to query and how to keep it updated. If you need someone working alongside your developers on the project, see Xero Integration Partner.
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
Your team is responsible for application design, implementation, testing and deployment. Code and schema reviews, debugging, and working sessions on your build can be quoted as a Xero Integration Partner engagement.
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). Use these to ask about the playbook’s explanations and recommendations during the 30-day support period.
Unused calls expire at the end of the support period.
30 days of support for playbook questions
The 30 days start the day after we deliver the playbook. Support covers clarification of the document, e.g. what a sample API call does or why we recommended an incremental sync for the requirements we agreed.
If a question needs us to inspect your code, investigate a bug, review your design or work through new requirements, we’ll discuss a separate Xero Integration Partner engagement with you and quote before starting that work.
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’ll update the document as we clarify guidance for the agreed requirements.
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 independently, with 30 days to ask questions about the document.
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 playbook support
Ask about the document’s explanations and recommendations in the Google Doc or by email. We respond 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 to ask questions about the playbook by email or in the Google Doc, with a response within one business day. Two 30-minute support calls are also included. Code review, debugging and advice on new requirements can be quoted separately as Xero Integration Partner.
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.
We can write a playbook for the requirements you’re still working on. The kickoff call helps us understand your progress and agree what the guide will cover. If you need a review of your existing design or code, we can quote for Xero Integration Partner.
Yes. We can build an integration with your existing software. For software products, we can help refine how your product will interact with Xero, then design, build and test the integration and assist with App Store listing. That work has a separate scope and fixed-price quote. See our Xero integration services for the options.
Ready to start?
Book a call and we’ll confirm the playbook fits what you’re building.