Integration
Xero + Bastle
What syncs from Xero, what it makes possible, and how to connect it.
This connector works and can be connected today, with edge cases still being closed. Check the first month against the source before you rely on it.
What does the Xero integration do?
What syncs
Bastle reads the following from Xero and normalises it into the same entities every other source produces. Ingestion is read-only: nothing is created, changed or cancelled upstream.
- Contacts → customers.
- Repeating invoices → subscriptions, with their schedule as the billing interval.
- Paid accounts-receivable invoices → charges, in integer cents.
- Credit notes → refunds.
- Change notifications from Xero webhooks, verified by signing key.
- Cadence: webhook-driven for changes; historical import run manually today.
Once connected
What Xero data unlocks
Connecting a source is not the point; what you can answer afterwards is. These are the questions this data makes answerable.
Recurring revenue from a ledger
Repeating invoices carry a schedule and an amount, which is enough to compute MRR for a business that bills by invoice rather than by card.
One picture across mixed billing
Enterprise contracts invoiced through Xero and self-serve subscriptions billed through a processor become sources in the same workspace, feeding one MRR figure.
Multi-organisation awareness
Xero scopes access per tenant, and Bastle pins a source to a specific organisation, so a bookkeeper with access to several clients cannot accidentally point a workspace at the wrong ledger.
Setup
Connecting Xero
The whole flow, start to first chart. No implementation call and no data engineer.
- Create an OAuth2 app in the Xero developer portalRequest the offline access, transaction read and contact read scopes — read scopes are sufficient because Bastle never writes.
- Authorise and select the organisationThe OAuth flow returns a refresh token and a tenant id identifying which Xero organisation the source reads.
- Configure a Xero webhookPoint it at /api/webhooks/xero and store the signing key in Bastle so deliveries can be verified.
- Plan for refresh-token rotationXero rotates the refresh token on every exchange, with a short grace window on the old one. Bastle logs the replacement; storing it is manual today.
Repeating invoices as subscriptions
Xero's repeating invoice is the nearest equivalent to a subscription: it has a customer, a schedule and an amount. Bastle maps it to a subscription and treats paid accounts-receivable invoices as the charges against it. Draft and voided invoices are ignored — a draft is an intention, not revenue.
Token rotation, again
Xero rotates the refresh token on every single exchange and the previous token stays usable only briefly. The connector surfaces the new token in its run log so an operator can store it. This is the same operational rough edge as QuickBooks and it has the same fix pending.
Scope your credentials down
The connector needs read access to transactions and contacts, plus offline access to refresh. It never needs write scopes, and granting them buys you risk with no capability in return.
What "beta" means here
The connector is written and the inbound webhook route verifies signatures and writes normalised rows, so a connected account keeps up with changes as they happen. What is not self-serve yet is the historical backfill: the code that walks your provider's API from the beginning exists in the connector, but the scheduled runner that triggers it is still a stub, so first-time imports are run by hand with us. Expect to email someone once during setup, and expect that to stop being true.
Bastle is free while in beta, connectors included. There is no tier that unlocks a provider.
Related
Other sources
Companies billing through Xero usually have at least one of these in the stack too.
- QuickBooks OnlineBetaThe QuickBooks Online integration reads accounting actuals through the Accounting API v3, treating recurring invoices as subscriptions and paid invoices as charges. It exists to bring booked revenue alongside billing-system revenue, so a forecast can be built on what the books say rather than on what the payment processor reports.
- StripeBetaThe Stripe integration turns a Stripe account into Bastle's subscription data model: prices become plans, subscriptions carry their add-ons and discounts, and charges carry the Stripe fee from the balance transaction. Ongoing changes arrive over a signature-verified webhook endpoint within seconds of happening in Stripe, so MRR, churn and failed-payment state track the billing account rather than a nightly export.
- Universal APILiveBastle's write API accepts subscription data from any billing system, including one you built yourself. A single batched import endpoint upserts plans, customers, subscriptions, charges and refunds against your own external ids, and a read API returns the same metrics the dashboard renders. It is available today, self-serve, with scoped API keys.
- WebhooksLiveBastle sends outbound webhooks for subscription, charge, trial and dunning events derived from every connected source, signed with an HMAC header and retried on a backoff schedule across roughly fourteen hours. Endpoints subscribe with exact event types or wildcard patterns, and delivery history is visible in settings. This is shipped and self-serve today.
Xero and Bastle: common questions
Which Xero scopes does Bastle need?
How does Bastle handle multiple Xero organisations?
Are draft invoices counted as revenue?
Do I still need my billing system connected?
Connect Xero and see your own history.
Bastle backfills what Xero will serve, then keeps current over webhooks — usually a couple of minutes before the first real chart. Free while in beta, no card required.