Laravel Xero Laravel Package

Product Decisions This Supports

• Build vs. buy for finance features. This package is the "buy/integrate" lever for anything accounting-shaped: invoicing, contacts, payments, credit notes, bank transactions, and reporting. If your roadmap includes "let customers see their Xero invoices" or "push invoices into their ledger," this is the shortest path — it removes the need to model double-entry accounting, tax handling, or reconciliation in your own product.
• Where the integration boundary sits. The v1.1.18 change (dropping accounting.transactions from default scopes) forces an explicit product decision: which finance capabilities are core to your app versus optional per-tenant. That maps directly onto feature-flag and permission design — a tenant that connects Xero for contacts-only sync should not be asked to grant transaction access.
• Onboarding and consent design. OAuth scopes are user-facing product surface. A narrower default scope set means a less intimidating consent screen and higher connect completion rates; it also means you must own a "request more access later" flow inside the product rather than relying on a single up-front grant.
• Roadmap sequencing. If accounting sync is a differentiator, budget for: connection management UI, re-consent/re-auth handling after scope changes, token refresh resilience, and data-freshness expectations (Xero rate limits and webhook latency shape what you can promise customers).
• Data ownership and trust positioning. Connecting a customer's ledger is a security and compliance conversation (SOC 2 questions, data-processing terms). The package gives you the plumbing, not the posture — treat that as a parallel workstream, not an afterthought.

When to Consider This Package

Consider it when:

• You're on Laravel/PHP and already comfortable with the framework's auth, config, and queue conventions — the package leans on them rather than fighting them.
• Your target customers use Xero as their system of record, which in practice means UK, Australia, New Zealand, and Ireland-heavy segments. This is a market-segmentation decision as much as a technical one.
• You need read or write access to invoices, contacts, payments, or reports — the bread-and-butter surfaces — rather than deep, real-time ledger manipulation.
• You want multi-tenant "connect your own Xero org" flows, where each customer authorizes their own account.
• You're validating demand and want the integration live in days, not a quarter, before committing to a bespoke finance data layer.

Look elsewhere when:

• Your customers are predominantly US-based on QuickBooks or NetSuite — the integration is wrong for the market, regardless of code quality.
• You need high-frequency, near-real-time sync. Xero's API rate limits and webhook characteristics cap how fresh your data can be; if the product promise is live dashboards, design around polling windows and communicate staleness honestly.
• You need payroll or deep inventory/manufacturing capability, which sits outside the core accounting API surface.
• You want to own the ledger. If double-entry accounting is your product, a client library to someone else's ledger is a dependency, not a foundation.
• You need committed API stability guarantees with enterprise SLAs. A community-maintained package is excellent value but you are the support tier.

On v1.1.18 specifically: the version number says patch, the behavior says breaking. Any existing install that relies on default scopes to create or read invoices and bank transactions will start failing authorization after upgrade. Treat it as a minor-version upgrade with a migration task: audit configured scopes, add accounting.transactions explicitly where transaction features exist, and verify the re-consent path for already-connected tenants. If you don't use transaction endpoints, the change is a net win — smaller blast radius, cleaner consent screen, better security review answers.

How to Pitch It (Stakeholders)

For executives: Customers keep their books in Xero. Rather than rebuilding accounting — a multi-year, heavily regulated effort — we integrate with the ledger they already trust. This package gives us that integration on our existing stack, which means finance-adjacent features ship in weeks instead of quarters, with no new headcount and no new platform to operate. The trade-off is dependency on a third-party API and its limits, which we should state plainly rather than discover in production. The latest release narrows the permissions we request by default; that's good for trust and conversion on the connect screen, and it costs us one round of scope auditing before rollout.

For engineering: It's a thin, conventional Laravel wrapper — service provider, config-driven credentials, OAuth2 handling, token storage and refresh. Fit is good if we stay inside Laravel's idioms. Three things to plan for: (1) v1.1.18 removes accounting.transactions from defaults, which is behaviorally breaking despite the patch version — audit our scopes and add it explicitly wherever we touch invoices or bank transactions; (2) we own the re-consent flow for tenants who connected before a scope change; (3) rate limits and webhook latency are product constraints, so data freshness needs to be a designed, visible property, not an implicit promise. Wrap the client behind our own interface so a future swap — or a second provider — isn't a rewrite.

For product and design: Scope requests are UX. Users see them at connect time and hesitate over anything that looks like write access to their books. Narrow defaults plus just-in-time escalation ("connect invoicing to enable this") will outperform a single broad permission grab, and it gives us a clean upsell moment inside the product. Also plan the unhappy paths explicitly: revoked access, expired tokens, an org that disconnects mid-quarter. Those states are where finance integrations earn or lose customer trust.