DEV Community: Apideck

Xero Scopes: What Changed and What It Means for Your Integration

Kate Apideck — Fri, 24 Jul 2026 09:29:40 +0000

Xero has replaced two broad OAuth 2.0 scopes with a set of fine-grained scopes that limit each app to only the specific endpoints it needs. If you created your Xero app on or after March 2, 2026, the old broad scopes are simply not available to you. If your app predates that cutoff, you have until September 2027 to migrate.

This is part of a larger restructuring of the Xero developer platform that also includes new API pricing tiers and premium-gating of the Journals endpoint. The scope changes themselves are a genuine security improvement. But combined with the pricing changes, they create real planning work for any team building on Xero.

What exactly changed

Two broad scopes are being deprecated: accounting.transactions and accounting.reports.read.

Before and after: transaction scopes

Before (deprecated)	After (granular)	Endpoints covered
`accounting.transactions`	`accounting.invoices`	Credit notes, invoices, linked transactions, purchase orders, quotes, repeating invoices, items
`accounting.transactions`	`accounting.payments`	Batch payments, overpayments, payments, prepayments
`accounting.transactions`	`accounting.banktransactions`	Bank transactions, bank transfers
`accounting.transactions`	`accounting.manualjournals`	Manual journals
`accounting.transactions`	`accounting.classicexpenses`	Expense claims, receipts (deprecated endpoint)

Each granular scope also has a .read variant for read-only access. So if your app only needs to pull invoice data without writing, you request accounting.invoices.read instead of the full scope.

One detail worth noting: the items endpoint is available via both the accounting.invoices and accounting.settings scopes. If your app only works with items and not invoices, you do not need the invoices scope.

Before and after: report scopes

Before (deprecated)	After (granular)	Reports covered
`accounting.reports.read`	`accounting.reports.aged.read`	Aged Payables by Contact, Aged Receivables by Contact
`accounting.reports.read`	`accounting.reports.balancesheet.read`	Balance Sheet
`accounting.reports.read`	`accounting.reports.banksummary.read`	Bank Summary
`accounting.reports.read`	`accounting.reports.executivesummary.read`	Executive Summary
`accounting.reports.read`	`accounting.reports.profitandloss.read`	Profit and Loss
`accounting.reports.read`	`accounting.reports.trialbalance.read`	Trial Balance
`accounting.reports.read`	`accounting.reports.taxreports.read`	GST and BAS reports

Scopes that are not changing

accounting.contacts, accounting.settings, accounting.attachments, and accounting.budgets remain available to every app regardless of when it was created. Non-Accounting API scopes like Payroll, Files, Assets, Projects, and the Finance API are also unaffected.

The two-track timeline

This is the most important detail for development teams to understand.

Apps created before March 2, 2026 can continue using the broad accounting.transactions and accounting.reports.read scopes until September 2027. During the transition, these apps can use a mix of broad and granular scopes simultaneously. Scopes are additive, so a user who re-authorizes receives both the legacy and new scope grants on their token.

By end of April 2026, Xero will assign the new granular scopes to all existing apps in the developer portal. But these will not automatically propagate to existing tokens. You need to update your authorization URL to request the granular scopes, and each connected user must re-authorize to receive the new permissions. There is no silent migration path. Explicit user consent is required for every connection.

Apps created on or after March 2, 2026 have no access to the broad scopes at all. Their authorization links must specify only granular scopes from day one. If a new app calls an endpoint without the matching granular scope, the API returns HTTP 401 Forbidden with an insufficient_scope error. If you are setting up a Xero app for the first time, you will only see the new granular scopes in the developer portal.

Journals, manual journals, and bank feeds: three different things

This is where the changes get most confusing, because three closely related concepts are governed by entirely different access regimes.

Manual journals (the /api.xro/2.0/ManualJournals endpoint) remain available at all pricing tiers under the new accounting.manualjournals granular scope. This endpoint handles user-created journal entries and is not restricted beyond requiring the correct scope.

The Journals endpoint (/api.xro/2.0/Journals) returns system-generated double-entry journal lines for every transaction in the ledger. This endpoint is now a premium feature gated behind the Advanced pricing tier, which starts at $1,445 AUD per month. Access requires both a security assessment and explicit use-case approval from Xero. If your integration depends on full ledger reconciliation or audit trail functionality, this is the endpoint that matters, and it now comes with a significant cost.

Bank feeds operate under their own separate API and scope (bankfeeds), which is not affected by the accounting scope changes at all. The Bank Feeds API has its own certification requirement and separate contractual terms. If your app only pushes bank statement data into Xero, the accounting.transactions deprecation does not impact you.

Bank transactions, meaning the read and write endpoints for reconciled bank line items within Xero's ledger, move from the old broad scope to accounting.banktransactions. This is distinct from bank feeds. Bank feeds push raw statement data in. Bank transactions are the resulting accounting records inside Xero.

What you need to do

If you have an existing Xero integration, the migration path follows a few steps.

Update your authorization URL to replace the broad scopes with the specific granular scopes your app actually needs. Only request the scopes you use. Requesting everything defeats the purpose and will make users hesitant to authorize.

Let new users authorize with the new scopes naturally. For existing connected users, let re-authorization happen organically when users add new organizations or refresh their connection. The additive scope behavior means users accumulate both scope sets during the transition.

Before September 2027, migrate any remaining connections that still only have broad scopes. For holdouts, you can force re-authorization by removing their connection via the API, which requires them to reconnect with the new scopes.

For testing, create a new app in the Xero developer portal. It will default to granular scopes and can be tested against a Demo Company. No SDK changes are needed since the scopes operate at the OAuth authorization layer.

If you are building a new integration from scratch, you start with granular scopes by default. Plan your scope requests carefully based on which endpoints you actually need.

If you are using Apideck to connect to Xero, you can configure which scopes your app requests in the Apideck dashboard. Our Xero connector setup guide walks through entering your OAuth credentials and reviewing the scopes granted in Xero against the scopes you are requesting in Apideck.

The bigger picture

The granular scope change fulfills a long-standing feature request on Xero's UserVoice forum, where developers have been asking for finer-grained permissions since at least 2010. For years, requesting invoice access also exposed bank balances and salary data because there was only one broad scope covering all of it. Fine-grained permissions are a real improvement.

But the timing is not great. Xero bundled this change with connection-based pricing tiers and premium-gating of key endpoints like Journals. For developers who have been building on the platform for years with free API access, the combined effect feels like a significant shift in the economics of building on Xero.

This is part of a broader pattern across accounting platforms. As we covered in our overview of accounting API pricing and partnerships, every major provider is evolving its developer program in a direction that adds cost and complexity. QuickBooks has its own partnership requirements. Sage remains free but has a smaller market footprint. NetSuite charges separately through its SuiteCloud licensing.

For teams building accounting integrations that need to support multiple platforms, the platform-specific scope and pricing changes reinforce the case for abstracting away provider differences. Whether you build direct integrations or use a unified API layer, the goal is the same: insulate your product from the policy changes of any single platform.

Key resources

Xero's developer blog post on the scope changes: Upcoming changes to Xero Accounting API Scopes

Xero's full scope reference documentation: OAuth 2.0 Scopes

For a detailed breakdown of the pricing tiers that accompany these scope changes: Xero API Pricing and the App Partner Program

For teams evaluating alternatives alongside Xero: Top 15 Accounting APIs to Integrate with in 2026

For a broader look at the Xero integration landscape: Xero Integrations: The Complete Guide for 2026

What Is ERP Banking? The Shift From Portal to Platform

Kate Apideck — Mon, 20 Jul 2026 20:40:53 +0000

Every morning, in corporate finance offices around the world, a treasurer logs into one system to check bank balances, switches to another to initiate payments, then copies data into a spreadsheet to reconcile the general ledger. Nobody designed this workflow. It emerged from decades of banks and accounting platforms evolving independently, and finance teams filling the gaps with manual effort.

ERP banking is the fix. The idea is simple: instead of making business customers toggle between a bank portal and their accounting software, you embed the banking services directly inside the ERP or accounting system. Payments, balances, reconciliation, cash reporting. All from the same environment where the rest of the financial work happens.

The term comes from analyst firm Datos Insights. Their definition: ERP banking is a model where corporate clients access and execute banking capabilities directly from their enterprise systems. The bank becomes invisible infrastructure. The customer never leaves their system of record.

ERP banking is not ERP for banks

There is a naming collision worth clearing up.

Search for "ERP banking" and most results describe ERP software used by banks for their own internal operations. SAP for a bank's back office. Oracle for a bank's financial reporting. That is a different topic entirely.

ERP banking as Datos Insights defines it, and as the commercial banking industry uses the term, describes the opposite direction. Banking services flow into the customer's ERP. The bank is the service provider. The ERP is the destination. One is a procurement decision for the bank's IT department. The other is a product strategy for the bank's commercial banking division.

Why this is happening now

Corporate treasurers are already voting with their feet. Datos Insights surveyed over 1,000 corporate users across 11 countries and found that integration with internal ERP systems is the top priority for corporate treasurers. More than one in four said they would likely switch their primary bank within two years over better technology integration from a competitor. A Nine Wave survey put it more starkly: 85% of CFOs would switch banks for direct ERP-to-bank connectivity. These are not hypothetical preferences. They are already driving churn.

The same Datos Insights research found that 58% of businesses already use a fintech for a core cash management or treasury service. Every payment that runs through a fintech instead of a bank is revenue the bank loses. ERP banking is how banks respond: by meeting the customer inside the system where financial decisions actually get made, rather than waiting for them to log into a portal.

Open banking regulations in Europe (PSD2), the UK, and increasingly the US (Section 1033) forced banks to build API capabilities for consumer data access. Those same APIs now serve ERP integration use cases. The plumbing exists. The question is who builds the last mile into the accounting system.

How it works technically

ERP banking connects a bank's core systems to the customer's ERP or accounting platform. The goal is bidirectional data flow: the bank pushes transaction data and balances into the ERP, and the ERP sends payment instructions back to the bank.

Datos Insights identifies five connectivity methods, roughly in order of maturity:

File-based transfers using SFTP, BAI2, MT940, and ISO 20022 are the oldest method and still the most common at many institutions. The bank generates a file, uploads it to a server, and the ERP picks it up on a schedule. Reliable but slow. No real-time error handling. Frequent format mismatches between bank and ERP.

Host-to-host connections are direct, dedicated links between a bank and a corporate customer's systems. Common in large enterprise relationships. Expensive to set up and maintain, which makes them impractical for mid-market customers.

Bank APIs are the foundation of modern ERP banking. The bank publishes RESTful endpoints that the ERP or a middleware provider can call to retrieve balances, initiate payments, and pull transaction history. J.P. Morgan, HSBC, Deutsche Bank, PNC, and TD Bank all offer this kind of API access for corporate clients.

ERP gateways and feeds are native connectivity features built into the ERP platforms themselves. Oracle Fusion Cloud ERP supports direct bank API integration from J.P. Morgan as a built-in capability. SAP has similar gateway functionality.

ERP banking connectors are pre-built plugins from middleware providers like FISPAN. They connect a bank's services directly into specific ERP platforms. FISPAN's connector works with Oracle NetSuite, Sage Intacct, Microsoft Dynamics 365, QuickBooks Online, and Xero. The bank partners with FISPAN. The customer installs the connector. No custom development required.

These methods are additive. A bank typically supports several simultaneously because its customer base spans different platforms and company sizes. A Fortune 500 on SAP might use host-to-host. A mid-market company on NetSuite uses an ERP banking connector. A small business on QuickBooks uses a bank feed.

What it does for the customer

The use cases span the full commercial banking value chain. For a detailed breakdown with examples from J.P. Morgan, HSBC, Bank of America, Deutsche Bank, and others, see our companion post on accounting and ERP integration for banks. Here is the summary.

Payment initiation is the most visible use case. The customer creates a payment run inside their ERP and the bank processes it directly. No portal login required. TD Bank supports this for NetSuite, QuickBooks Online, Sage Intacct, and Dynamics 365 Business Central through its embedded banking product.

Bank feeds and transaction sync follow closely. The bank pushes transaction data into the customer's accounting system automatically. Challenger banks like Allica Bank and Monzo have turned this into a competitive differentiator, offering free integration with Xero, QuickBooks, and Sage as part of their business banking products.

Cash position reporting pulls balance and transaction data from all banking relationships into a single treasury management system or ERP dashboard. No more logging into five different bank portals every morning.

Automated reconciliation matches bank transactions against ERP records automatically. Exceptions get flagged for review. The line-by-line manual matching goes away.

Expense sync lands corporate card transactions in the customer's accounting platform without anyone touching a spreadsheet. J.P. Morgan's Touchless Expense program and Cross River (powering Divvy/Bill.com) both work this way.

Credit underwriting from accounting data connects banks and lenders to a business's accounting system through an API to pull real-time P&L, cash flow, and accounts receivable data. Plaid and Datos Insights found that 60% of US small business lenders now use some form of account data in their underwriting process.

Who is building it

The market has three layers.

Banks with direct integrations

J.P. Morgan is furthest along. It became the first bank with direct integrated banking for Oracle Fusion Cloud ERP, and also partnered with FISPAN for its Treasury Ignition product covering NetSuite, Sage Intacct, and Dynamics 365. Over 1,000 corporates are live on Treasury Ignition.

TD Bank launched its Embedded Banking product with FISPAN across four ERP platforms. HSBC and Deutsche Bank both partnered with FinLync for SAP connectivity. PNC, Citizens, KeyBank, Wells Fargo, BMO, and Santander all have FISPAN partnerships. BMO launched BMO Sync in early 2025 as the first fully embedded banking solution from a Canadian bank.

Middleware and connector providers

FISPAN is the clear market leader. Founded in 2016, it now has over 4,500 businesses on its platform processing more than $100 billion in annual payment volume. The company raised a $30 million Series B in mid-2025 from Canapi Ventures. Sage named FISPAN its recommended bank feeds solution for Sage Intacct, and over 1,000 businesses are now active on that integration alone, with adoption growing 118% year-over-year.

FinLync focuses on the enterprise SAP segment. Cobase provides multi-bank connectivity for European corporates. Fides connects to over 13,000 banks globally for treasury connectivity.

Unified API providers

For banks that need to connect to many accounting and ERP platforms at once, a unified API provides a single normalized interface that maps to multiple downstream systems. Instead of building separate integrations for QuickBooks, Xero, Sage, NetSuite, Exact Online, MYOB, and Microsoft Dynamics 365, the bank builds one integration and gets connectivity to all supported platforms through a single schema.

Apideck's Accounting API supports 45+ accounting and ERP connectors. The bank's engineering team writes to one API. Apideck handles the platform-specific translation, authentication, and lifecycle management. This approach is particularly valuable for the accounting data side of ERP banking: bank feeds, transaction sync, invoice reconciliation, and credit underwriting all require deep integration with the customer's accounting platform, and each platform has a different API with different data models.

The distinction between middleware connectors and unified APIs matters here. FISPAN and FinLync solve the bank-to-ERP connectivity problem: getting payment capabilities and balance data into the ERP. Unified APIs like Apideck solve the ERP-to-accounting-data problem: reading and writing financial data across dozens of accounting platforms through a single integration. For banks building a full ERP banking stack, both layers come into play.

The market

Datos Insights estimates the ERP banking market at $11 billion to $19 billion, growing at nearly 10% annually.

The retention argument alone justifies the investment. Once banking services are embedded in a customer's ERP workflow, switching banks becomes significantly more disruptive. FISPAN reports that banks on its platform see 30-50% deposit increases from connected clients. And 8% of FISPAN users are net-new to their commercial bank, meaning the embedded banking capability is winning accounts, not just retaining them.

Datos Insights published a separate report specifically on monetizing ERP banking, exploring pricing models from premium connectivity fees to transaction-based billing to value-added bundling within commercial banking packages.

J.P. Morgan's 2026 payment trends report found that 88% of financial professionals consider direct bank connectivity very or extremely beneficial. 85% said they would likely switch banks to get it. At that volume of demand, banks don't get to treat this as optional.

The accounting layer problem

Most of the attention in ERP banking goes to the bank connectivity side. How does the bank's API connect to the ERP platform? That matters, but it is only half the problem.

The other half is the accounting layer. A bank can push transactions into an ERP all day long, but if those transactions do not reconcile against the customer's chart of accounts, match invoices, or flow into journal entries correctly, the integration creates more problems than it solves.

This is where fragmentation hits hardest. Each accounting platform has its own API with its own data model for transactions, its own authentication scheme, its own field naming conventions. A bank that wants to support QuickBooks Online, Xero, Sage Intacct, NetSuite, FreshBooks, and Dynamics 365 needs six different accounting integrations. Building and maintaining those one at a time is expensive. Every engineer working on accounting platform connectors is an engineer not working on core banking products. This is the problem unified accounting APIs exist to solve.

Where this goes

ERP banking is a platform shift in commercial banking, not a feature.

The banks that do it well will become invisible to their customers in the best possible way. The middleware providers and unified API platforms connecting banks, ERPs, and accounting systems are the infrastructure layer making that transition possible.

For any bank evaluating its ERP banking strategy, the demand case is settled. The remaining problem is how to reach broad accounting platform coverage without burning through engineering resources on one-at-a-time integrations. The largest banks can build natively to Oracle and SAP. Everyone else needs the combination of ERP banking connectors for the bank-to-ERP pipe and unified accounting APIs for the accounting data pipe.

Apideck's Accounting API connects to 45+ accounting and ERP platforms through a single integration. If your bank needs to build accounting integrations at scale, get started here.

Bank API Integration: How Banks Connect to Accounting and ERP Systems

Kate Apideck — Wed, 15 Jul 2026 16:11:22 +0000

Banks no longer compete on branch locations or interest rates alone. The fastest-growing differentiator in commercial banking is how well a bank plugs into the accounting and ERP systems its customers already use every day. This shift is often called ERP banking, and it is reshaping how commercial banks compete for business customers.

Bank API integration is the technical bridge that makes this possible. It connects a bank's core systems to third-party accounting platforms, ERPs, and financial applications through standardized interfaces. When done well, it eliminates manual file transfers, enables real-time cash visibility, and turns the bank into an invisible layer inside the customer's existing workflow.

This guide covers how bank API integration works, the use cases driving adoption, the engineering challenges involved, and the approaches available for building and scaling these integrations.

What is bank API integration?

Bank API integration refers to any API-based connection between a bank and a third-party application. The third party is typically an ERP system like Oracle NetSuite or SAP, an accounting platform like QuickBooks Online or Xero, or a fintech application that handles payments, expense management, or treasury operations.

Once the connection is established, financial data flows between the bank and the third-party system on a defined cadence. That data can include transaction records, account balances, payment instructions, invoice details, and reconciliation status.

There are two distinct perspectives on bank API integration, and they matter because the technical requirements differ:

The bank's perspective. A bank builds integrations with accounting and ERP platforms to offer embedded financial services to its business customers. The goal is to reduce churn, win new commercial accounts, and differentiate against competitors who still rely on portal-based workflows. J.P. Morgan, HSBC, TD Bank, and PNC all run embedded banking programs that connect directly into customer ERP environments.

The business's perspective. A company connects its bank accounts to its own accounting or ERP system to automate cash management, reconciliation, and payment workflows. The goal is operational efficiency. Finance teams want real-time visibility into bank balances without logging into separate portals, and they want payment runs initiated from within their system of record.

Both perspectives converge on the same technical problem: connecting bank systems to accounting platforms at scale.

Why APIs beat the alternatives

Banks and businesses have historically relied on four methods to move financial data between systems: manual entry, file-based transfers, screen scraping, and APIs. Here is why APIs are winning.

File-based transfers (SFTP/BAI2/MT940) still dominate in legacy commercial banking. The bank generates a file in BAI2 or MT940 format, uploads it to an SFTP server, and the customer's ERP system picks it up on a schedule. This works, but it introduces latency (often 24 hours), requires manual intervention when file formats change, and creates reconciliation gaps when transactions arrive out of order. File-based integrations also lack real-time error handling. If a payment file contains a malformed record, the entire batch may fail silently.

Screen scraping extracts data from a bank's online portal by simulating user interactions. It breaks every time the bank updates its UI. It also creates security risks because it requires storing and transmitting user credentials. Most banks actively block scraping, and regulatory frameworks like PSD2 in Europe have replaced it with dedicated API access.

APIs solve these problems. They provide structured, authenticated, real-time access to financial data. Authentication is handled through OAuth 2.0 or API keys with scoped permissions. Data is encrypted in transit. Rate limits prevent abuse. And when something fails, the API returns a structured error response that the consuming application can handle programmatically.

The fourth option, manual entry, still exists in small businesses but is not a serious integration method. It does not scale, it introduces human error, and it consumes finance team hours that could be spent on higher-value work.

Types of bank APIs

Not all bank APIs are the same. The access model and scope vary significantly depending on the bank's strategy and regulatory environment.

Private APIs are internal to the bank. They connect the bank's own systems, such as the core banking platform, the online portal, and the mobile app. Third parties cannot access these. They matter for bank API integration only insofar as they constrain what data the bank can expose through its other APIs.

Partner APIs are shared with selected third parties under a contractual agreement. A bank might expose payment initiation and account information endpoints to a specific ERP vendor or fintech partner. FISPAN, for example, partners with banks like J.P. Morgan, PNC, and TD Bank to embed banking services inside ERP platforms through partner API access. These integrations are typically bespoke and require a formal relationship.

Open APIs are available to any authorized developer. In the EU, PSD2 mandates that banks provide open banking APIs for account information (AIS) and payment initiation (PIS) to licensed third-party providers. The UK's Open Banking Implementation Entity defined standardized API specifications that the nine largest UK banks must support. In the US, the CFPB's Section 1033 rulemaking is pushing toward formal consumer data access standards, though the market currently relies more on data aggregators like Plaid and MX than on bank-published open APIs. The Open Banking Tracker tracks 54,000+ financial institutions across 30+ jurisdictions, providing a comprehensive view of which banks offer open API access and under what regulatory framework.

Bank-as-a-Service (BaaS) APIs are a newer category. Companies like Solaris, Column, and Treasury Prime provide full-stack banking APIs that non-bank companies can use to offer financial products. Samsung Pay, for example, runs on Solaris APIs. This is adjacent to traditional bank API integration but follows a different pattern: instead of connecting to an existing bank, the company embeds a bank's infrastructure through APIs.

Use cases driving bank API integration

The market for bank-ERP integration is estimated at $11 billion to $19 billion and growing at nearly 10% annually, according to Datos Insights research. Here are the use cases driving that growth. (For a deeper dive with specific bank examples from J.P. Morgan, HSBC, Deutsche Bank, and others, see our companion post on accounting and ERP integration for banks.)

Bank feeds and transaction sync

This is the most common use case and the foundation for everything else. The bank sends transaction data (debits, credits, balances) to the customer's accounting system automatically. In accounting terms, this is the bank feed.

Challenger banks like Allica Bank and Monzo have turned accounting integration into a competitive weapon for business banking. Allica provides free integration with QuickBooks, Xero, and Sage as part of its Business Rewards Account. Monzo gates accounting integration behind its paid business tiers. Both approaches reflect the same reality: bank feeds are no longer an optional add-on.

For the bank building these integrations, the challenge is supporting the dozen-plus accounting platforms its customers actually use. QuickBooks Online, Xero, Sage Intacct, FreshBooks, Zoho Books, Wave, and Microsoft Dynamics 365 each have different API schemas, authentication flows, and data models for representing transactions.

Payment initiation from ERP

Instead of logging into a bank portal to initiate payments, the customer creates a payment run inside their ERP and the bank processes it directly. TD Bank's Embedded Banking product supports this for NetSuite, QuickBooks Online, Sage Intacct, and Microsoft Dynamics 365 Business Central. Customers can initiate ACH, wire, and check payments without leaving their ERP.

For the bank, this is a retention play. Once payment initiation is embedded in a customer's ERP workflow, switching banks becomes significantly more disruptive. For the customer, it eliminates the dual-entry problem where payment details have to be entered in both the ERP and the bank portal.

Invoice reconciliation

A vendor creates an invoice through their bank, sends it to the customer, and the invoice data syncs to the vendor's accounting system. When the customer pays, the payment data flows back into the accounting system and matches against the outstanding invoice. The vendor's accounting team reconciles without manual intervention.

This workflow requires bidirectional sync between the bank and the accounting platform. The bank needs to push invoice metadata (amount, date, currency, due date) to the accounting system on creation, and then update the invoice status when payment is received.

Corporate card provisioning and expense sync

Banks that offer corporate card programs can integrate with their customers' HR and accounting systems to automate card provisioning. When a new employee is added to the HRIS, the bank provisions a corporate card with spending limits based on the employee's role, department, and location. When the employee is terminated, the card is deactivated automatically.

On the expense side, corporate card transactions sync directly into the customer's accounting platform. J.P. Morgan's Touchless Expense program and Cross River (powering Divvy/Bill.com) both operate this way. The bank pushes categorized transaction data into the accounting system, eliminating manual expense reports.

Credit underwriting from accounting data

This may be the most transformative use case. By accessing a business's real-time accounting data (profit and loss statements, cash flow, accounts receivable aging, and outstanding obligations), lenders can make faster and more accurate credit decisions than traditional methods allow.

Research by Plaid and Datos Insights found that 60% of US small business lenders now use some form of account data in their underwriting process. This is one of the clearest examples of open finance in action: instead of relying on annual financial statements and manual document collection, the lender connects to the business's accounting system through an API and pulls real-time financial data.

For banks building this capability, the integration needs to support read access to the full chart of accounts, journal entries, invoices, bills, and bank transactions across whatever accounting platform the applicant uses.

Cash position reporting

Treasury teams at mid-market and enterprise companies need real-time visibility into cash positions across multiple bank accounts, entities, and currencies. Without an integration, this means logging into multiple bank portals, downloading statements, and consolidating data in a spreadsheet.

With bank API integration, balance and transaction data from all banking relationships flows into a single treasury management system or ERP. Kyriba, for example, connects to over 9,900 banks to provide this kind of unified cash visibility.

The engineering challenge

The use cases are clear. The engineering challenge is what makes bank API integration hard in practice.

Each accounting platform and ERP has its own API with its own data model, authentication scheme, rate limits, and field conventions. A bank that wants to support QuickBooks Online, Xero, Sage Intacct, NetSuite, Microsoft Dynamics 365, and FreshBooks needs to build and maintain six separate integrations.

Each of those integrations involves:

Implementing the platform's authentication flow (OAuth 2.0 for most, but the details vary)
Mapping the bank's internal data model to the platform's schema for transactions, invoices, contacts, accounts, and journal entries
Handling pagination, rate limits, webhook subscriptions, and retry logic
Managing ongoing API version changes, field deprecations, and breaking changes
Testing against sandbox environments, which not all platforms provide equally

Datos Insights research across 1,000+ corporate users in 11 countries found that more than one in four corporate treasurers will likely switch their primary financial institution within two years because a competitor offers better technology integration. The stakes are high, but the engineering cost of building and maintaining integrations one at a time is equally high.

Banks that try to build everything in-house face a painful tradeoff: every engineer working on accounting platform integrations is an engineer not working on core banking products. And the integration surface area keeps growing as new accounting platforms gain market share and existing platforms evolve their APIs.

How unified APIs solve the fragmentation problem

A unified API provides a single normalized interface that maps to multiple downstream platforms. Instead of building separate integrations for QuickBooks, Xero, Sage, NetSuite, and the rest, the bank builds one integration against the unified API and gets connectivity to all supported platforms through a single schema.

This approach works because accounting platforms share a common conceptual model despite differing implementations. Every accounting system has some version of accounts, transactions, invoices, bills, contacts, journal entries, and tax rates. The unified API abstracts over the implementation differences while preserving access to the underlying data.

For banks, the advantages are significant:

Speed. One integration instead of six or twelve. A bank can go from zero accounting platform connectivity to broad coverage in weeks instead of months.

Maintenance. The unified API provider handles downstream API changes, field mapping updates, and authentication flow changes. The bank's engineering team stays focused on its core product.

Coverage. A unified accounting API like Apideck's supports 40+ accounting and ERP connectors through a single integration. As new platforms gain market share, the bank gets access without additional engineering work.

Normalized data. The bank works with a single schema for invoices, transactions, and journal entries regardless of which accounting platform the customer uses. This simplifies downstream processing, reporting, and analytics.

The tradeoff is control. A unified API introduces a dependency and an abstraction layer. Banks that need deep, platform-specific functionality (custom fields, platform-specific workflows, advanced reporting APIs) may find that the unified model does not cover every edge case. The right approach depends on the bank's integration needs, engineering capacity, and the breadth of platforms it needs to support.

Approaches to building bank API integration

There are three primary approaches. Each involves a different set of tradeoffs.

Build native integrations in-house

The bank's engineering team builds and maintains each integration directly against the target platform's API.

This gives the bank full control over data mapping, sync cadence, error handling, and feature depth. It also means the bank can build highly customized integrations that match its customers' exact requirements.

The downside is cost and speed. Building a production-quality integration with a single accounting platform takes weeks to months, and maintaining it is an ongoing engineering commitment. Banks that choose this path typically support only two or three platforms and leave the rest of the market unserved.

Expose API endpoints for customers to build against

Larger banks often publish their own APIs and let customers or their ERP vendors build the integration. This shifts the engineering burden to the customer side.

The bank avoids building and maintaining integrations itself, but the customer experience suffers. Customers may take months to build to the bank's endpoints, and ongoing maintenance falls on their engineering teams. For small and mid-market businesses without dedicated integration engineers, this approach is not viable.

Use a unified API

The bank integrates once with a unified API provider and gets normalized access to multiple accounting and ERP platforms. Apideck's Accounting API, for example, provides a single integration point that connects to QuickBooks Online, Xero, Sage Intacct, NetSuite, FreshBooks, Exact Online, MYOB, and many others.

This is the fastest path to broad coverage and the lowest ongoing maintenance burden. The bank's engineering team writes to one API schema, and the unified API provider handles the platform-specific translation, authentication, and API lifecycle management.

Banks that need to move quickly, support a wide range of customer accounting platforms, and keep their engineering team focused on core banking products should evaluate the unified API approach seriously.

How to evaluate a bank API integration strategy

The right approach depends on several factors specific to the bank's situation.

How many accounting platforms do your customers use? If the answer is two (say, QuickBooks and Xero), native integrations may be viable. If the answer is eight or more, building natively becomes prohibitively expensive.

How fast do you need to go live? If there is competitive pressure to launch ERP-embedded banking quickly, a unified API cuts time-to-market from months to weeks.

What is the depth of integration required? Simple bank feeds require a narrow API surface. Full bidirectional sync with payment initiation, invoice management, and journal entry creation requires deeper integration. Make sure whatever approach you choose supports the data objects and operations your use cases demand.

What is the total cost of ownership? Factor in initial build time, ongoing maintenance, developer hiring, sandbox access fees, and the opportunity cost of engineers not working on core banking products.

Does the provider offer sandbox environments? Testing accounting integrations against live customer data is risky. Sandbox environments with realistic test data are essential for development and QA.

Open banking is not the same thing

Open banking and bank API integration overlap but are not the same thing.

Open banking is a regulatory and industry framework that requires banks to provide API access to authorized third parties. It is driven by regulation (PSD2 in Europe, Open Banking in the UK, Section 1033 in the US) and focuses on consumer data portability and payment initiation. The scope is expanding toward open finance, which extends the same principles beyond payments and accounts to insurance, investments, pensions, and lending data.

Bank API integration is a broader category that includes any API-based connection between a bank and a third-party system. It covers open banking use cases but also extends to ERP integrations, accounting platform connections, treasury management, and embedded banking services that are not mandated by regulation.

A bank can have a robust open banking API program and still lack proper integrations with the accounting platforms its commercial customers use. The two capabilities serve different customer segments and different business objectives.

What comes next

The direction is clear. According to Datos Insights, more than one in four corporate treasurers will likely switch banks within two years if a competitor offers better technology integration. Banks that embrace ERP banking and embed their services inside the accounting workflows their customers already rely on will retain and grow their commercial banking relationships. Banks that force customers to use separate portals and manual file transfers will lose them.

The technical infrastructure to make this work exists today. The question for any bank is whether to build it all in-house, piece by piece, or use a unified accounting API to get there faster.

Apideck's Accounting API connects to 30+ accounting and ERP platforms through a single integration. If your bank needs to build accounting integrations at scale, get started here.

Treasury Accounting: Why Every Fintech That Moves Money Needs ERP Integration

Kate Apideck — Tue, 14 Jul 2026 11:41:04 +0000

Your treasury product is working. Customers are depositing funds, earning yield, and paying bills from a single platform. Cash management has never been smoother.

Then the finance team calls. They need to reconcile treasury activity in QuickBooks. Or NetSuite. Or Xero. And suddenly your product creates more manual work than it eliminates, because there is no clean path from your treasury ledger to their general ledger.

This is the treasury accounting problem. And it is quietly becoming the biggest gap in fintech product stacks.

What treasury accounting actually means

Treasury accounting is the process of recording, classifying, and reconciling all financial activity that flows through a company's treasury function. That includes cash deposits, withdrawals, investment earnings, internal transfers between accounts, and any interest or yield payouts.

For a traditional corporate treasury team, this work happens inside an ERP or dedicated treasury management system. Journal entries are posted for every movement of cash. GL accounts are mapped for each treasury account. The month-end close process depends on this data being accurate and timely.

But the game has changed. A growing number of companies now manage treasury activity through fintech platforms rather than through their bank directly. Spend management tools, neobanks, and vertical SaaS platforms now offer treasury features that let customers sync business account activity and investment earnings into their ERP as journal entries. That is not a nice-to-have feature. It is a prerequisite for adoption by any company with a finance team that actually closes their books.

The reconciliation gap in modern treasury

Here is what happens when a fintech platform handles treasury but does not integrate with accounting systems.

The platform tracks every deposit, withdrawal, and earnings payout internally. The customer's finance team then needs to get that data into their ERP for reconciliation. Without an integration, they are left exporting CSV or OFX files, manually uploading them, and then matching transactions by hand. For companies running multiple treasury accounts with daily activity, this becomes a serious time sink.

The problem gets worse when you add bank feeds into the picture. Bank feeds provide a statement-level view of transactions for matching and verification in the ERP. But the accounting sync creates the actual ledger entries. If both are running but the data does not match cleanly, finance teams end up with duplicate transactions, unmatched entries, and a reconciliation nightmare.

The best implementations address this by building two distinct sync paths: an accounting sync that pushes journal entries into the ERP, and a separate bank feed for statement-level reconciliation. The key detail is that these two paths serve different purposes. The accounting sync creates the book-side records. The bank feed provides the bank-side records for verification. Both are needed, and they should not be confused or combined.

Why this matters for any platform that moves money

If you are building a fintech product that handles customer funds, whether that is a business account, an investment product, a payment platform, or a cash management tool, treasury accounting is your responsibility. Not in the sense that you do the accounting for your customers. But in the sense that you need to give them the tools to account for what happens on your platform.

That means your product needs to support a few things.

First, GL account mapping. Customers need to link their treasury accounts in your product to corresponding accounts in their ERP. A business account maps to one GL account. An earnings or investment account maps to another. Without this mapping, there is no way to automatically post transactions to the right place.

Second, journal entry sync. Cash transfers and earnings payouts should sync into the ERP as proper journal entries, not as generic transactions that need to be reclassified. The more structured the data you send, the less manual work the customer's finance team has to do.

Third, bank feed support. Even with accounting sync, finance teams need a bank-side view for reconciliation. Offering OFX or CSV exports, or direct bank feed connections via Xero or similar providers, gives them the second side of the matching equation.

Fourth, sync controls and visibility. Finance teams need the ability to manually trigger syncs for unsynced transfers, view sync history, and see clear error messages when something fails. This is not just a UX concern. It is an audit concern.

Building treasury accounting with APIs: a practical walkthrough

Let's get concrete. If your platform processes treasury transactions and you want to sync them into your customers' accounting systems, here is what the integration looks like using a unified accounting API.

Step 1: Retrieve the customer's chart of accounts

Before you can post journal entries, you need to know which GL accounts exist in the customer's ERP. The ledger accounts endpoint returns the full chart of accounts so your product can let users map their treasury accounts to the right GL codes.

import { Apideck } from '@apideck/unify'

const apideck = new Apideck({
  apiKey: process.env.APIDECK_API_KEY,
  appId: 'your-app-id',
  consumerId: 'customer-123'
})

// Retrieve the customer's chart of accounts
const { data } = await apideck.accounting.ledgerAccounts.list({
  serviceId: 'quickbooks', // or 'xero', 'netsuite', 'sage-intacct', etc.
  filter: {
    type: 'bank' // filter for bank/cash accounts
  }
})

// Returns normalized ledger accounts across any ERP
// Use these IDs to map treasury accounts to GL codes
for (const account of data) {
  console.log(`${account.nominal_code} - ${account.name} (${account.type})`)
}

This works identically whether the customer uses QuickBooks, Xero, NetSuite, or Sage Intacct. The unified API normalizes the response so your mapping UI does not need ERP-specific logic.

Step 2: Create journal entries for treasury activity

When a deposit, withdrawal, or earnings payout occurs on your platform, post it to the customer's ERP as a journal entry. Each entry needs balanced debit and credit lines.

// Sync a treasury deposit as a journal entry
const journalEntry = await apideck.accounting.journalEntries.create({
  serviceId: 'quickbooks',
  journalEntry: {
    title: 'Treasury Deposit - Business Account',
    currency: 'USD',
    posted_at: '2026-03-15T00:00:00.000Z',
    memo: 'Transfer from linked bank to treasury business account',
    line_items: [
      {
        type: 'debit',
        total_amount: 50000,
        ledger_account: {
          id: 'treasury-business-account-gl-id' // mapped in Step 1
        },
        description: 'Deposit to treasury business account'
      },
      {
        type: 'credit',
        total_amount: 50000,
        ledger_account: {
          id: 'linked-bank-account-gl-id' // source bank account
        },
        description: 'Transfer from operating account'
      }
    ]
  }
})

console.log(`Journal entry created: ${journalEntry.data.id}`)

Step 3: Sync earnings and yield payouts

Investment earnings and yield payouts need their own journal entries, typically crediting a revenue or interest income account.

// Sync an earnings payout from the investment account
const earningsEntry = await apideck.accounting.journalEntries.create({
  serviceId: 'xero', // same code, different ERP
  journalEntry: {
    title: 'Treasury Earnings - Q1 2026',
    currency: 'USD',
    posted_at: '2026-03-31T00:00:00.000Z',
    memo: 'Quarterly earnings payout from investment account',
    line_items: [
      {
        type: 'debit',
        total_amount: 1825.50,
        ledger_account: {
          id: 'business-account-gl-id'
        },
        description: 'Earnings received'
      },
      {
        type: 'credit',
        total_amount: 1825.50,
        ledger_account: {
          id: 'interest-income-gl-id' // revenue/earnings account
        },
        description: 'Investment earnings - money market fund'
      }
    ]
  }
})

Step 4: Push bank feed statements for reconciliation

For ERPs that support bank feeds (like Xero bank feeds), you can push transaction statements directly. This gives the finance team the bank-side view they need to match against the journal entries you posted above.

// Create a bank feed account (one-time setup)
const feedAccount = await apideck.accounting.bankFeedAccounts.create({
  serviceId: 'xero',
  bankFeedAccount: {
    source_account_id: 'your-platform-account-id',
    target_account_name: 'Treasury Business Account',
    target_account_number: '98765432',
    bank_account_type: 'bank',
    currency: 'USD'
  }
})

// Push a bank feed statement with transactions
const statement = await apideck.accounting.bankFeedStatements.create({
  serviceId: 'xero',
  bankFeedStatement: {
    bank_feed_account_id: feedAccount.data.id,
    start_date: '2026-03-01',
    end_date: '2026-03-31',
    start_balance: 100000,
    end_balance: 151825.50,
    transactions: [
      {
        posted_at: '2026-03-15T00:00:00.000Z',
        description: 'Transfer from operating account',
        amount: 50000,
        type: 'credit'
      },
      {
        posted_at: '2026-03-31T00:00:00.000Z',
        description: 'Q1 2026 earnings payout',
        amount: 1825.50,
        type: 'credit'
      }
    ]
  }
})

The finance team opens their ERP's reconciliation module, sees the bank feed transactions, and matches them against the journal entries your platform already synced. No CSV exports. No manual uploads. Books close on schedule.

The integration challenge: every ERP is different

The real complexity is not in the accounting logic. It is in the integrations.

QuickBooks Online, NetSuite, Xero, Sage Intacct, and QuickBooks Desktop all handle journal entries, chart of accounts, and bank reconciliation differently. Each has its own API with different authentication models, data formats, rate limits, and sync behaviors. Some have additional quirks: Microsoft Dynamics 365 Business Central, for example, does not even expose a standalone journal entry object via its API. It uses general journal batches and lines, requiring batch-level posting logic that differs fundamentally from how QuickBooks or Xero handle the same operation.

Building a direct integration to even one of these systems takes weeks of engineering time. Building and maintaining integrations to all of them is a full-time job.

This is where most fintech companies face a strategic decision. Do you build and maintain direct integrations to each ERP? Do you support CSV exports and let customers handle the mapping themselves? Or do you use a unified API that normalizes the differences across platforms?

The first option gives you the most control but the highest maintenance burden. The second option is the cheapest to build but creates the worst customer experience. The third option lets you ship treasury accounting to all major ERPs through a single integration, but it requires choosing the right abstraction layer.

As the code examples above illustrate, the unified API approach means your journalEntries.create call works the same way whether the customer is on QuickBooks, Xero, NetSuite, or Exact Online. The API handles the translation, authentication, and field mapping under the hood. For a deeper comparison of the top accounting APIs, the differences in how each platform handles journal entries and bank feeds become even more apparent.

What good treasury accounting looks like

The gold standard for treasury accounting in a fintech product looks something like this.

When a customer connects their ERP, your platform automatically discovers or creates the relevant GL accounts for treasury activity. Deposits, withdrawals, earnings payouts, and internal transfers each map to specific accounts. As transactions occur, they sync into the ERP as properly coded journal entries with no manual intervention required.

In parallel, the platform provides a bank feed or exportable statement that the customer can use to reconcile the ledger entries against actual account activity. The finance team opens their reconciliation module, sees the matched entries, and confirms them. Month-end close happens on schedule.

When something fails, the customer sees a clear error with a path to resolution. Sync history is downloadable. Unsynced transfers are flagged and can be retried. The finance team has full visibility and control.

This is not a luxury feature. For companies that handle customer funds, this is the bare minimum to serve any customer with a real accounting function.

The bigger picture: treasury is becoming a platform feature

Treasury functionality, which used to live exclusively inside banks and standalone TMS platforms, is increasingly being embedded into fintech products. Spend management platforms, payment processors, neobanks, and vertical SaaS companies are all adding cash management and yield features.

But every one of these products eventually hits the same wall: the customer's finance team needs the data in their ERP. If the integration is not there, adoption stalls. If the integration is manual (CSV exports, copy-pasting), adoption happens but with resentment. If the integration is automated and reliable, treasury features become a genuine differentiator.

The concept of Open Accounting, where businesses expect their financial data to be accessible through standardized APIs regardless of which platform they use, is accelerating this shift. Just as Open Banking standardized access to bank account data, Open Accounting is pushing toward standardized access to ledger data across ERPs and accounting platforms. For treasury platforms, this means the infrastructure to sync journal entries, ledger accounts, and bank feeds across systems is becoming more accessible, but only if you invest in building it.

The companies that figure out treasury accounting early, and invest in proper ERP integrations from the start, will be the ones that capture the most value from this shift. The ones that treat it as an afterthought will keep losing deals to competitors who made accounting sync a day-one feature.

Getting started

If you are building or operating a fintech platform that moves customer money and you have not yet addressed treasury accounting, here is where to start.

Audit your current state. How do customers currently get treasury data into their ERP? If the answer is CSV exports or manual entry, you have a gap to close.

Talk to your customers' finance teams. Not the product buyer, not the admin. Talk to the person who closes the books each month. Ask them what data they need, in what format, and when they need it.

Evaluate your integration strategy. For most platforms, building direct integrations to every ERP is not practical. Look at unified API providers that support journal entries, chart of accounts, and bank transaction objects across multiple accounting platforms.

Start with the big three. QuickBooks Online, Xero, and NetSuite cover the vast majority of small and mid-market companies. If you can sync treasury activity into these three systems, you have addressed 80% or more of your customer base.

Build sync visibility from the start. Do not bolt on error handling and sync history later. Finance teams need to trust the integration, and trust comes from transparency.

Treasury accounting is not a feature request. It is infrastructure. Build it like infrastructure, and it will pay dividends across your entire product.

Related reading:

Disclaimer: Apideck's Unified Accounting API supports journal entries, chart of accounts, bank feeds, and bank transaction sync across QuickBooks, Xero, NetSuite, Sage, and 40+ other accounting and ERP platforms. If you are building treasury accounting features, get in touch or explore the API reference to see how it works.

Multi-Entity General Ledger Integration: What Changes When You Build Accounting APIs

Kate Apideck — Mon, 13 Jul 2026 21:21:31 +0000

Most accounting integrations are built for a single company with a single set of books. You read invoices, write journal entries, sync payments. The chart of accounts has a few dozen line items. Everything maps cleanly to one general ledger.

Then your customer has two subsidiaries. Or five. Or forty, spread across three currencies and two continents. Suddenly you're dealing with subsidiary hierarchies, intercompany eliminations, and consolidation logic that varies by platform. The GL integration you built for a single-entity QuickBooks user doesn't translate to a NetSuite OneWorld customer running twelve legal entities.

This is the part of accounting software integration that most teams underestimate. And it's the part that matters most for the customers with real money on the line.

How multi-entity accounting changes the general ledger

A multi-entity setup means a business operates multiple legal entities that each maintain their own financial records but ultimately roll up into a consolidated view. These entities might be subsidiaries in different countries, regional branches, or distinct business divisions. Each entity has its own general ledger. Each general ledger is organized around a chart of accounts. In simple setups, all entities share the same chart of accounts. In more complex ones, entities have their own accounts tailored to local tax or regulatory requirements, with a mapping layer that connects them for consolidation.

The general ledger is the backbone. Every transaction in an accounting system, whether it originates from AP, AR, or any other module, ultimately generates journal entries with offsetting debits and credits in the GL. Approve a vendor bill and the system records an expense and a liability. Process the payment and it reduces both the liability and cash. In a well-integrated ERP, none of this requires manual posting.

Multi-entity complicates things in ways that compound quickly.

The most obvious challenge is intercompany transactions. When subsidiary A sells goods to subsidiary B, both entities record the transaction in their own books. But from a consolidated perspective, that revenue and cost need to be eliminated so the group financials reflect only external activity. If subsidiary A lent $500,000 to subsidiary B, the receivable on one side and the payable on the other need to cancel out during consolidation. Miss these eliminations and you inflate your consolidated numbers.

Currency translation adds another layer. A subsidiary operating in EUR while the parent reports in USD needs its financials translated at appropriate exchange rates: current rates for monetary items, average rates for income statement items, historical rates for equity. Unrealized gains and losses from open foreign-currency positions need revaluation journal entries at each reporting period.

Then there's dimensional reporting. Beyond the basic account structure, enterprises need to slice financial data by department, location, project, or other custom segments. Each accounting platform handles these "tracking categories" differently, and the way they interact with entity structures varies considerably.

Finance teams at multi-entity companies spend an average of six days per month manually consolidating financial data across entities, according to SoftLedger. NetSuite OneWorld carries a $10,000 to $30,000 annual premium over standard NetSuite specifically because multi-subsidiary management is that complex.

How NetSuite, QuickBooks, Xero, and Sage Intacct model entities

This is where it gets painful for anyone building integrations.

NetSuite OneWorld treats each legal entity as a subsidiary record in a hierarchical tree. All subsidiaries can share a chart of accounts (with optional country-specific accounts), and the system supports up to 250 subsidiaries per account. Intercompany journal entries are a distinct transaction type. NetSuite automatically generates elimination entries during the period close process through its Automated Intercompany Management feature, posting them to dedicated "elimination subsidiaries" that exist solely for consolidation. Advanced Intercompany Journal Entries allow debits and credits across multiple subsidiaries in a single balanced entry.

QuickBooks, by contrast, was built for single-entity accounting. Multi-entity businesses running QuickBooks typically operate separate company files for each entity. There's no native subsidiary hierarchy, no built-in intercompany elimination, no consolidated reporting. A biotech firm called Aviva Biology found that QuickBooks couldn't meet its multi-subsidiary needs after an acquisition, and switched to NetSuite OneWorld to consolidate finances across entities. This is a common migration pattern.

Xero supports multiple organizations under a single user login, but each organization is an isolated instance with its own chart of accounts and data. Consolidation happens outside the system, either through reporting tools like Fathom or through manual spreadsheet work.

Sage Intacct takes a dimensional approach. Rather than rigid subsidiary hierarchies, it uses entities as one of several dimensions (alongside departments and locations) that can be applied to transactions and used for reporting. It supports multiple books per entity for parallel reporting under different accounting standards.

The structural differences run deep. NetSuite has a dedicated subsidiary object type with a parent-child hierarchy. QuickBooks has no entity concept at all in its API. Xero and Sage Intacct each take their own approach: Xero with isolated organizations, Sage with entities as a reporting dimension. These are not cosmetic differences in naming. They represent different data models with different assumptions about how financial information is organized.

How multi-entity affects accounting API integrations

When you're building a product that needs to read from or write to your customers' general ledgers, multi-entity support changes the integration surface area dramatically.

Consider journal entries. In a single-entity QuickBooks integration, you POST a journal entry with line items that include account references and amounts. The QuickBooks API call looks something like this:

POST /v3/company/{realmId}/journalentry

{
  "Line": [
    {
      "Amount": 1000.00,
      "DetailType": "JournalEntryLineDetail",
      "JournalEntryLineDetail": {
        "PostingType": "Debit",
        "AccountRef": { "value": "36", "name": "Checking" }
      }
    },
    {
      "Amount": 1000.00,
      "DetailType": "JournalEntryLineDetail",
      "JournalEntryLineDetail": {
        "PostingType": "Credit",
        "AccountRef": { "value": "96", "name": "Consulting Revenue" }
      }
    }
  ]
}

Straightforward. One company, one set of accounts, one journal entry.

In NetSuite OneWorld, that same journal entry needs to be scoped to a specific subsidiary. If it's an intercompany transaction, you need to use the Advanced Intercompany Journal Entry, specifying both the originating subsidiary and the receiving subsidiary. The payload gets more complex:

// Simplified for illustration
POST /services/rest/record/v1/advInterCompanyJournalEntry

{
  "subsidiary": { "id": "2" },
  "toSubsidiary": { "id": "5" },
  "line": {
    "items": [
      {
        "account": { "id": "210" },
        "debit": 50000.00,
        "subsidiary": { "id": "2" },
        "eliminate": true
      },
      {
        "account": { "id": "315" },
        "credit": 50000.00,
        "subsidiary": { "id": "5" },
        "eliminate": true
      }
    ]
  }
}

Notice the differences: subsidiary scoping on the transaction and on each line item, a toSubsidiary field, and an eliminate flag that tells NetSuite to reverse these entries during consolidation. Your integration code needs to know whether the customer is on standard NetSuite or OneWorld, whether the journal crosses entity boundaries, and which clearing accounts the system expects.

Consider the chart of accounts. In QuickBooks, you call the Account endpoint and get a flat list. In NetSuite, accounts exist in a hierarchy and may be shared across subsidiaries or scoped to specific ones. Sage Intacct combines accounts with dimensional attributes like department and location that determine how transactions are categorized for reporting. Each platform's version of what Xero calls "tracking categories" has a different name and a different data shape, and your integration has to normalize these into a consistent structure or handle each one separately. (For a deeper look at how tracking dimensions vary across platforms, see our guide to tracking dimensions in accounting integrations.)

Consider reporting. A trial balance in a single-entity system is one set of account balances. In a multi-entity system, you need trial balances per entity, a consolidated trial balance with intercompany eliminations applied, and potentially a currency-translated view. The API surface for these reports differs across every platform.

Each integration ends up being its own project. QuickBooks is one data model. Xero is another. NetSuite is a third, substantially more complex model with subsidiary scoping on nearly every API call. Building and maintaining these individually means engineering teams spend a disproportionate amount of time on connector logic rather than core product work. Individual accounting integrations typically cost $3,000 to $15,000 each when you factor in engineering time, infrastructure, and the normalization work required to make financial data consistent across sources.

Using a unified accounting API for multi-entity integrations

Unified accounting APIs attempt to solve this by providing a single normalized interface across multiple platforms. You make one API call for journal entries, one for chart of accounts, one for invoices, and the unified layer translates your request into the native format of whatever platform your customer uses.

This works well for the common case. Standard transactional objects like invoices and payments follow broadly similar patterns across platforms (though the field names and nesting structures differ). A unified API normalizes these into a consistent schema and manages the ongoing maintenance when providers ship breaking changes. It also handles authentication, which varies widely: QuickBooks uses OAuth 2.0 with strict refresh token rotation. NetSuite requires token-based authentication with HMAC-SHA256 signature generation on every request.

Here's what the same journal entry looks like through the Apideck Accounting API:

import { Apideck } from '@apideck/node'

const apideck = new Apideck({
  apiKey: process.env.APIDECK_API_KEY,
  appId: process.env.APIDECK_APP_ID,
  consumerId: 'user-123'
})

const { data } = await apideck.accounting.journalEntriesAdd({
  journalEntry: {
    title: 'Intercompany transfer',
    line_items: [
      {
        type: 'debit',
        ledger_account: { id: '210' },
        total_amount: 50000.00,
        tracking_categories: [{ id: 'subsidiary-2' }]
      },
      {
        type: 'credit',
        ledger_account: { id: '315' },
        total_amount: 50000.00,
        tracking_categories: [{ id: 'subsidiary-5' }]
      }
    ]
  }
})

One call, one data model. The unified layer resolves which downstream platform the customer uses and translates the request into the native format, whether that's QuickBooks, NetSuite, Xero, or any of the 30+ supported connectors.

For multi-entity scenarios, the unified layer needs to do more. It needs to surface entity and subsidiary context on relevant endpoints. It needs to handle tracking categories and dimensional reporting consistently, even when each platform implements them differently. It needs to support journal entries that span entities where the underlying platform allows it, and degrade gracefully where it doesn't.

The Apideck Accounting API handles this through a unified tracking categories endpoint that abstracts the differences between each platform's implementation into a single interface. Rather than learning four different tracking systems with four different names and four different data shapes, developers use one API that works identically across all supported platforms. For subsidiary and entity context, the unified model includes company and organization-level scoping that maps to the native entity model of each downstream provider.

This doesn't eliminate all complexity. A deep NetSuite OneWorld integration with custom intercompany allocation schedules will always require some platform-specific configuration. But for the 80% of use cases where you need to move GL data and transactional records across multiple entities and multiple platforms, the unified approach compresses months of integration work into weeks.

What's next for multi-entity accounting APIs

The multi-entity problem is growing, not shrinking. Cross-border commerce is expanding. Vertical SaaS platforms serving franchise operators and multi-location businesses need to connect with the accounting systems of customers who may operate dozens of entities. Fintech products offering embedded lending or working capital need reliable consolidated financial data to underwrite risk accurately.

At the same time, accounting platforms are investing heavily in their multi-entity capabilities. Intuit launched its Enterprise Suite with multi-entity features aimed at mid-market companies. New entrants like Campfire are building AI-native ERPs with multi-entity consolidation as a first-class feature. NetSuite continues expanding OneWorld's automated intercompany management capabilities.

For integration builders, this means the bar keeps rising. It's no longer sufficient to connect to a single QuickBooks company and call it done. Customers expect their software to understand that they run multiple entities, that those entities have relationships with each other, and that the financial data flowing through the integration reflects the consolidated reality of their business. The GL is not just a list of accounts. It's a hierarchical, multi-dimensional, entity-scoped structure that changes shape depending on which accounting platform you're looking at. Building integrations that handle this well is hard. Using a unified API that has already mapped these differences is the faster path to getting it right.

FAQ

What is multi-entity accounting?

Multi-entity accounting is the practice of maintaining separate financial records for multiple legal entities (subsidiaries, branches, or divisions) within a single organization, while consolidating them into unified financial statements. Each entity has its own general ledger and chart of accounts, and the consolidation process requires eliminating intercompany transactions and translating foreign currencies.

How do accounting APIs handle subsidiaries?

Each accounting platform handles subsidiaries differently at the API level. NetSuite OneWorld requires subsidiary scoping on most API calls and has dedicated intercompany journal entry endpoints. QuickBooks has no subsidiary concept in its API, so multi-entity businesses use separate company files. Xero treats each entity as an isolated organization. A unified accounting API normalizes these differences into a single data model.

What are intercompany eliminations?

Intercompany eliminations are accounting adjustments that remove the effect of transactions between entities within the same corporate group during financial consolidation. If subsidiary A sold $100,000 of services to subsidiary B, that revenue and expense need to be eliminated so consolidated financials only reflect transactions with external parties.

What is a unified accounting API?

A unified accounting API provides a single, normalized interface for integrating with multiple accounting platforms. Instead of building separate connectors for QuickBooks, Xero, NetSuite, and Sage Intacct, developers build once against the unified API, which translates requests into each platform's native format and handles authentication, pagination, and data normalization.

SAP Business One API Integration Guide: Authentication, Endpoints, and OData Queries

Kate Apideck — Fri, 10 Jul 2026 09:51:13 +0000

SAP Business One runs the back offices of over 80,000 small and mid-sized companies worldwide. If you're building software that needs to read invoices, sync customers, or push journal entries into any of those systems, you'll eventually find yourself working with the Service Layer API. It's SAP's REST interface for Business One, and it's both more capable and more quirky than you might expect coming from modern SaaS APIs.

This is a practical walkthrough of what the integration actually looks like: authentication, core endpoints, querying patterns, pagination, and the gotchas that will cost you hours if nobody warns you about them first. If you're looking for SAP's enterprise product instead, see our SAP S/4HANA API integration guide.

What is the SAP Business One Service Layer?

The Service Layer is SAP Business One's OData-based REST API. It sits on top of an Apache HTTP server and talks to the same business object layer that the desktop client uses (the DI Core). That last part matters, because it means the API enforces the same validation rules and business logic as the application itself. You can't create an invoice with a missing required field through the API any more than an accountant could through the UI.

As of Feature Pack 2405, SAP has deprecated OData v3 and made OData v4 the primary protocol. The practical difference: your base URL path changes from /b1s/v1/ to /b1s/v2/, and the JSON response format follows OData v4 conventions (annotations use the @odata. prefix instead of odata.). If you're starting a new integration today, use v2.

Your Service Layer instance runs at a URL like:

https://your-sap-server:50000/b1s/v2/

The port and hostname depend on the customer's deployment. SAP Business One can run on either Microsoft SQL Server or SAP HANA, and the Service Layer works the same way on both. SAP publishes a complete API reference covering every entity and action, along with a detailed Service Layer user manual that covers installation, configuration, and query patterns.

It's worth knowing that the Service Layer is not SAP Business One's only integration path. The DI API is a .NET library for deep server-side access, mainly used by desktop add-ons running on the same machine as the SAP client. The Integration Framework (B1If) is a Java-based middleware layer that lets SAP partners build custom passive REST endpoints and event-driven workflows using XSLT transformations. B1If routes through the DI API on SQL Server deployments and through the Service Layer on HANA. Some partners, like Brazilian consultancy Ogeda & Nietsche, have used B1If to build domain-specific REST APIs (ecommerce, CRM, WMS) that wrap SAP Business One objects in a loosely coupled integration layer. The Service Layer is the right starting point for most external integrations: it's REST-native, requires no middleware installation, and works identically on both database backends.

How to authenticate with the SAP Business One API

This is where the Service Layer diverges from what you're used to with modern APIs. There are no API keys. No persistent bearer tokens. You authenticate by posting credentials and getting a session cookie back.

The login request looks like this:

POST https://your-sap-server:50000/b1s/v2/Login

{
  "CompanyDB": "SBODemoUS",
  "UserName": "manager",
  "Password": "your-password"
}

If the credentials are valid, you get back a 200 response with a SessionId in the body and a B1SESSION cookie in the response headers. Every subsequent request must include that cookie.

In Python, a basic connection using requests looks like this:

import requests

base_url = "https://your-sap-server:50000/b1s/v2"

session = requests.Session()
session.verify = False  # only for self-signed certs in dev

# Authenticate
login = session.post(f"{base_url}/Login", json={
    "CompanyDB": "SBODemoUS",
    "UserName": "manager",
    "Password": "your-password"
})
login.raise_for_status()

# Query customers
customers = session.get(f"{base_url}/BusinessPartners", params={
    "$filter": "CardType eq 'cCustomer'",
    "$select": "CardCode,CardName",
    "$top": 50
})

for bp in customers.json()["value"]:
    print(bp["CardCode"], bp["CardName"])

# Logout when done
session.post(f"{base_url}/Logout")

The key detail: use a requests.Session() object. It automatically persists the B1SESSION cookie across requests, so you authenticate once and every subsequent call reuses the same session. If you create a new requests.post() for each call without a shared session, you'll re-authenticate every time and hit the 5-second overhead on each request.

The session expires after 30 minutes of inactivity by default. You can extend this in the Service Layer configuration (the b1s.conf file) or in the SLD Control Center, but most integrations handle it by catching the 401 response and re-authenticating automatically.

One detail that catches people: the first authenticated request to the Service Layer can take around 5 seconds. Subsequent requests using the session cookie return in roughly 20 milliseconds. This is a well-known behavior in the SAP community, and it means you absolutely need to reuse sessions rather than authenticating per request. If you're running a web application that calls the Service Layer from a backend, implement a session cache that stores the B1SESSION cookie and only re-authenticates when the session expires.

SAP also added OAuth 2.0 and OpenID Connect support starting in version 10.0 FP 2305. This requires configuring an identity provider (SAP IAS or another SAML2-compatible IDP) and is more complex to set up, but it's worth considering if your integration needs to support SSO or if you're building a multi-tenant application where managing per-company credentials gets unwieldy.

SAP Business One API endpoints for accounting data

The API exposes SAP Business One's business objects as OData entities. The ones you'll work with most often in an accounting software integration:

BusinessPartners for customers and vendors. Items for products and services. Orders for sales orders. Invoices for A/R invoices. PurchaseInvoices for A/P invoices. JournalEntries for general ledger postings. ChartOfAccounts for the GL account list.

All of these support standard HTTP methods. A GET to retrieve, POST to create, PATCH to update, DELETE to remove. Here's what creating an invoice looks like:

POST /b1s/v2/Invoices

{
  "CardCode": "C20000",
  "DocDate": "2026-03-15",
  "DocumentLines": [
    {
      "ItemCode": "A00001",
      "Quantity": 10,
      "UnitPrice": 25.00
    }
  ]
}

The CardCode references an existing BusinessPartner. The API validates that the partner exists, that the item code is valid, and that all required fields are present before writing anything to the database. If validation fails, you get a structured error response with the SAP error code and message.

OData query options: filtering, sorting, and joins

OData gives you a consistent query language across all entities. The basics:

GET /b1s/v2/BusinessPartners?$select=CardCode,CardName&$filter=CardType eq 'cCustomer'&$orderby=CardCode&$top=50

This returns the first 50 customers, selecting only the fields you need. The filter operators include eq, ne, gt, lt, ge, le, and, or, plus string functions like startswith() and contains().

You can navigate relationships using OData associations. If you have an order's DocEntry, you can retrieve the associated customer in a single request:

GET /b1s/v2/Orders(7)/BusinessPartner

Aggregation support was added for HANA deployments and uses the $apply query option. You can run sums, averages, counts, and group-by operations directly through the API, which can save you from pulling large datasets just to aggregate on the client side.

The biggest limitation: you cannot join across entities in a single query. Each API call returns data from one endpoint. If you need to correlate invoices with their associated payments, that's two separate requests and a client-side join. For complex reporting queries, SAP requires you to save the query in Query Manager first, then call it through the SQLQueries endpoint. You can't pass arbitrary SQL through the API.

Pagination and page size configuration

The default page size is 20 records. If you request /b1s/v2/Invoices, you'll get back 20 invoices and an @odata.nextLink annotation pointing to the next page.

You have two options for controlling this. Client-driven paging uses $top and $skip:

GET /b1s/v2/Invoices?$top=100&$skip=200

Server-driven paging uses the Prefer header to request a larger page size:

GET /b1s/v2/Invoices
Prefer: odata.maxpagesize=100

The server responds with a Preference-Applied header confirming the page size. You can also set PageSize globally in the b1s.conf configuration file, though this requires Service Layer restart and affects all clients.

Setting odata.maxpagesize=0 disables pagination entirely. This is useful for small reference tables like chart of accounts but dangerous for transactional entities with thousands of records.

Batch operations and atomic transactions

The Service Layer supports OData batch requests through the /$batch endpoint. This lets you bundle multiple operations into a single HTTP request, and operations within a changeset are atomic: if one fails, they all roll back.

This is useful for scenarios like creating an invoice and its payment in a single atomic operation, or bulk-updating inventory across multiple items. The request format uses multipart MIME boundaries, which is ugly to construct manually but well-supported by most OData client libraries.

User-Defined Fields and User-Defined Objects

Almost every SAP Business One customer has customized their instance with User-Defined Fields (UDFs) and User-Defined Tables (UDTs). If your integration ignores these, you'll lose data on every sync.

UDFs are accessible through the Service Layer on the parent entity. A custom field added to BusinessPartners named "CustomerTier" appears in the API response as U_CustomerTier (all UDFs carry the U_ prefix). You can read, write, and filter on UDFs the same way you would any standard property:

GET /b1s/v2/BusinessPartners?$filter=U_CustomerTier eq 'Gold'

User-Defined Tables work similarly but use the U_ prefix on the table name. You access them through a dedicated endpoint:

GET /b1s/v2/U_CUSTOMTABLE

User-Defined Objects (UDOs) go a step further, wrapping UDTs with business logic like find, add, update, and delete operations. The Service Layer exposes registered UDOs as first-class entities, so they behave like any built-in object.

The catch: UDFs, UDTs, and UDOs vary from customer to customer. Your integration needs to discover them at runtime using the /$metadata endpoint or the UserFieldsMD and UserTablesMD entities, rather than assuming a fixed schema. This is one of the more time-consuming parts of building a production SAP Business One integration, and it's a common reason teams choose a unified API approach that normalizes these differences across customers.

Error handling and debugging

The Service Layer returns errors as JSON objects with an error key containing a code and message. The codes come from SAP's DI API layer and carry more diagnostic value than the HTTP status alone. A 400 response might mean a missing required field, a referential integrity violation, or a business logic constraint like trying to post to a closed accounting period.

Some common error patterns worth handling explicitly:

Error code -5002 means the session has expired. Catch this and re-authenticate rather than failing the entire sync. Error code -2028 indicates a locked object, which happens when another user or process has the same record open. The right response is to retry with exponential backoff. Error code -10 is a generic validation failure; the message.value field will contain the specific field and constraint that failed.

Log the full error response body on every failure. SAP support and implementation partners will ask for the error code, the request payload, and the entity path. Without these, troubleshooting becomes guesswork.

For debugging during development, the Service Layer's /$metadata endpoint is indispensable. It returns the full OData schema for every entity, property, and association available in the API. Generate your client code from this schema rather than hard-coding property names, because SAP adds and occasionally renames properties across feature packs.

Production deployment considerations

Session management is the single most important thing to get right. Build a session pool that re-authenticates lazily when the 30-minute timeout hits, and never authenticate per-request. The 5-second authentication overhead will destroy your throughput otherwise.

Handle the CompanyDB parameter carefully. SAP Business One customers often run multiple company databases on the same server. Your session is scoped to a single company database, so if you need to sync data across companies, you need separate sessions for each.

The Service Layer enforces TLS 1.2 or 1.3 and requires a valid X.509 certificate. In practice, many on-premise deployments use self-signed certificates, which means your HTTP client needs to be configured to trust that specific certificate rather than skipping validation entirely.

Because SAP Business One is typically deployed on-premise, your integration also needs to account for network connectivity. Unlike cloud APIs where you can call an endpoint from anywhere, reaching a customer's Service Layer often requires VPN access, IP allowlisting, or a reverse proxy. Some SAP partners deploy a proxy layer in front of the Service Layer to handle session caching and certificate management for external clients. This on-premise reality is one of the main reasons ERP and accounting integrations are more complex than connecting to a cloud-native API like Xero or QuickBooks Online.

The Service Layer isn't the most elegant API you'll ever work with. The session-based auth, the OData conventions, and the on-premise deployment model all add friction compared to a typical cloud API. But it's well-documented, it's functionally complete, and it exposes the full depth of SAP Business One's business logic. For any SaaS company that needs to support SAP Business One customers, understanding the Service Layer is a prerequisite, not an option.

Frequently asked questions

What authentication methods does the SAP Business One Service Layer support?

The Service Layer supports two authentication schemes. Basic authentication uses a username, password, and CompanyDB posted to the /Login endpoint, returning a B1SESSION cookie valid for 30 minutes. OAuth 2.0 with OpenID Connect is available from version 10.0 FP 2305 onward and requires an identity provider like SAP IAS.

What is the default session timeout for SAP Business One Service Layer?

The default session timeout is 30 minutes of inactivity. You can extend this in the b1s.conf configuration file or through the SLD Control Center. Most production integrations handle expiry by catching the -5002 error code and re-authenticating automatically.

Can you use OData v3 and v4 with SAP Business One Service Layer?

As of Feature Pack 2405, OData v3 is deprecated and OData v4 is the primary protocol. OData v3 still works for backward compatibility (use the /b1s/v1/ path), but SAP recommends migrating to v4 (/b1s/v2/) for new integrations.

What is the default page size for SAP Business One API responses?

The default page size is 20 records. You can change this per-request using the Prefer: odata.maxpagesize=N header, or globally by setting PageSize in the b1s.conf file. Setting the page size to 0 disables pagination, which is useful for small lookup tables but risky for large transactional datasets.

How do you handle User-Defined Fields in the Service Layer?

UDFs appear on their parent entity with a U_ prefix. A custom field called "Region" on BusinessPartners becomes U_Region in the API. You can read, write, and filter on UDFs like any standard field. Discover available UDFs at runtime through the UserFieldsMD entity or the /$metadata endpoint.

How to Integrate With the Campfire API

Kate Apideck — Wed, 08 Jul 2026 14:03:22 +0000

Campfire is an AI-native ERP platform built for high-growth startups and mid-market companies that are outgrowing QuickBooks or Xero, or looking for a modern alternative to NetSuite and Sage Intacct. Founded in 2023 and backed by Accel, Ribbit, Foundation Capital, Y Combinator, and Capital49, it offers a general ledger with multi-entity and multi-currency support, revenue recognition, invoicing, close management, and bank reconciliation. The company raised a $35M Series A led by Accel in June 2025, followed by a $65M Series B co-led by Accel and Ribbit just 12 weeks later, bringing total funding past $100M.

If you're building a product that needs to sync accounting data with Campfire, this guide covers two approaches: integrating directly with the Campfire API, and using a unified API like Apideck to build an Campfire Integration (and 40+ other accounting platforms).

What the Campfire API covers

Campfire exposes a REST API organized around its core accounting workflows. The base URL for all requests is https://api.meetcampfire.com, and the full API reference lives at docs.campfire.ai.

The API is split across several resource groups:

Cash management covers bank accounts and bank transactions. You can list, create, update, and delete bank accounts, manage individual bank transactions with full CRUD support, and push bank feed data for reconciliation.

Accounts payable handles bills, debit memos, and payment workflows. Beyond basic CRUD, it includes endpoints for marking bills as paid, voiding bills, reopening voided bills, and bulk searching bills by number.

Accounts receivable includes invoices, credit memos, and payment recording. It supports bulk invoice creation, bulk search by invoice number, voiding, and reopening voided invoices.

Core accounting covers journal entries (single-entity and intercompany), budgets, fixed assets, chart transactions, vendor contacts, and custom dimensions. It also includes bulk search endpoints for departments, vendors, and custom dimensions.

Financial statements gives programmatic access to income statements, balance sheets, cash flow statements, trial balances, general ledger data, comparative statements, and cash-basis variants of income and operating statements.

Revenue recognition handles contracts, subscriptions, milestones, usage-based revenue, products, bundles, and bundle allocations. You can create, modify, duplicate, and terminate contracts.

Company objects include chart of accounts, departments, vendors, custom fields, custom dimensions (and dimension groups), cost allocations, and fixed asset classes.

Settings cover entity management, file uploads, currency configuration, and exchange rates.

Integrations provide webhook management for event-driven sync.

Bank reconciliation includes reconciliation report management, GL transaction listing for reconciliation, and bulk matching of GL transactions to statement transactions.

Authentication

Campfire uses static API key authentication. To get set up:

Log into your Campfire instance and go to Settings > API Keys
Click "Create User" and assign a role. The three roles determine access scope:
- admin grants access to all API endpoints
- clerk allows viewing all data and posting draft entries
- view only restricts to GET endpoints
Click "Create API Key" on the user. Copy the key immediately since it's only shown once.

Include the token in every request:

Authorization: Token YOUR_API_KEY

There is no OAuth flow for the API itself (though Campfire does support MCP-based integration for AI tools, covered later).

API conventions

Before jumping into examples, a few things about how the API behaves.

Endpoint paths vary by resource group. Bank accounts live under /ca/api/account, bills under /ca/api/v1/bill, invoices under /ca/api/v1/invoice, journal entries under /ca/api/journal, and webhooks under /integrations/api/v1/webhook. There isn't a single prefix convention, so check the API reference for each resource.

Pagination uses limit and offset query parameters. Paginated responses return a count, a results array, and next/previous URLs:

{
  "count": 142,
  "results": [...],
  "next": "https://api.meetcampfire.com/ca/api/account?offset=100&limit=100",
  "previous": null
}

Incremental sync is supported through last_modified_at__gte and last_modified_at__lte filters (ISO 8601 format). Most list endpoints also support an include_deleted parameter. When set to true, it returns only deleted records (not active ones) with is_deleted=true and a deleted_at timestamp. When false or omitted, you get only active records. This toggle-based design gives you clean separation between active and deleted data, which is useful for maintaining data consistency across systems.

Object references are numeric IDs. When creating bills, invoices, or journal entries, you first need to look up the IDs of related objects (entities, accounts, vendors, departments, custom dimensions) through their respective list endpoints.

Multi-currency is handled through a two-tier exchange rate model: exchange_rate_book (between the transaction currency and the entity's book currency) and exchange_rate (between the entity currency and the consolidation currency). Both can be auto-computed if omitted.

Direct integration examples

Listing entities

Multi-entity support is core to Campfire. You need entity IDs for nearly every write operation, so this is often the first call an integration makes.

curl --request GET \
  --url https://api.meetcampfire.com/ca/api/entity \
  --header 'Authorization: Token YOUR_API_KEY'

The response includes parent-child relationships, currencies, and exchange rate configuration per entity. There's also a dedicated endpoint for listing entities available for intercompany journal entries.

Listing the chart of accounts

Account IDs are required for bills, journal entries, and most write operations.

curl --request GET \
  --url 'https://api.meetcampfire.com/ca/api/v1/chart_accounts?limit=100' \
  --header 'Authorization: Token YOUR_API_KEY'

You can filter by account type and subtype to narrow results. There's also a separate endpoint for income statement accounts specifically.

Listing bank accounts

curl --request GET \
  --url https://api.meetcampfire.com/ca/api/account \
  --header 'Authorization: Token YOUR_API_KEY'

Supports sorting by most returned fields (prefix with - for descending, e.g. ?ordering=-current_balance), and filtering by chart_of_accounts_account to find bank accounts linked to a specific GL account.

Creating a vendor

Before you can create bills, you need vendor records. This is a common first step when syncing supplier data from an external system.

curl --request POST \
  --url https://api.meetcampfire.com/ca/api/vendor \
  --header 'Authorization: Token YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Acme Cloud Services",
    "email": "billing@acme.example.com",
    "currency": "USD",
    "payment_terms": "net_30"
  }'

Use the bulk search endpoint (POST /ca/api/v1/vendor/bulk_search) to look up vendors by external ID or name, which is useful for matching records during initial sync.

Creating a bill

Bills require references to existing entities, vendors, and expense accounts. Fetch those first, then assemble the bill:

curl --request POST \
  --url https://api.meetcampfire.com/ca/api/v1/bill \
  --header 'Authorization: Token YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "terms": "net_30",
    "bill_date": "2025-07-01",
    "due_date": "2025-08-25",
    "lines": [
      {
        "account": "180564",
        "amount": 10000,
        "description": "Monthly SaaS subscription",
        "department": "35",
        "tags": [{"id": "8114"}]
      }
    ],
    "entity": "5",
    "currency": "USD",
    "vendor": "34182",
    "bill_number": "098765",
    "item_date": "2025-07-01",
    "mailing_address": "1234 Main St. San Francisco CA"
  }'

Key fields on bills: terms accepts values like net_7, net_10, net_15, net_20, net_30, net_40, net_45, net_60, net_90, net_105, net_120, or due_on_receipt. Each line item references an account (the expense account), and can optionally include a department, tags (custom dimension field IDs), and bill_customer for cost center tracking.

Recording a bill payment

Payments in Campfire work through a transaction-based model. You don't simply mark a bill as paid with an amount. You reference an existing journal entry transaction (either one you created or one you found via the list transactions endpoint) and apply it to the bill:

curl --request POST \
  --url https://api.meetcampfire.com/ca/api/v1/bill/{bill_id}/mark_as_paid \
  --header 'Authorization: Token YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "transactions": [
      {
        "transaction_id": 21069178,
        "account_id": "2550",
        "amount": 8999.99
      }
    ]
  }'

If the payment doesn't use the full amount of the referenced transaction, Campfire creates a new journal line for the remainder. You can apply multiple transactions to a single bill in one call.

Creating an invoice

Invoices use a different set of reference objects than bills. They require a client (not vendor), a product, and an entity. Optionally, you can link to a revenue recognition contract.

curl --request POST \
  --url https://api.meetcampfire.com/ca/api/v1/invoice \
  --header 'Authorization: Token YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "terms": "net_30",
    "invoice_date": "2025-07-01",
    "due_date": "2025-07-31",
    "lines": [
      {
        "service_date": "2025-07-01",
        "amount": 300,
        "product": "3560",
        "rate": 15,
        "quantity": 20,
        "description": "API usage - July 2025",
        "tax": 12
      }
    ],
    "entity": "54",
    "currency": "USD",
    "client": "24020",
    "invoice_number": "INV-2025-001",
    "billing_address": "456 Commerce Ave, New York NY",
    "period_start": "2025-07-01",
    "period_end": "2025-07-31",
    "contract": "24899"
  }'

Invoice line items have product, rate, quantity, and tax fields, which differ from bill line items that use account and a flat amount. The contract field ties the invoice to a revenue recognition contract for ASC 606 compliance.

For high-volume scenarios, use the bulk create endpoint (POST /ca/api/v1/invoice/bulk_create) to submit multiple invoices in a single request.

Recording an invoice payment

Invoice payments follow the same transaction-based pattern as bill payments:

curl --request POST \
  --url https://api.meetcampfire.com/ca/api/v1/invoice/{invoice_id}/mark_as_paid \
  --header 'Authorization: Token YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "transactions": [
      {
        "transaction_id": 21069200,
        "account_id": "2550",
        "amount": 300
      }
    ]
  }'

Same mechanics as bill payments: reference an existing journal transaction, and Campfire handles the remainder if the payment is partial. You can also void an invoice payment without voiding the invoice itself using the /void_payment endpoint.

Creating a credit memo

Credit memos are the AR counterpart to debit memos on the AP side. They follow a similar structure to invoices.

curl --request POST \
  --url https://api.meetcampfire.com/ca/api/v1/credit_memo \
  --header 'Authorization: Token YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "credit_memo_date": "2025-07-15",
    "lines": [
      {
        "amount": 150,
        "product": "3560",
        "description": "Overpayment refund"
      }
    ],
    "entity": "54",
    "currency": "USD",
    "client": "24020"
  }'

Credit memos have their own void, reopen, and "mark as used" lifecycle, similar to invoices.

Bulk searching invoices by number

When reconciling against an external system, you often need to look up invoices by their number rather than iterating through pages.

curl --request POST \
  --url https://api.meetcampfire.com/ca/api/v1/invoice/bulk_search \
  --header 'Authorization: Token YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "invoice_numbers": ["INV-2025-001", "INV-2025-002", "INV-2025-003"]
  }'

The same pattern exists for bills (/ca/api/v1/bill/bulk_search), credit memos, and debit memos.

Posting a journal entry

Journal entries require balanced debit and credit transactions. Each transaction line must have either its debit amounts or credit amounts set, never both.

curl --request POST \
  --url https://api.meetcampfire.com/ca/api/journal \
  --header 'Authorization: Token YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "date": "2025-08-01",
    "type": "journal_entry",
    "transactions": [
      {
        "account": "180564",
        "debit_amount_native": 1000,
        "bank_description": "Monthly rent expense",
        "vendor": "34182",
        "department": "3613",
        "tags": [{"id": "7737"}]
      },
      {
        "account": "8856",
        "credit_amount_native": 1000,
        "bank_description": "Monthly rent expense",
        "department": "3436",
        "tags": [{"id": "8330"}]
      }
    ],
    "memo": "August 2025 rent",
    "entity": "54",
    "currency": "USD"
  }'

You only need to set debit_amount_native or credit_amount_native. The _book and consolidation amounts are auto-computed from your exchange rates if omitted. Including a reversal_date in the request body will automatically post a reversing journal on that date.

Posting an intercompany journal entry

Intercompany JEs have two key differences from standard journal entries: each transaction line specifies its own entity, and the request includes a top-level entities object with exchange rates for every entity involved.

curl --request POST \
  --url https://api.meetcampfire.com/ca/api/intercompany_journal \
  --header 'Authorization: Token YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "date": "2025-07-01",
    "type": "journal_entry",
    "transactions": [
      {
        "entity": 54,
        "account": "180564",
        "debit_amount_native": 1000,
        "debit_amount_book": 1000,
        "debit_amount": 1000,
        "bank_description": "Interco services - US entity"
      },
      {
        "entity": 5,
        "account": "7409",
        "credit_amount_native": 1000,
        "credit_amount_book": 728.33,
        "credit_amount": 1000,
        "bank_description": "Interco services - EU entity"
      },
      {
        "entity": 5,
        "account": "7405",
        "debit_amount_native": 1000,
        "debit_amount_book": 728.33,
        "debit_amount": 1000,
        "bank_description": "Interco elimination - EU"
      },
      {
        "entity": 54,
        "account": "8856",
        "credit_amount_native": 1000,
        "credit_amount_book": 1000,
        "credit_amount": 1000,
        "bank_description": "Interco elimination - US"
      }
    ],
    "memo": "Intercompany services Q3 2025",
    "currency": "USD",
    "entities": {
      "5": {
        "id": 5,
        "exchange_rate": 1.373,
        "exchange_rate_book": 0.728332
      },
      "54": {
        "id": 54,
        "exchange_rate": 1,
        "exchange_rate_book": 1
      }
    }
  }'

The entities object is keyed by entity ID and contains the exchange rates for each entity. This is how Campfire handles multi-currency consolidation for groups with subsidiaries in different reporting currencies.

Pulling financial statements

The financial statements endpoints return structured report data without requiring any write operations.

# Income statement
curl --request GET \
  --url 'https://api.meetcampfire.com/ca/api/income_statement?start_date=2025-01-01&end_date=2025-03-31' \
  --header 'Authorization: Token YOUR_API_KEY'

# Balance sheet
curl --request GET \
  --url 'https://api.meetcampfire.com/ca/api/balance_sheet?as_of_date=2025-03-31' \
  --header 'Authorization: Token YOUR_API_KEY'

# Trial balance
curl --request GET \
  --url 'https://api.meetcampfire.com/ca/api/trial_balance?as_of_date=2025-03-31' \
  --header 'Authorization: Token YOUR_API_KEY'

# Cash flow statement
curl --request GET \
  --url 'https://api.meetcampfire.com/ca/api/cash_flow?start_date=2025-01-01&end_date=2025-03-31' \
  --header 'Authorization: Token YOUR_API_KEY'

Campfire also supports cash-basis variants of the income and operating statements for companies that need both accrual and cash-basis reporting, as well as comparative income statements and comparative balance sheets for period-over-period analysis.

Pulling the general ledger

For detailed transaction-level reporting, the general ledger endpoint returns individual GL entries rather than summarized financial statements.

curl --request GET \
  --url 'https://api.meetcampfire.com/ca/api/general_ledger?start_date=2025-01-01&end_date=2025-03-31' \
  --header 'Authorization: Token YOUR_API_KEY'

This is useful for building custom reports or feeding data into a BI tool where you need line-level detail rather than aggregated statement data.

Posting a bank feed

For banking and fintech integrations, you can push transaction data directly into a bank account.

curl --request POST \
  --url https://api.meetcampfire.com/ca/api/account/{account_id}/bank_feed \
  --header 'Authorization: Token YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "transactions": [
      {
        "date": "2025-07-15",
        "amount": -2500.00,
        "description": "Wire transfer to vendor",
        "reference": "WT-20250715-001"
      }
    ]
  }'

This is the endpoint you'd use if you're building a banking integration that feeds transactions into Campfire for reconciliation.

Setting up webhooks

Rather than polling for changes, you can subscribe to events and receive push notifications:

curl --request POST \
  --url https://api.meetcampfire.com/integrations/api/v1/webhook \
  --header 'Authorization: Token YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://your-app.com/webhooks/campfire",
    "topics": [{"name": "invoice.created"}, {"name": "bill.updated"}],
    "active": true
  }'

Use GET /integrations/api/v1/webhook/events to list all available webhook topics. Each webhook includes a token field you can use to verify incoming payloads.

Voiding and reopening

Both bills and invoices support a void/reopen lifecycle that preserves audit trails:

# Void a bill
curl --request POST \
  --url https://api.meetcampfire.com/ca/api/v1/bill/{bill_id}/void \
  --header 'Authorization: Token YOUR_API_KEY'

# Reopen a voided bill
curl --request POST \
  --url https://api.meetcampfire.com/ca/api/v1/bill/{bill_id}/reopen_voided \
  --header 'Authorization: Token YOUR_API_KEY'

# Void an invoice
curl --request POST \
  --url https://api.meetcampfire.com/ca/api/v1/invoice/{invoice_id}/void \
  --header 'Authorization: Token YOUR_API_KEY'

# Void an invoice payment (without voiding the invoice itself)
curl --request POST \
  --url https://api.meetcampfire.com/ca/api/v1/invoice/{invoice_id}/void_payment \
  --header 'Authorization: Token YOUR_API_KEY'

This matters for integration builders because you need to handle these state transitions in your sync logic. A voided bill or invoice isn't deleted; it stays in the system with its status changed.

MCP server for AI integrations

Campfire also exposes an MCP (Model Context Protocol) server, which is worth knowing about if you're building AI-powered workflows on top of accounting data.

The MCP server provides 12 tools covering chart of accounts, transactions, entities, vendors, departments, tags, income statements, balance sheets, cash flow, budgets, contracts, and aging reports. It authenticates with the same API token.

Configuration for Claude Desktop:

{
  "mcpServers": {
    "Campfire": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.meetcampfire.com/mcp",
        "--header",
        "Authorization:Token YOUR_API_TOKEN"
      ]
    }
  }
}

For Cursor and VS Code, the server URL is https://api.campfire.com/mcp (note: different domain from the Claude Desktop config, which uses api.meetcampfire.com) with the token passed in headers. This enables natural language queries against your Campfire data, like pulling income statements or searching transactions without writing API calls.

Challenges of integrating directly

Campfire's API is well-structured and modern, but building a direct integration still involves the typical costs:

Auth management. API keys need to be stored securely for each customer connection, and there's no OAuth flow, so you're managing static credentials.

Data model specifics. Bills use vendor, invoices use client. Payment recording requires referencing journal transactions rather than just posting an amount. Exchange rates have a two-tier model. These are all reasonable design choices, but they mean your integration code is tightly coupled to Campfire's data model.

Maintenance overhead. The API is actively evolving. Endpoint paths don't follow a single convention (some use /ca/api/, others /ca/api/v1/, webhooks use /integrations/api/v1/), so keeping up with changes requires ongoing attention.

Single-provider coverage. If your customers also use QuickBooks, Xero, NetSuite, Sage, FreshBooks, or any of the dozens of other accounting platforms, you need to build and maintain each integration separately.

Integrating with Campfire through Apideck

Apideck provides a unified Accounting API that normalizes data across 40+ accounting platforms, including Campfire. You write one integration and get coverage across all of them.

How it works

Sign up for Apideck and enable the Campfire connector in your dashboard
Use the pre-built Vault component to let your users securely connect their Campfire account. Apideck handles credential storage.
Make API calls using the unified Accounting API

Example: listing invoices

import { Apideck } from '@apideck/node'

const apideck = new Apideck({
  apiKey: process.env.APIDECK_API_KEY,
  appId: process.env.APIDECK_APP_ID,
  consumerId: 'user-123'
})

const { data } = await apideck.accounting.invoicesAll({
  serviceId: 'campfire'
})

console.log(`Found ${data.length} invoices`)

The same code works for QuickBooks, Xero, NetSuite, FreshBooks, Exact, and every other connector in the Accounting category. Only the serviceId changes.

What Apideck normalizes

Through the unified API, Campfire data is mapped to 18+ standardized data models including invoices, bills, payments, customers, suppliers, ledger accounts, journal entries, tax rates, bank accounts, and balance sheet reports. You also get webhook support across all connected providers, official SDKs for Node.js, Python, TypeScript, PHP, and Go, and a pre-built auth component so you don't need to build credential management.

When to use which approach

Go direct if Campfire is the only accounting platform you need to support, you need access to Campfire-specific features like intercompany journal entries with multi-entity exchange rate handling, revenue recognition contracts, or bank reconciliation, or you're building an internal tool for a single Campfire instance.

Use Apideck if your product needs to connect to multiple accounting platforms, you want to ship your Campfire integration in days instead of weeks, or you're a vertical SaaS, fintech, or embedded finance platform where multi-provider accounting connectivity is a product requirement.

Getting started

For direct integration, start with the Campfire API quickstart and the four workflow guides covering accounts payable, accounts receivable, journal entries, and MCP integration.

For the unified API route, sign up for Apideck, enable the Campfire connector, and follow the Accounting API docs.

Accrual vs Cash-Based Accounting: Geographic Differences and What They Mean for Your API

Kate Apideck — Tue, 07 Jul 2026 16:21:43 +0000

If you are building software that touches accounting data, you need to understand the difference between accrual and cash-based accounting. The accounting method your customer uses changes what the numbers in their ledger actually mean.

And it gets more complex when you operate across borders. The rules are not the same in the US, the UK, and Europe. The thresholds differ. The defaults differ. What is mandatory for a company in Germany may be optional for the same size company in Texas.

This post covers the fundamentals first, then the geographic nuances, then what all of this means when you are building accounting integrations through APIs.

Part 1: The Fundamentals

Cash-based accounting

Cash-based accounting records transactions when money moves. Revenue is recognized when payment hits your bank account. Expenses are recorded when the payment leaves. Simple. Predictable. Easy to reconcile against your bank statement.

A freelancer sends an invoice in March. The client pays in May. Under cash-based accounting, that revenue shows up in May. There is no accounts receivable entry. There is no accrual adjustment at year end.

This method works well for sole traders, small service businesses, and anyone who primarily deals in straightforward cash transactions. It gives you an accurate view of how much money is actually available right now.

The downside is that it can distort the picture of how a business is performing. Revenue earned in one period may show up in another. A business can look profitable in one quarter simply because a batch of invoices happened to get paid, while the next quarter looks terrible because nothing came in.

Accrual-based accounting

Accrual accounting records transactions when they are earned or incurred, regardless of when cash changes hands. Revenue is recognized when a sale is made. Expenses are recorded when the obligation is created. This is the matching principle in action: match revenue with the costs required to generate it.

Same example. Freelancer sends an invoice in March. Under accrual accounting, the revenue is recorded in March, even if the payment does not arrive until May. There is an accounts receivable entry on the balance sheet until the cash comes in.

This method gives a more accurate picture of a company's financial health over time. It is why both GAAP (Generally Accepted Accounting Principles, used in the US) and IFRS (International Financial Reporting Standards, used in most of the rest of the world) require accrual accounting for financial reporting.

The trade-off is complexity. You need to track receivables, payables, accrued expenses, prepayments, and deferred revenue. Closing the books at period end takes more work. You need to estimate some amounts that are not yet final.

Why it matters for software

If your application reads financial data from an accounting system, the accounting method determines what those numbers mean. A Profit & Loss report pulled from a cash-basis ledger will show different revenue figures than the same report pulled on an accrual basis, even for the same business in the same period.

If you are building lending software, expense management, or financial analytics, you need to know which basis you are working with. Otherwise your risk models, forecasts, and dashboards are built on assumptions that may not hold.

Part 2: Geographic Differences

The rules around which businesses must use accrual accounting, which can choose, and which default to cash vary significantly across markets.

United States

The US is relatively permissive. The IRS allows most small businesses to use the cash method as long as they meet the gross receipts test. Since the Tax Cuts and Jobs Act (TCJA), the threshold has been indexed for inflation. For tax years beginning in 2025, the threshold sits at $31 million in average annual gross receipts over the prior three-year period.

Below that threshold, sole proprietors, S corporations, partnerships without C corporation partners, and qualified personal service corporations can all use cash-basis accounting. C corporations and partnerships with C corporation partners must use accrual if they exceed the threshold.

There are additional nuances around inventory. Businesses that produce, purchase, or sell merchandise generally need to use accrual for inventory accounting. But the small business taxpayer exception lets qualifying businesses treat inventory as non-incidental supplies and stay on cash.

The practical result: a large portion of US small and mid-market businesses use cash-basis accounting. QuickBooks holds roughly 80% market share among US small businesses by most estimates, and many of those customers run on a cash basis.

United Kingdom

The UK took a dramatic step in April 2024. HMRC made cash-basis accounting the default method for sole traders and partnerships. Previously, cash basis was opt-in with a turnover threshold of £150,000 to enter and £300,000 to stay. Those thresholds have been completely removed.

Now, any sole trader or eligible partnership in the UK automatically uses cash-basis accounting unless they actively opt out and choose traditional (accrual) accounting on their Self Assessment tax return. This is a deliberate simplification move, aligned with HMRC's Making Tax Digital initiative.

Limited companies and LLPs cannot use cash basis. They must use accrual accounting and comply with UK GAAP or IFRS. But for the vast majority of UK self-employed individuals, cash is the default.

This means if you are building software for UK SMBs and sole traders, the most common scenario is cash-basis data flowing through the system. Xero, FreeAgent, and other UK-popular platforms all support cash-basis reporting.

Europe (EU and EEA)

Europe is more fragmented. Each EU member state has its own rules, but the EU Accounting Directive provides a framework with simplified reporting regimes for SMEs and micro-businesses.

Germany is strict on income tax accounting. The mandatory double-entry bookkeeping threshold under §141 AO applies at €800,000 in revenue or €80,000 in profit per year. These thresholds were raised from €600,000 and €60,000 respectively by Germany's Growth Opportunities Act (Wachstumschancengesetz), which came into force in March 2024. Sole proprietors and civil law companies (GbRs) below that threshold can use a simplified income-expenditure method (EÜR). Companies required to keep books, such as a GmbH, OHG, or UG, can apply for cash-based VAT treatment (Istversteuerung under §20 UStG) if their annual revenue is below €800,000. This threshold was also raised from €600,000 in January 2024. For income tax and statutory reporting purposes, most German businesses of any meaningful size use accrual accounting.

The Netherlands allows businesses to opt for cash accounting for VAT purposes. The rules depend on entity type and turnover levels. But for corporate income tax and statutory reporting, accrual is standard.

France similarly requires accrual accounting for most businesses that are under a real tax regime (régime réel). Simplified cash-like reporting is available for micro-enterprises below certain thresholds, but the default for any established business is accrual.

The broader pattern in Europe: accrual is the default for any company required to file statutory accounts. IFRS applies to listed companies. National GAAP (which is generally aligned with or derived from the EU Accounting Directive) applies to most others. Cash accounting is an exception for the smallest businesses, not the norm.

From a VAT perspective, the EU SME scheme caps the threshold at €85,000 for domestic VAT exemption and €100,000 for the cross-border scheme. These thresholds took effect from January 2025 under EU Council Directive 2020/285. They overlap in practice with the cash accounting question because the businesses small enough to qualify for VAT simplification are often the same ones that might use cash accounting.

Australia and New Zealand

Australia allows small businesses with an aggregated turnover under AUD 10 million to use cash accounting for GST purposes. Above that threshold, the non-cash (accruals) method is mandatory. For income tax, both cash and accrual methods are available to eligible businesses, though accrual remains the norm for companies required to prepare statutory financial statements under Australian Accounting Standards. New Zealand follows a similar pattern. Xero was built in New Zealand and its defaults and data models reflect this accrual-first environment.

What this means in practice

If you are building a multi-market product that touches accounting data, you cannot assume a single accounting method across your customer base. US customers are more likely to be on cash basis. UK sole traders default to cash. European and ANZ customers are more likely to be on accrual. And even within a single market, the accounting method can vary by entity type and size.

Part 3: What This Means for Your API Integration

The problem for developers

When you connect to an accounting platform through its API, the data you get back is shaped by the accounting method the business uses. This creates several concrete challenges.

Profit & Loss reports. QuickBooks Online lets you pull P&L reports on either a cash or accrual basis through its API, regardless of the company's default setting. Xero defaults to accrual and lets you switch in connected tools. Sage simply returns data in whatever method the business has configured. If your application does not account for this, you may be comparing cash-basis P&L data from one customer with accrual-basis data from another.

Revenue recognition timing. On an accrual basis, revenue shows up when an invoice is created. On a cash basis, it shows up when the payment is received. If you are building a lending product that assesses revenue trends, mixing these two data sets without normalization will produce unreliable results.

Accounts receivable and accounts payable. Under cash-basis accounting, AR and AP effectively do not exist in a meaningful sense. The ledger does not track outstanding invoices as balance sheet items. If your application expects to pull AR aging data to assess credit risk, that data may be empty or absent for a cash-basis customer.

Balance sheet completeness. A cash-basis balance sheet is incomplete by definition. There are no accrued expenses, no deferred revenue, no prepayments. If your product needs a full picture of a company's financial position, you need accrual data.

How accounting APIs handle this

Each accounting platform handles the cash vs accrual distinction differently at the API level.

QuickBooks Online stores all transaction data and can generate reports on either basis. The QBO Reports API accepts an accounting_method parameter that can be set to Cash or Accrual. This is powerful because it means you can always request accrual-basis reports even if the company's default is cash. The underlying journal entries contain enough data to reconstruct either view.

GET /v3/company/{companyId}/reports/ProfitAndLoss
  ?accounting_method=Accrual
  &start_date=2025-01-01
  &end_date=2025-03-31

Xero defaults to accrual and stores transactions accordingly. When you pull reports through the Xero API, the default is accrual. Cash-basis reporting is handled by connected tools (like Fathom) that can reprocess the data. The API itself returns accrual-basis data. Invoice objects include status fields like AUTHORISED, PAID, and VOIDED that let you reconstruct cash-basis timing if needed.

Sage Business Cloud returns data based on the company's configuration. The API does not offer a toggle to switch between cash and accrual views. What you see is what the business has set up. If they run on cash, you get cash-basis data.

NetSuite is accrual-first by design. As an enterprise ERP, it assumes accrual accounting. Revenue recognition schedules, multi-period allocations, and deferred revenue are all built into the data model. Cash-basis views are available through reporting configurations but the transaction data is fundamentally accrual.

Building for both: the unified API approach

When you are integrating with multiple accounting platforms across multiple markets, the challenge compounds. You are dealing with different APIs, different data models, different authentication methods, and different assumptions about accounting basis.

A unified accounting API normalizes these differences. Instead of writing separate integration code for QuickBooks, Xero, Sage, and others, you connect once and get a standardized data model across all platforms.

For the cash vs accrual problem specifically, a unified API can:

Expose the accounting method as a field on the company or organization object, so your application knows what basis the data represents
Normalize invoice objects to include both the invoice date (accrual timing) and payment date (cash timing), giving you the data to reason about either method
Standardize balance sheet accounts across platforms so your code does not need to handle the differences between how QBO, Xero, and Sage represent AR and AP

Here is an example using Apideck's Accounting API to pull invoices with both timing signals:

import { Apideck } from '@apideck/node'

const apideck = new Apideck({
  apiKey: process.env.APIDECK_API_KEY,
  appId: process.env.APIDECK_APP_ID,
  consumerId: 'customer-123'
})

// Pull invoices with both accrual and cash timing data
const { data: invoices } = await apideck.accounting.invoicesAll({
  filter: {
    updated_since: '2025-01-01T00:00:00.000Z'
  }
})

// Each invoice includes:
// - invoice_date (when it was issued, accrual timing)
// - due_date (when payment is expected)
// - paid_date (when payment was received, cash timing)
// - status (DRAFT, AUTHORISED, PAID, VOIDED)
// - balance (outstanding amount)

for (const invoice of invoices) {
  console.log(`Invoice ${invoice.number}`)
  console.log(`  Issued: ${invoice.invoice_date}`)    // accrual
  console.log(`  Paid:   ${invoice.paid_date}`)        // cash
  console.log(`  Status: ${invoice.status}`)
  console.log(`  Balance: ${invoice.balance}`)
}

This gives you the building blocks to handle both accounting methods in your application logic, regardless of which platform the customer uses.

Handling multi-market scenarios

If your product serves customers in the US, UK, and Europe, here are the practical patterns to follow.

Detect the accounting method. Always check the organization's accounting method configuration when a new customer connects. Do not assume. Store this alongside the connection metadata so your application logic can branch accordingly.

Normalize revenue data. For analytics and reporting, decide whether your product works on a cash or accrual basis internally. Then normalize incoming data to match. If you need accrual-basis revenue but the customer runs on cash, you can often reconstruct accrual timing from invoice dates. The reverse (deriving cash from accrual) requires payment data, which most APIs expose.

Handle missing data gracefully. Cash-basis customers may have sparse or empty AR/AP data. Your UI and logic need to handle this without breaking. Do not show an AR aging chart that is empty and confusing. Instead, adapt the experience based on the accounting method.

Be explicit about basis in reports. If your product generates financial reports or exports data, always label the accounting method. A revenue chart that does not specify cash vs accrual is a chart that can be misread.

Tax implications vary by region. If your product handles anything tax-related, be aware that the accounting method for tax purposes may differ from the method used for management reporting. A UK limited company must use accrual for statutory accounts but might use simplified reporting internally. A US business might use cash for tax but accrual for management purposes. The API data reflects the accounting system's configuration, not necessarily the tax reporting basis.

The trial balance: where it all comes together

The trial balance is the foundational report for any accounting integration. It is a list of all accounts with their debit and credit balances at a point in time. On an accrual basis, the trial balance includes accrued income, accrued expenses, prepayments, and deferred revenue. On a cash basis, many of these accounts either do not exist or carry zero balances.

If your product relies on the trial balance for financial analysis, credit assessment, or automated bookkeeping, you need to understand which version you are looking at. A cash-basis trial balance can look very different from an accrual-basis trial balance for the same business in the same period.

For platforms like QuickBooks that support both views, you can request the trial balance on either basis. For platforms that only return data in the configured method, you need to work with what you get or build conversion logic in your application layer.

Part 4: Platform Support Reference

The table below covers the full range of accounting systems and ERPs you are likely to encounter when building for US, UK, European, and ANZ markets. Cash basis column indicates whether the platform supports it at all; API basis toggle indicates whether you can request a specific basis via API parameter rather than relying on the company's configuration.

Platform	Cash basis	Accrual basis	API basis toggle	Default	Primary markets
QuickBooks Online	Yes	Yes	Yes (`accounting_method` param)	Varies (cash common for US SMBs)	US, CA, UK, AU
QuickBooks Desktop	Yes	Yes	No	Set per company	US, CA
Xero	Reports only	Yes	No	Accrual	AU, NZ, UK
Sage Business Cloud	Config-dependent	Yes	No	Accrual	UK, IE, US
Sage Intacct	Reports only	Yes	No	Accrual	US enterprise
Sage 50	Yes	Yes	No	Set per company	UK, US, CA
NetSuite	Reports only	Yes	Via SuiteQL	Accrual	Enterprise global
MS Dynamics 365 BC	Reports only	Yes	No	Accrual	Enterprise global
SAP Business One	No	Yes	No	Accrual	Mid-market global
FreshBooks	Yes	Yes	No	Set per account	US, CA
Wave	Yes	Yes	No	Accrual	US, CA
Zoho Books	Yes	Yes	Report params only	Accrual	Global SMB
FreeAgent	Yes	Yes	No	Cash (sole traders)	UK
Exact Online	No	Yes	No	Accrual	NL, BE, EU
Moneybird	Yes	Yes	No	Accrual	NL
Yuki	No	Yes	No	Accrual	BE, NL
Odoo	Via journal config	Yes	No	Accrual	Global

QuickBooks Online is the only platform here that offers a genuine API-level basis toggle. You can request either cash or accrual regardless of how the company is configured. That makes it the most flexible platform for products that need to normalize data across a mixed customer base.

Most other platforms return data in whatever basis the company has configured and offer no server-side switch. If you need cash-basis data from a Xero customer, you reconstruct it from payment dates on the invoice objects. If you need accrual from a Sage Business Cloud customer running on cash, that conversion happens in your code.

Exact Online, Yuki, and SAP Business One are accrual-only. If you are building for Benelux or mid-market European buyers, assume accrual. There is no cash-basis configuration in these systems.

FreeAgent is the UK outlier. It defaults to cash basis for sole traders, in line with HMRC's April 2024 change. If you are seeing sparse AR and AP data from UK FreeAgent connections, check whether the customer is a sole trader on cash before assuming a data issue.

Deferred revenue and what it exposes about platform differences

Deferred revenue is a good test case for how much any given platform understands about accrual accounting. It is a current liability: cash has been received, but the obligation to deliver the service or product has not yet been fulfilled. A SaaS company that collects $12,000 for an annual subscription on January 1 records $12,000 in deferred revenue on that date, then recognizes $1,000 per month as the subscription period passes. On a cash basis, none of that exists. The $12,000 shows up as revenue in January.

The gap this creates for developers is concrete. If you pull P&L data from a SaaS company on cash-basis accounting, their January looks exceptional and the rest of the year looks flat. If you pull from the same company on accrual, you see $1,000 per month throughout the year. These are not just different accounting treatments of the same underlying reality. They tell completely different stories about the business.

NetSuite has the most complete implementation of any platform in common use. Revenue recognition is a core module, not a bolted-on feature. You can pull recognition schedules directly from the API, query deferred revenue balances by contract or item, and get forecast data showing how deferred amounts will recognize over future periods. Sage Intacct also has dedicated revenue recognition, with contract-level schedules and multi-element arrangements exposed through the revenue management objects.

QuickBooks Online supports deferred revenue in the sense that you can create a liability account and manually post journal entries against it. But there is no native recognition scheduling. You cannot query how much of a company's deferred revenue will recognize in Q3 through the QBO API. You get the account balance; the schedule lives in a spreadsheet.

Xero has no native deferred revenue module. Teams handle it through manual journal entries or third-party tools. What you get from the Xero API is the balance in whatever liability account the accountant set up. There is no structured recognition data behind it.

FreshBooks and Wave have no deferred revenue support. They are built for service businesses billing hourly or per project, where the concept rarely applies.

Whether structured recognition schedules exist depends on the platform, not the business. NetSuite and Sage Intacct expose them via API. QBO, Xero, and most SMB platforms do not. If you need scheduled data, you either connect at the ERP layer or build your own estimation logic from invoice and contract data.

A deferred revenue balance on the balance sheet is also not always reliable as a standalone metric. For QBO customers, it often reflects manually created journal entries rather than a systematically maintained schedule. The number may be accurate or it may be months stale. Before using it in credit assessment or financial modeling, treat it as a starting point.

Zero deferred revenue in the ledger does not necessarily mean the business has none. For cash-basis customers, it simply does not appear. The information is absent by design, not because the business has no advance payments.

What to do about it

If you are building a product that connects to accounting platforms, treat the accounting method as a first-class concept in your data model. Detect it early. Handle both methods in your logic. Label your outputs clearly so nobody misreads a cash-basis revenue number as accrual.

The businesses connecting to your product have no choice in the matter. Their accounting method is determined by their jurisdiction, their entity type, and their size. Your job is to meet them where they are and make the data useful regardless.

How to Integrate with the FreshBooks API

Kate Apideck — Mon, 06 Jul 2026 15:15:56 +0000

FreshBooks is cloud-based accounting software popular with freelancers and small businesses. The FreshBooks API gives you programmatic access to invoices, clients, expenses, time tracking, and reports through a REST interface.

The Apideck FreshBooks connector handles authentication, pagination, and data normalization if you want to skip the manual work. It also lets you support 25+ accounting platforms with a single integration.

This guide covers direct FreshBooks integration: authentication, the identity model, endpoints, pagination, webhooks, and the gotchas that trip people up.

What the FreshBooks API is

The FreshBooks API is JSON-based REST. You can create invoices, manage clients, track expenses, log time, and pull reports.

The API uses standard HTTP methods (GET, POST, PUT, DELETE) with JSON payloads, OAuth 2.0 for authentication, scope-based permissions, and webhooks for real-time notifications.

Base URL: https://api.freshbooks.com

Why Integrate with FreshBooks

SaaS companies integrate with FreshBooks to connect their platform to their customers' accounting workflows. Instead of asking users to export and import data manually, an integration syncs it automatically. For more on accounting integration patterns, see our guide on accounting integration.

Say you have a project management tool that tracks billable hours. Without integration, users manually create invoices in FreshBooks based on their time entries. With integration, your tool generates draft invoices with the right client, line items, and rates.

Other use cases: payment processors marking invoices as paid when payments clear, CRM systems syncing client data bidirectionally, e-commerce platforms creating invoices on orders, expense tools pushing approved expenses into FreshBooks.

Getting Started

You need a FreshBooks account and a registered application before writing any code.

Create a Developer Account

Register Your Application

Go to the FreshBooks developer page and create a new application. You'll provide an application name (must be unique across all FreshBooks apps, shows on the authorization screen), a redirect URI (receives the authorization code after users grant access, must be HTTPS in production), and the scopes your app needs.

FreshBooks generates a client ID and client secret after you save. Store the secret securely.

Authentication

FreshBooks uses OAuth 2.0. The flow:

User visits your authorization URL, gets redirected to FreshBooks
User logs in and grants permission
FreshBooks redirects back with an authorization code
Your server exchanges the code for access and refresh tokens

Authorization URL

Redirect users here to start the OAuth flow:

https://auth.freshbooks.com/oauth/authorize/
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=user:profile:read user:clients:read user:invoices:read

The scope parameter defines what permissions you're requesting. Request only what you need.

Token Exchange

After the user grants access, FreshBooks redirects to your redirect URI with a code parameter. Exchange it:

curl -X POST 'https://api.freshbooks.com/auth/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "code": "AUTHORIZATION_CODE",
    "redirect_uri": "YOUR_REDIRECT_URI"
  }'

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 43200,
  "refresh_token": "abc123...",
  "scope": "user:profile:read user:clients:read user:invoices:read",
  "created_at": 1234567890
}

Token Lifetimes

Access tokens expire after 12 hours. Refresh tokens never expire but are single-use. Every refresh gives you a new access token and a new refresh token. Store the new refresh token immediately because the old one is now invalid.

curl -X POST 'https://api.freshbooks.com/auth/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "refresh_token",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

Making Authenticated Requests

Include the access token in the Authorization header:

curl -X GET 'https://api.freshbooks.com/auth/api/v1/users/me' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

The Identity Model

This is where FreshBooks gets tricky. The API uses two different identifiers: accountId and businessId. You need to know when to use each.

Accounts vs Businesses

FreshBooks evolved from an account-based architecture to a business-based one. The result is a split:

accountId is for /accounting endpoints (invoices, clients, expenses, payments). businessId is for /timetracking and /projects endpoints.

These are different values. You cannot interchange them. Using the wrong one causes silent failures or incorrect routing.

Getting Your Identifiers

Call the /me endpoint to retrieve the user's identities:

curl -X GET 'https://api.freshbooks.com/auth/api/v1/users/me' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

The response includes a business_memberships array:

{
  "response": {
    "business_memberships": [
      {
        "id": 168372,
        "role": "owner",
        "business": {
          "id": 77128,
          "name": "Acme Corp",
          "account_id": "zDmNq"
        }
      }
    ]
  }
}

In this example, businessId is 77128 and accountId is zDmNq.

A single user can have multiple business memberships with different roles (owner, admin, manager, employee, contractor, client). Your integration needs to handle this.

Endpoint Patterns

Accounting endpoints use accountId:

/accounting/account/{accountId}/invoices/invoices
/accounting/account/{accountId}/users/clients
/accounting/account/{accountId}/expenses/expenses

Time tracking and project endpoints use businessId:

/timetracking/business/{businessId}/time_entries
/projects/business/{businessId}/projects

Key Endpoints

FreshBooks organizes its API around business entities.

Clients

Method	Endpoint	Description
GET	`/accounting/account/{accountId}/users/clients`	List all clients
POST	`/accounting/account/{accountId}/users/clients`	Create a client
GET	`/accounting/account/{accountId}/users/clients/{clientId}`	Get a single client
PUT	`/accounting/account/{accountId}/users/clients/{clientId}`	Update a client

To delete a client, send a PUT request with vis_state set to 1:

curl -X PUT 'https://api.freshbooks.com/accounting/account/zDmNq/users/clients/12345' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "client": {
      "vis_state": 1
    }
  }'

Creating a client:

curl -X POST 'https://api.freshbooks.com/accounting/account/zDmNq/users/clients' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "client": {
      "fname": "Jane",
      "lname": "Doe",
      "email": "jane@example.com",
      "organization": "Doe Industries",
      "currency_code": "USD"
    }
  }'

Invoices

Method	Endpoint	Description
GET	`/accounting/account/{accountId}/invoices/invoices`	List invoices
POST	`/accounting/account/{accountId}/invoices/invoices`	Create an invoice
GET	`/accounting/account/{accountId}/invoices/invoices/{invoiceId}`	Get an invoice
PUT	`/accounting/account/{accountId}/invoices/invoices/{invoiceId}`	Update an invoice

Invoice line items are not returned by default. You must explicitly request them with include[]:

curl -X GET 'https://api.freshbooks.com/accounting/account/zDmNq/invoices/invoices?include[]=lines' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Expenses

Method	Endpoint	Description
GET	`/accounting/account/{accountId}/expenses/expenses`	List expenses
POST	`/accounting/account/{accountId}/expenses/expenses`	Create an expense
GET	`/accounting/account/{accountId}/expenses/expenses/{expenseId}`	Get an expense

Payments

Method	Endpoint	Description
GET	`/accounting/account/{accountId}/payments/payments`	List payments
POST	`/accounting/account/{accountId}/payments/payments`	Record a payment

Time Entries

Method	Endpoint	Description
GET	`/timetracking/business/{businessId}/time_entries`	List time entries
POST	`/timetracking/business/{businessId}/time_entries`	Create a time entry

Pagination

FreshBooks uses page-based pagination with page and per_page parameters.

curl -X GET 'https://api.freshbooks.com/accounting/account/zDmNq/invoices/invoices?page=1&per_page=100' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response includes pagination metadata:

{
  "response": {
    "result": {
      "invoices": [...],
      "page": 1,
      "pages": 14,
      "per_page": 100,
      "total": 1389
    }
  }
}

Watch out: the API silently caps per_page at 100. If you request per_page=2000, you get 100 results with no warning. You need proper pagination to fetch complete datasets.

async function getAllInvoices(accountId, accessToken) {
  const invoices = [];
  let page = 1;
  let totalPages = 1;

  do {
    const response = await fetch(
      `https://api.freshbooks.com/accounting/account/${accountId}/invoices/invoices?page=${page}&per_page=100`,
      { headers: { 'Authorization': `Bearer ${accessToken}` } }
    );
    const data = await response.json();

    invoices.push(...data.response.result.invoices);
    totalPages = data.response.result.pages;
    page++;
  } while (page <= totalPages);

  return invoices;
}

Searching and Filtering

FreshBooks supports search parameters on list endpoints. The syntax is search[field]=value:

# Find invoices for a specific client
curl -X GET 'https://api.freshbooks.com/accounting/account/zDmNq/invoices/invoices?search[customerid]=12345' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

# Find unpaid invoices
curl -X GET 'https://api.freshbooks.com/accounting/account/zDmNq/invoices/invoices?search[payment_status]=unpaid' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

For "in" searches (matching multiple values):

# Find invoices with status 2 or 4
curl -X GET 'https://api.freshbooks.com/accounting/account/zDmNq/invoices/invoices?search[status][]=2&search[status][]=4' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Available search parameters vary by endpoint. Check the API docs for each resource.

Includes

Related data often requires extra API calls. FreshBooks provides an include[] parameter to fetch related resources inline:

# Get invoices with line items
curl -X GET 'https://api.freshbooks.com/accounting/account/zDmNq/invoices/invoices?include[]=lines' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

# Get invoices with lines and allowed payment gateways
curl -X GET 'https://api.freshbooks.com/accounting/account/zDmNq/invoices/invoices?include[]=lines&include[]=allowed_gateways' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Without include[]=lines, invoice responses omit line item details. This trips people up.

Rate Limits

FreshBooks does not publish specific numeric rate limits but will throttle requests if you make too many calls in a short period. The API returns HTTP 429 when rate limited.

Implement exponential backoff on 429 responses, cache responses where appropriate, use includes to reduce call count, and batch operations when possible.

FreshBooks reserves the right to disable apps that hit the API aggressively.

Webhooks

You can subscribe to webhooks for real-time notifications instead of polling.

Registering a Webhook

curl -X POST 'https://api.freshbooks.com/events/account/zDmNq/events/callbacks' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "callback": {
      "event": "invoice.create",
      "uri": "https://your-server.com/webhooks/freshbooks"
    }
  }'

Verification

FreshBooks sends a verification code to your endpoint when you first register. You must verify ownership by sending the code back:

curl -X PUT 'https://api.freshbooks.com/events/account/zDmNq/events/callbacks/{callbackId}' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "callback": {
      "verifier": "scADVVi5QuKuj5qTjVkbJNYQe7V7USpGd"
    }
  }'

Save this verification code. You'll need it to verify incoming webhook signatures.

Webhook Payload

When an event occurs, FreshBooks POSTs form-urlencoded data to your URI:

name=invoice.create
&object_id=1234567
&account_id=zDmNq
&business_id=77128
&identity_id=712052
&user_id=1

The object_id is the ID of the affected resource. You'll need to call the API to get full details.

Signature Verification

Each webhook includes an X-FreshBooks-Hmac-SHA256 header. Verify it using the verification code as the secret:

import base64
import hmac
import hashlib
import json

def verify_webhook(verifier, request_data, signature):
    # FreshBooks sends form-urlencoded data, but calculates the signature
    # using a JSON representation. Convert all values to strings and serialize
    # to JSON. Note: Python's json.dumps adds spaces after : and , which matches
    # FreshBooks' format (e.g., {"key": "value", "key2": "value2"})
    msg = {k: str(v) for k, v in request_data.items()}
    payload = json.dumps(msg)

    calculated = hmac.new(
        verifier.encode('utf-8'),
        msg=payload.encode('utf-8'),
        digestmod=hashlib.sha256
    ).digest()

    return base64.b64encode(calculated).decode() == signature

Supported Events

Common webhook events:

Event	Description
client.create	Client created
client.update	Client updated
client.delete	Client deleted
invoice.create	Invoice created
invoice.update	Invoice updated
invoice.delete	Invoice deleted
invoice.sendByEmail	Invoice emailed
estimate.create	Estimate created
estimate.update	Estimate updated
estimate.delete	Estimate deleted
payment.create	Payment recorded
payment.update	Payment updated
payment.delete	Payment deleted
expense.create	Expense created
expense.update	Expense updated
expense.delete	Expense deleted
project.create	Project created
project.update	Project updated
project.delete	Project deleted
time_entry.create	Time entry created
time_entry.update	Time entry updated
time_entry.delete	Time entry deleted

FreshBooks supports many more events including bill.*, bill_vendor.*, category.*, credit_note.*, item.*, recurring.*, service.*, and tax.*. See the FreshBooks webhook documentation for the full list.

You can subscribe to all events for a noun by using just the noun: invoice subscribes to create, update, delete, and sendByEmail.

Error Handling

FreshBooks returns standard HTTP status codes with JSON error bodies: 200 for success, 400 for bad request (invalid parameters), 401 for unauthorized (invalid or expired token), 403 for forbidden (insufficient permissions), 404 for not found, 429 for rate limited, 500 for server error.

Error responses include details:

{
  "response": {
    "errors": [
      {
        "errno": 1012,
        "field": "customerid",
        "message": "Customer not found.",
        "object": "invoice",
        "value": "999999"
      }
    ]
  }
}

Data Mapping Considerations

When mapping your data structures to FreshBooks:

Clients require either a first name/last name or an organization name. Email is optional but recommended. Clients are identified by their userid field in responses.

Invoices need line items with a name and unit_cost. The qty defaults to 1. Tax handling is complex and varies by region.

Monetary values come back as nested objects:

{
  "amount": {
    "amount": "1234.56",
    "code": "USD"
  }
}

Dates use ISO 8601 format (YYYY-MM-DD).

FreshBooks uses vis_state to track whether records are active (0), deleted (1), or archived (2). Records are soft-deleted by sending a PUT request with vis_state: 1. You can restore deleted records by setting vis_state back to 0. If you're updating a record, don't include vis_state unless you intend to change it. FreshBooks processes vis_state changes separately and will ignore other fields in the same request.

Connecting to FreshBooks and 25+ Accounting APIs at Once

Building a direct FreshBooks integration means handling OAuth token rotation, the dual identity model, silent pagination caps, and webhook signature verification. And that's one platform.

If your product needs multiple accounting systems, each has its own quirks. QuickBooks uses a different OAuth flow. Xero has its own pagination. Sage requires managing multiple regional APIs. For more on these challenges, see our guide on ERP integration for fintech and SaaS.

Apideck provides a unified API that handles these differences. You write one integration and get FreshBooks, QuickBooks, Xero, NetSuite, and 25+ other accounting platforms.

import { Apideck } from '@apideck/node';

const apideck = new Apideck({
  apiKey: process.env.APIDECK_API_KEY,
  appId: process.env.APIDECK_APP_ID,
  consumerId: 'user-123'
});

// List invoices from FreshBooks
const { data } = await apideck.accounting.invoicesAll({
  serviceId: 'freshbooks'
});

// Same code works for QuickBooks, Xero, etc.
const qbInvoices = await apideck.accounting.invoicesAll({
  serviceId: 'quickbooks'
});

Apideck handles OAuth flows, token refresh, data normalization, and pagination for each connector. Your team builds features instead of maintaining integrations.

Get started with Apideck to connect FreshBooks and 25+ other platforms through a single Accounting API. For a comparison of FreshBooks against other options, check out our top 15 accounting APIs to integrate with.

Frequently Asked Questions

Does FreshBooks provide a sandbox environment?

No. Use a trial account or a separate development account for testing. Be careful not to send real invoices from test accounts.

How do I handle multiple FreshBooks accounts for a single user?

Users can belong to multiple businesses with different roles. Parse the business_memberships array from the /me endpoint and let users select which business to connect. Store both the accountId and businessId for each connected business.

Does the API support bulk operations?

No dedicated bulk endpoints. You'll need to make individual API calls. Implement rate limiting and error handling to avoid hitting limits.

How do I handle currency conversion?

FreshBooks stores amounts in the currency specified for each client or invoice. Multi-currency transactions are supported, but currency conversion is not handled by the API. Your integration must handle conversion if needed.

What scopes should I request?

Request only the scopes your app needs. user:profile:read is required to get identity information. For client management, add user:clients:read and user:clients:write. For invoices, add user:invoices:read and user:invoices:write. For expenses, add user:expenses:read. For payments, add user:payments:read.

Over-requesting scopes makes users less likely to authorize your app.

How to Integrate with the MYOB API

Kate Apideck — Fri, 03 Jul 2026 12:13:02 +0000

MYOB dominates the accounting software market in Australia and New Zealand. If your SaaS product serves businesses in the ANZ region, your customers are probably asking for MYOB integration. This guide covers authentication (including the changes MYOB introduced in March 2025), the ongoing deprecation of AccountRight Classic, and the practical details of working with the API.

If you'd rather skip the complexity of building direct integrations, Apideck offers a MYOB connector through our Unified Accounting API that handles OAuth, token management, and data normalization across MYOB and 30+ other accounting platforms.

What is the MYOB Business API?

The MYOB Business API is a REST-based JSON API for reading and writing data from MYOB AccountRight and MYOB Business company files. It works with both local desktop installations and cloud-hosted files, though the authentication flow differs between the two.

The API covers core accounting functions: contacts (customers, suppliers, employees), invoices, bills, payments, inventory, general ledger accounts, journal entries, tax codes, and payroll. It uses OAuth 2.0 for cloud file authentication and supports OData query parameters for filtering and sorting results.

MYOB has consolidated its product lines under the "MYOB Business" branding. The AccountRight and Essentials product lines are being phased out for new customers, but the API remains consistent across all three. If you see references to "AccountRight API" in older documentation, you're looking at the same API.

Why integrate with MYOB?

MYOB holds significant market share among Australian and New Zealand SMBs. For vertical SaaS products, fintech platforms, and B2B tools targeting the ANZ market, MYOB integration is often a requirement.

Consider an expense management SaaS. Without integration, users export transactions, manually create bills in MYOB, and reconcile by hand. With a MYOB integration, the app can push approved expenses directly to the ledger, create supplier records, and apply the correct tax codes automatically. Users save hours of double entry and reduce errors.

The same logic applies to invoicing platforms, payment reconciliation tools, inventory management systems, and payroll applications. Integration eliminates manual data transfer and makes your product fit into existing accounting workflows.

Registration and API keys

Before writing any code, register for the MYOB Developer Program at developer.myob.com. Registration is free and gives you access to the MY.MYOB portal where you create API keys.

Once your developer account is approved, log into MY.MYOB and navigate to the Developer tab. Register your application by providing a name and redirect URI. MYOB generates a client ID (API Key) and client secret that you use for OAuth authentication.

The redirect URI must match exactly what you register. MYOB is strict about this—any mismatch causes authentication failures.

MYOB offers different developer program tiers with varying API call limits. The default rate limit is 8 requests per second and 1,000,000 requests per day per API key. You can only have 2 active API keys at once per developer account. Using a third key automatically deactivates one of the others, which causes confusing rate limit errors if you're unaware of this restriction.

Authentication: the March 2025 changes

MYOB overhauled its OAuth flow in March 2025. If you're building a new integration, you must use the new scopes and authentication requirements. Keys created before March 2025 still use the old scopes, but any new integration needs to follow the updated process.

New granular scopes

The old CompanyFile scope is deprecated for new API keys. MYOB now requires granular scopes that specify which data categories your app needs access to:

sme-company-file — required for all access
sme-general-ledger — accounts, journals, tax codes
sme-sale — invoices, customer payments, quotes
sme-purchase — bills, supplier payments
sme-contact — customers, suppliers, employees
sme-inventory — items, locations, adjustments
sme-payroll — employee payroll details

Request only the scopes your application actually needs. The authorization screen shows users exactly what data you're requesting access to.

Admin-only authorization

As of March 2025, only administrator users of a MYOB company file can approve OAuth requests. This is a security enhancement. If your users attempt to authorize with a non-admin account, the flow fails.

Company file GUID retrieval

The old endpoint GET https://api.myob.com/accountright/ no longer returns company files for new API keys. Instead, MYOB returns the company file GUID (businessId) in the redirect URI after successful authorization.

You must include prompt=consent in your authorization URL to ensure the businessId is returned. The authorization URL looks like:

https://secure.myob.com/oauth2/account/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/redirect
  &response_type=code
  &scope=sme-company-file sme-contact sme-sale
  &prompt=consent

After the user authorizes, MYOB redirects to your URI with both a code and businessId parameter. Use the code to exchange for access and refresh tokens. Store the businessId as the company file identifier for all subsequent API calls.

Token lifecycle

Access tokens expire in approximately 20 minutes. When you receive tokens, MYOB includes an expiry timestamp. Implement token refresh before expiration to maintain uninterrupted access. The refresh token request uses:

POST https://secure.myob.com/oauth2/v1/authorize
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID
&client_secret=YOUR_SECRET
&refresh_token=REFRESH_TOKEN
&grant_type=refresh_token

Store tokens securely and never log them.

Key API endpoints

The MYOB Business API organizes endpoints by business function. The base URL for cloud files is:

https://arl2.api.myob.com/accountright/{company_file_id}/

For local desktop files, the API runs on localhost:8080/accountright/.

Contacts

Contacts cover customers, suppliers, and employees.

Endpoint	Purpose
`/Contact/Customer`	Customer records for invoicing
`/Contact/Supplier`	Supplier records for bills
`/Contact/Employee`	Employee records for payroll
`/Contact/Personal`	Other contacts

Contacts require a Name field at minimum. Each contact gets a unique UID that you use when creating invoices or bills.

Sales

Sales endpoints handle customer-facing transactions.

Endpoint	Purpose
`/Sale/Invoice/Item`	Product-based invoices
`/Sale/Invoice/Service`	Service-based invoices
`/Sale/CustomerPayment`	Payments received from customers
`/Sale/Quote/Item`	Quotes for products
`/Sale/CreditSettlement`	Credit note applications

When creating invoices, you POST to the specific invoice type endpoint. The generic /Sale/Invoice endpoint only supports GET requests.

Purchases

Purchase endpoints mirror the sales structure for supplier transactions.

Endpoint	Purpose
`/Purchase/Bill/Item`	Bills for purchased items
`/Purchase/Bill/Service`	Service bills
`/Purchase/SupplierPayment`	Payments to suppliers
`/Purchase/Order/Item`	Purchase orders

General Ledger

Ledger endpoints provide access to the chart of accounts and financial data.

Endpoint	Purpose
`/GeneralLedger/Account`	Chart of accounts
`/GeneralLedger/TaxCode`	Tax rate definitions
`/GeneralLedger/JournalTransaction`	Posted journal entries
`/GeneralLedger/GeneralJournal`	Manual journal entry creation
`/GeneralLedger/Category`	Tracking categories

Inventory

Inventory endpoints manage products and stock.

Endpoint	Purpose
`/Inventory/Item`	Products and services
`/Inventory/Adjustment`	Stock adjustments
`/Inventory/Location`	Warehouse locations

Request headers and versioning

The API requires specific headers for all requests:

Authorization: Bearer ACCESS_TOKEN
x-myobapi-key: YOUR_CLIENT_ID
x-myobapi-version: v2

Always specify x-myobapi-version: v2. The default is v1, which lacks GUID support and causes problems. This is a common source of errors for new integrations.

For cloud files, include the company file token:

x-myobapi-cftoken: BASE64_ENCODED(username:password)

The cftoken contains the company file username and password, base64 encoded with a colon separator. For files authenticated via OAuth 2.0 with admin access, this may not be required, but older implementations and desktop files need it.

Data mapping considerations

When syncing data between your application and MYOB, keep these mapping issues in mind.

Invoice structure

MYOB supports five invoice types: Item, Service, Professional, TimeBilling, and Miscellaneous. Each has a different line item structure. Most integrations use Item or Service invoices.

Line items require references to existing inventory items or tax codes. You cannot create an invoice with inline item definitions. Fetch or create the required items first, then reference them by UID in the invoice payload.

Tax codes

MYOB stores tax rates as TaxCode objects with UIDs. Common Australian tax codes include GST (10%), GST Free, and Input Taxed. Your application needs to map its tax logic to the appropriate MYOB tax codes, which you can retrieve from /GeneralLedger/TaxCode.

Account mapping

Line items on invoices and bills link to ledger accounts. MYOB uses account numbers and UIDs. Retrieve the chart of accounts via /GeneralLedger/Account to map your categories to the correct accounts.

Currency

MYOB supports multi-currency transactions. Currency codes follow ISO 4217. If your customers use foreign currencies, check whether their MYOB file has multi-currency enabled.

Error handling and rate limits

The API returns standard HTTP status codes: 200 for success, 201 for created, 400 for bad request, 401 for authentication errors, and 404 for not found.

Error responses include JSON with error codes and messages:

{
  "Errors": [
    {
      "Name": "ValidationError",
      "Message": "The Customer UID is required."
    }
  ]
}

Rate limiting

The default limits are 8 requests per second and 1,000,000 requests per day per API key. When you hit a rate limit, the API returns a 403 status (not 429, which can be confusing). Implement exponential backoff and retry logic.

The 29-second timeout limit means long-running queries may fail. If you're fetching large datasets, use pagination and OData filters to reduce response times.

OData filtering

The API supports OData query parameters for filtering results:

/Contact/Customer?$filter=IsActive eq true
/Sale/Invoice/Item?$orderby=Number desc
/GeneralLedger/Account?$filter=Type eq 'Asset'

Field names are case-sensitive. A common mistake is using number instead of Number or isActive instead of IsActive.

Deprecation: AccountRight Classic

MYOB is retiring AccountRight Classic (v19 and earlier) on February 28, 2026. After this date, Classic company files become read-only. Users won't be able to create transactions, only view historical data.

This matters for your integration if you support customers running older AccountRight versions. After February 2026, those files will not accept new invoices or payments via the API. Affected customers need to migrate to the current AccountRight or MYOB Business product.

The API for modern AccountRight and MYOB Business is unaffected. This deprecation only impacts the legacy Classic versions that predated the current API.

Testing your integration

MYOB does not provide sandbox environments with demo data. You need to set up test data yourself, which requires understanding both the API and MYOB's accounting workflows.

Your options: create a trial MYOB Business account and populate it with test data manually, use a dedicated company file in a customer's MYOB system (with their permission), or set up a local AccountRight installation for development.

Start with read operations to verify your authentication works. Fetch company info, then retrieve customers and accounts. Once reads work, test creating a simple customer contact before moving to invoices.

Use MYOB's Postman collection to experiment with API calls before writing code. The collection is available from the developer portal.

Unified API approach

Building direct MYOB integrations requires handling OAuth flows, token management, data normalization, and ongoing API maintenance. If MYOB updates their authentication requirements (as they did in March 2025), you need to update your integration.

A unified API provider like Apideck handles this complexity. Instead of building separate integrations for each accounting platform your customers use, you build one integration against a normalized API. The provider manages authentication, handles API updates, and normalizes data structures across platforms. For a detailed comparison of approaches, see our guide on accounting integrations.

This approach works well when you need to support multiple accounting platforms or when you want to reduce ongoing maintenance burden. For teams focused on building core product features rather than becoming accounting API experts, unified APIs can significantly reduce integration time.

Frequently asked questions

Can I access multiple company files with one integration?

Yes. Each company file requires separate OAuth authorization, but your integration can store multiple sets of tokens and company file GUIDs. When making API calls, use the appropriate token and businessId for the target company file.

Does MYOB support webhooks?

No. The API does not provide webhooks for real-time notifications. You need to poll endpoints to detect changes. Use the $filter parameter with timestamps to fetch only modified records since your last sync.

What happens when AccountRight releases a new version?

MYOB releases AccountRight updates regularly, typically monthly. Each release includes a decommission date for older versions, usually 2-3 months after the new release. Plan to update your integration testing when new versions ship, as some API behaviors may change.

Can I email invoices through the API?

Yes. Endpoints like /Sale/Invoice/Item/{invoice_uid}/email let you trigger invoice emails directly from the API. The company file must be configured to send emails via AccountRight, and this only works for online files.

What's the difference between AccountRight and MYOB Business?

MYOB Business is the current product branding that replaces AccountRight and Essentials for new customers. The API is the same. AccountRight files show UIAccessFlags: 3 while Essentials files show UIAccessFlags: 2. Your integration should work with both.

Next steps

Register for a MYOB Developer account, create an API key, and start with the authentication flow. Read the endpoint documentation for contacts and invoices, since those are the most common integration points.

If you want to accelerate your timeline, start with Apideck to connect MYOB and other accounting platforms through a single unified API.

For more on building accounting integrations, see:

How to Integrate with the Odoo API

Kate Apideck — Thu, 02 Jul 2026 10:08:39 +0000

How Odoo's API Works

Odoo exposes three API protocols: XML-RPC, JSON-RPC, and a REST API (added in Odoo 17). All three access the same underlying ORM layer — the same models, fields, and methods you'd use in a Python module.

Deprecation warning: Odoo has announced that both XML-RPC (/xmlrpc, /xmlrpc/2) and JSON-RPC (/jsonrpc) are scheduled for removal in Odoo 20 (targeted for fall 2026). Odoo 19 introduced a replacement called the JSON-2 API, which uses bearer token authentication and standard HTTP conventions. If you're starting a new integration today targeting Odoo 17+, it's worth checking the JSON-2 API docs before committing to XML-RPC. For integrations that need to support older versions (14–18), XML-RPC remains the most compatible choice.

The key thing to understand regardless of protocol: Odoo's API is model-driven. Almost everything is a CRUD operation against a named model — account.move for invoices, res.partner for contacts, account.account for the chart of accounts. Once you understand this pattern, working with any Odoo module follows the same playbook.

Authentication

Odoo uses a two-step authentication process:

Call the authenticate method to get a user ID (uid)
Use that uid plus your API key or password on all subsequent calls

import xmlrpc.client

url = "https://yourodoo.com"
db = "your_database"
username = "admin@example.com"
password = "your_api_key_or_password"  # Use API keys in production

# Step 1: Get the uid
common = xmlrpc.client.ServerProxy(f"{url}/xmlrpc/2/common")
uid = common.authenticate(db, username, password, {})

# Step 2: Create the models proxy
models = xmlrpc.client.ServerProxy(f"{url}/xmlrpc/2/object")

A few things worth noting:

API keys vs passwords. Odoo 14+ supports dedicated API keys (Settings > Technical > API Keys). Always use an API key in production rather than a user password. API keys can be scoped and revoked independently.

The uid is per-session. It's a stable identifier for the user account, not a session token that expires. You can store it and reuse it, but re-authenticate if you switch credentials.

Access rights matter. The uid you authenticate with determines what models and records you can read or write. If you're hitting access errors, check the user's security groups in Odoo — not just the API code.

Core API Methods

Every Odoo model supports the same set of methods. These five cover the vast majority of integration use cases:

`search_read`

The workhorse method. Searches records matching a domain filter and returns field values in a single call.

# Get all posted (validated) customer invoices from the last 30 days
invoices = models.execute_kw(
    db, uid, password,
    'account.move', 'search_read',
    [[
        ['move_type', '=', 'out_invoice'],
        ['state', '=', 'posted'],
        ['invoice_date', '>=', '2025-02-01']
    ]],
    {
        'fields': ['name', 'partner_id', 'amount_total', 'invoice_date', 'payment_state'],
        'limit': 100,
        'offset': 0,
        'order': 'invoice_date desc'
    }
)

Always specify fields explicitly. Omitting it returns every field on the model, which is slow and produces a lot of noise.

`create`

Creates one record and returns its ID.

invoice_id = models.execute_kw(
    db, uid, password,
    'account.move', 'create',
    [{
        'move_type': 'out_invoice',
        'partner_id': 42,
        'invoice_date': '2025-03-01',
        'invoice_line_ids': [
            [0, 0, {
                'name': 'Consulting services - March 2025',
                'quantity': 10,
                'price_unit': 150.0,
                'account_id': 11,
            }]
        ]
    }]
)

The [0, 0, {...}] syntax is Odoo's "One2many command" for creating nested records inline. It's unusual but consistent — you'll see it everywhere relational fields appear.

`write`

Updates one or more records.

models.execute_kw(
    db, uid, password,
    'account.move', 'write',
    [[invoice_id], {'ref': 'PO-2025-001'}]
)

`unlink`

Deletes records. Use with care — Odoo often prevents deletion of posted records to preserve audit trails.

models.execute_kw(db, uid, password, 'account.move', 'unlink', [[invoice_id]])

`execute_kw` with custom methods

Some actions (like posting an invoice) aren't CRUD — they're state transitions. You call these as named methods on the model:

# Post (validate) a draft invoice
models.execute_kw(db, uid, password, 'account.move', 'action_post', [[invoice_id]])

Accounting Module: Key Models

Here's a map of the models you'll use most when integrating with Odoo Accounting.

Invoices and Bills — `account.move`

This single model handles customer invoices, vendor bills, credit notes, and journal entries. The move_type field distinguishes them:

move_type	Description
`out_invoice`	Customer invoice
`in_invoice`	Vendor bill
`out_refund`	Customer credit note
`in_refund`	Vendor credit note
`out_receipt`	Sales receipt
`in_receipt`	Purchase receipt
`entry`	Journal entry

Key fields to know:

fields = [
    'name',           # Invoice number (e.g. INV/2025/0042)
    'move_type',      # See table above
    'state',          # draft, posted, cancel
    'payment_state',  # not_paid, in_payment, paid, partial, reversed
    'partner_id',     # Customer or vendor
    'invoice_date',
    'invoice_date_due',
    'amount_untaxed',
    'amount_tax',
    'amount_total',
    'amount_residual', # Outstanding balance
    'currency_id',
    'invoice_line_ids',
    'journal_id',
    'ref',            # External reference / PO number
]

Invoice Lines — `account.move.line`

Individual line items on an invoice. You can query these directly for detailed reporting:

lines = models.execute_kw(
    db, uid, password,
    'account.move.line', 'search_read',
    [[['move_id', '=', invoice_id]]],
    {'fields': ['name', 'quantity', 'price_unit', 'price_subtotal', 'tax_ids', 'account_id']}
)

Payments — `account.payment`

Records of money in/out. When a payment is registered against an invoice, Odoo creates a reconciliation between the payment and the invoice line.

# Get all customer payments
payments = models.execute_kw(
    db, uid, password,
    'account.payment', 'search_read',
    [[
        ['payment_type', '=', 'inbound'],
        ['state', '=', 'posted']
    ]],
    {'fields': ['name', 'partner_id', 'amount', 'date', 'journal_id', 'ref']}
)

To register a payment against a specific invoice:

# Create payment
payment_id = models.execute_kw(
    db, uid, password,
    'account.payment', 'create',
    [{
        'payment_type': 'inbound',
        'partner_type': 'customer',
        'partner_id': 42,
        'amount': 1500.0,
        'date': '2025-03-10',
        'journal_id': 1,
        'ref': 'INV/2025/0042',
    }]
)

# Validate the payment
models.execute_kw(db, uid, password, 'account.payment', 'action_post', [[payment_id]])

Chart of Accounts — `account.account`

accounts = models.execute_kw(
    db, uid, password,
    'account.account', 'search_read',
    [[['deprecated', '=', False]]],
    {'fields': ['code', 'name', 'account_type', 'reconcile']}
)

The account_type field (Odoo 16+) replaced the old user_type_id relation. The full list of values is: asset_receivable, asset_cash, asset_current, asset_non_current, asset_prepayments, asset_fixed, liability_payable, liability_credit_card, liability_current, liability_non_current, equity, equity_unaffected, income, income_other, expense, expense_depreciation, expense_direct_cost, off_balance.

Contacts — `res.partner`

Both customers and vendors live here. The customer_rank and supplier_rank fields indicate their commercial relationship:

customers = models.execute_kw(
    db, uid, password,
    'res.partner', 'search_read',
    [[['customer_rank', '>', 0]]],
    {'fields': ['name', 'email', 'phone', 'vat', 'street', 'city', 'country_id', 'property_payment_term_id']}
)

Working with the JSON-RPC Interface

If you prefer JSON (or you're working in a language without a mature XML-RPC client), the JSON-RPC endpoint works just as well:

async function odooRequest(url, service, method, params) {
    const response = await fetch(`${url}/web/dataset/call_kw`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            jsonrpc: '2.0',
            method: 'call',
            params: {
                model: params.model,
                method: params.method,
                args: params.args,
                kwargs: params.kwargs || {}
            }
        })
    });
    const data = await response.json();
    return data.result;
}

// Authenticate
const uid = await odooRequest(url, 'common', 'authenticate', {
    db,
    login: username,
    password: apiKey
});

// Fetch invoices
const invoices = await odooRequest(url, 'object', 'execute_kw', {
    model: 'account.move',
    method: 'search_read',
    args: [[[['move_type', '=', 'out_invoice'], ['state', '=', 'posted']]]],
    kwargs: {
        fields: ['name', 'partner_id', 'amount_total', 'payment_state'],
        limit: 50
    }
});

Working with the Native REST API (Odoo 17+)

Note: This section covers the built-in REST API shipped with Odoo 17 and 18 — not any of the third-party REST modules available on the Odoo App Store. The native REST API is experimental as of Odoo 18 and has limited official documentation. For production integrations targeting Odoo 16 or earlier, use XML-RPC or JSON-RPC instead.

Authentication

The REST API authenticates using your API key as a bearer token. Generate one in Odoo under Preferences > Account Security > New API Key, then pass it in every request:

Authorization: Bearer <your_api_key>
Content-Type: application/json

If your Odoo instance hosts multiple databases, add the database name as a header:

X-Odoo-Database: your_database_name

Reading Records (GET)

import requests

base_url = "https://yourodoo.com"
api_key = "your_api_key"

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

# Get all posted customer invoices
response = requests.get(
    f"{base_url}/api/account.move",
    headers=headers,
    params={
        "domain": '["move_type","=","out_invoice"],["state","=","posted"]]',
        "fields": '["name","partner_id","amount_total","payment_state","invoice_date"]',
        "limit": 50,
    }
)

invoices = response.json()

Creating Records (POST)

response = requests.post(
    f"{base_url}/api/account.move",
    headers=headers,
    json={
        "move_type": "out_invoice",
        "partner_id": 42,
        "invoice_date": "2025-03-01",
        "invoice_line_ids": [
            [0, 0, {
                "name": "Consulting services",
                "quantity": 5,
                "price_unit": 200.0,
                "account_id": 11,
            }]
        ]
    }
)

new_invoice = response.json()
invoice_id = new_invoice["id"]

Calling Methods

State transitions like posting an invoice require calling a named method:

response = requests.post(
    f"{base_url}/api/account.move/{invoice_id}/action_post",
    headers=headers,
)

The JSON-2 API (Odoo 19+)

Odoo 19 introduced a cleaner replacement for XML-RPC and JSON-RPC called the JSON-2 API, located at /json/2/{model}/{method}. It uses the same bearer token auth but with named arguments in the request body instead of positional ones:

response = requests.post(
    f"{base_url}/json/2/account.move/search_read",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
        "X-Odoo-Database": "your_database_name",
    },
    json={
        "domain": [["move_type", "=", "out_invoice"], ["state", "=", "posted"]],
        "fields": ["name", "partner_id", "amount_total", "payment_state"],
        "limit": 50,
    }
)

The JSON-2 API is the long-term direction for Odoo's external API. If you're on Odoo 19 or planning to migrate, it's worth building against this rather than XML-RPC.

Pagination and Performance

Odoo doesn't paginate automatically. You control it with limit and offset:

def fetch_all_invoices(models, db, uid, password, batch_size=200):
    offset = 0
    all_invoices = []

    while True:
        batch = models.execute_kw(
            db, uid, password,
            'account.move', 'search_read',
            [[['move_type', '=', 'out_invoice'], ['state', '=', 'posted']]],
            {
                'fields': ['name', 'partner_id', 'amount_total', 'invoice_date'],
                'limit': batch_size,
                'offset': offset,
                'order': 'id asc'
            }
        )

        if not batch:
            break

        all_invoices.extend(batch)
        offset += batch_size

    return all_invoices

A few performance tips:

Always use order: 'id asc' when paginating to ensure stable ordering
Keep limit under 500 — larger batches increase memory pressure on the server
Use search (returns IDs only) then read (fetches specific fields by IDs) instead of search_read when you need to pre-filter a large set before loading fields
Avoid fetching binary fields (like image_1920) unless you actually need them

Handling Odoo Versions

Odoo's API surface changes between versions. The main gotchas:

Version 14 to 16: The account type system changed from a relational user_type_id field to a direct account_type string field. If you support multiple Odoo versions, you'll need to branch on this.

Version 17: A REST API was added alongside the existing XML-RPC and JSON-RPC protocols.

Version 19+: Odoo announced the deprecation of both the XML-RPC and JSON-RPC endpoints, with removal planned for Odoo 20 (fall 2026). Odoo 19 introduced a JSON-2 API as the replacement.

You can check the server version via:

version_info = common.version()
# Returns e.g. {'server_version': '16.0', 'server_version_info': [16, 0, 0, 'final', 0, '']}

Error Handling

Odoo returns errors inside the XML-RPC fault mechanism or the JSON-RPC error field. In Python, XML-RPC errors surface as xmlrpc.client.Fault exceptions:

try:
    result = models.execute_kw(db, uid, password, 'account.move', 'create', [data])
except xmlrpc.client.Fault as e:
    print(f"Odoo error {e.faultCode}: {e.faultString}")

Common error patterns:

AccessError — the user doesn't have permission on that model or record
ValidationError — a required field is missing or a constraint failed
UserError — a business rule blocked the operation (e.g. trying to delete a posted invoice)

Always log the full faultString — Odoo includes a Python traceback in it, which makes debugging much faster.

Webhooks and Real-time Sync

Odoo doesn't have native webhooks in its community edition. For real-time sync, your options are:

Polling — query for records updated since a timestamp using write_date or create_date fields
Odoo Automation — create a scheduled action or server action that calls an external URL when a record changes (Enterprise or custom module)
Database-level triggers — only viable for self-hosted deployments where you have database access
Odoo Studio — Enterprise feature that can configure webhook-style integrations

For most integrations, polling with write_date filtering works well enough:

from datetime import datetime, timedelta

since = (datetime.utcnow() - timedelta(hours=1)).strftime('%Y-%m-%d %H:%M:%S')

updated_invoices = models.execute_kw(
    db, uid, password,
    'account.move', 'search_read',
    [[['write_date', '>=', since], ['move_type', '=', 'out_invoice']]],
    {'fields': ['id', 'name', 'state', 'payment_state', 'write_date']}
)

Using a Unified API Instead

If you're building a product that needs to integrate with multiple accounting and ERP systems (QuickBooks, Xero, NetSuite, Sage, Microsoft Business Central), maintaining direct API integrations with each platform is a significant ongoing investment. Each one has different auth flows, data models, pagination patterns, and versioning behavior.

A unified accounting API like Apideck normalizes these differences behind a single endpoint. You write the integration once to a standardized Invoice, Payment, or Ledger Account model, and the platform handles the per-connector translation. This is especially useful if you're targeting vertical SaaS, embedded finance, or any segment where your customers run a mix of accounting platforms.

Apideck supports Odoo as a connector on both the Unified Accounting API and the CRM API, with 29+ normalized data models. On the accounting side, the connector covers invoices, bills, payments, bill payments, credit notes, journal entries, ledger accounts, tax rates, customers, suppliers, invoice items, company info, purchase orders, expenses, bank accounts, bank feed accounts, bank feed statements, subsidiaries, departments, locations, tracking categories, and attachments. The CRM side adds companies, contacts, leads, opportunities, activities, notes, and users.

You can include Odoo alongside QuickBooks, Xero, and the rest without maintaining a separate direct integration, and without giving up coverage of the resources that matter for real accounting workflows.

Wrapping Up

Odoo's API is mature, consistent, and surprisingly powerful once you get past the initial learning curve. The model-driven RPC approach means that anything you can do in the UI, you can do via API — including custom fields and modules added by your customers.

The main things to keep in mind as you build:

Authenticate with API keys, not passwords, in production
Learn the domain filter syntax — it's the same across every model and covers complex queries
Always specify fields in search_read to avoid pulling unnecessary data
Use write_date filtering for incremental sync rather than full refreshes
Handle Odoo version differences explicitly, especially around the accounting type system

If you're integrating with Odoo as part of a broader multi-ERP strategy, it's worth evaluating whether a unified API layer saves you time versus owning each integration directly.

Financial Statement APIs: What Most Accounting Platforms Won't Give You (and How to Get It Anyway)

Kate Apideck — Wed, 01 Jul 2026 14:12:38 +0000

Most accounting APIs will let you create an invoice, fetch a list of customers, or record a journal entry. But ask for a balance sheet or a trial balance, and things get complicated fast.

Financial statements are the output every finance team cares about most. They're what lenders use to assess creditworthiness, what FP&A tools use to build forecasts, and what auditors use to verify the books. Yet the APIs behind popular accounting platforms treat financial statements as an afterthought, if they expose them at all.

If you're building a SaaS product that needs financial statement data from your customers' accounting systems, you need to understand which statement types are available and how to work around the gaps.

The full picture: types of financial statements

Before getting into API availability, it helps to be specific about what "financial statements" actually means. Five statement types matter for most integration use cases, and they vary wildly in how well accounting APIs support them.

P&L statements and balance sheets sit at the top of the availability spectrum. Most major accounting platforms expose some form of endpoint for these two reports, though the depth and format differ. P&L shows revenue and expenses over a period, netting out to income or loss. Balance sheets capture a company's financial position (what it owns versus what it owes) at a specific point in time.

Cash flow statements and trial balances are where things get thin. A cash flow statement reclassifies accrual-basis data into standardized cash flow categories. Xero's Finance API exposes a cash flow endpoint but restricts it to non-U.S. entities. QuickBooks Online has a cash flow report, but the response format is designed for HTML rendering rather than programmatic use. Many platforms simply don't offer it. Trial balances, which list every account with its debit or credit balance, face a similar problem: some platforms expose them as reports, others expect you to reconstruct them from ledger account data.

The statement of changes in equity sits at the bottom of the stack. It tracks how equity changed over a period through items like net income and dividends. Very few accounting APIs expose this as a dedicated endpoint. In most cases, you'd derive it from balance sheet snapshots at two points in time.

The pattern: the further you get from P&L and balance sheet, the thinner API support becomes.

Why the gaps exist

An accounting API that gives you access to invoices, bills, and the rest of the general ledger is giving you the raw ingredients. A financial statement is the cooked meal. The distance between those two things is significant.

Financial statements require aggregation logic that varies by report type and accounting method (cash vs. accrual), plus date range and chart of accounts structure. Most accounting platforms built their APIs around CRUD operations on individual records, not around computed reports. Adding report endpoints means exposing business logic that was originally designed for the platform's own UI, and each provider has done this differently, if they've done it at all.

The endpoint fragmentation becomes obvious once you look at the actual APIs. QuickBooks Online exposes reports at a company-specific path:

GET /v3/company/<realmID>/reports/ProfitAndLoss?start_date=2025-01-01&end_date=2025-12-31
GET /v3/company/<realmID>/reports/BalanceSheet?date=2025-12-31

The response is a recursive row/column structure with headers and data cells mixed into a single nested array. It was designed for rendering HTML tables in the QuickBooks UI, not for programmatic consumption. Parsing it into a usable data structure requires custom logic for every report type.

Xero splits financial statement data across two separate APIs. The standard Accounting API has report endpoints:

GET /api.xro/2.0/Reports/ProfitAndLoss?fromDate=2025-01-01&toDate=2025-12-31
GET /api.xro/2.0/Reports/BalanceSheet?date=2025-12-31
GET /api.xro/2.0/Reports/TrialBalance?date=2025-12-31

And the Finance API (which requires separate partnership approval) exposes a different set:

GET /finance.xro/1.0/financialstatements/profitandloss
GET /finance.xro/1.0/financialstatements/balancesheet
GET /finance.xro/1.0/financialstatements/cashflow  // not available for U.S. entities

The two APIs return different response schemas for the same data. And the Finance API's cash flow endpoint doesn't work for U.S. organizations at all.

NetSuite buries financial reports behind SuiteQL or saved search configurations that require significant setup. Sage Intacct requires you to define report templates before you can pull data. Each platform has its own authentication flow and its own response schema.

If you're building integrations with multiple accounting platforms, you're writing and maintaining entirely separate parsing logic for each one.

Real use cases that depend on clean financial statement data

The demand for financial statement APIs comes from a few distinct product categories.

Lending and underwriting platforms are probably the most obvious consumer. They pull P&L statements and balance sheets to assess creditworthiness. A lender evaluating a small business needs gross margin trends and current ratio computed from financial statement data. Manual document collection (requesting PDFs over email and re-keying numbers into a spreadsheet) adds days to the underwriting process. API access cuts that to minutes. Some lenders also pull trial balances for deeper account-level analysis during due diligence.

Financial planning tools are another major category. Causal, a financial planning platform, integrated with customers' accounting systems to pull financial statement data into an AI-powered modeling tool. Users connect their QuickBooks or Xero account, and the platform auto-generates financial models with metrics like burn rate and runway, updated on a recurring schedule. Cash flow data is especially valuable here: forecasting tools that can ingest historical cash flow statements produce meaningfully better projections than those working from P&L alone.

Then there's the growing segment of vertical SaaS products that embed financial dashboards directly in their UI. A construction management platform might display a contractor's cash position alongside project data. A healthcare practice management tool might show monthly P&L trends next to patient volume. In both cases, the product team needs financial statement data arriving in a predictable format, on a reliable schedule, from whatever accounting system the customer happens to use.

Building it yourself vs. using a unified API

If you only need to support one accounting platform, building a direct integration for financial statements is feasible, if tedious. You'll parse the provider's report format, map it to your internal schema, handle rate limits, and maintain it as the provider's API evolves. (For a full breakdown of what that build process looks like, including authentication, sync patterns, and scaling, see the complete fintech accounting API guide.)

The math changes when you need to support five or ten or twenty platforms. Each one has different authentication flows (OAuth 2.0 is standard, but implementation details vary widely) and different data models, with varying levels of financial statement support. Some platforms version their APIs aggressively; Xero has deprecated and replaced major endpoints multiple times. Others, like QuickBooks Desktop, still rely on SOAP-based communication through a local Web Connector.

A unified API normalizes these differences behind a single interface. You build one integration, and the unified API provider handles the per-platform mapping and ongoing maintenance.

Compare the endpoint fragmentation above with Apideck's Accounting API, which covers the two most requested financial statement types natively. Balance Sheet and Profit and Loss endpoints work across 45+ accounting connectors, with a consistent schema regardless of the downstream platform. Aging reports (Aged Creditors and Aged Debtors) round out the reporting layer. Instead of writing separate parsing logic for QuickBooks' nested row structure and Xero's report schema, you write one call:

import { Apideck } from '@apideck/unify'

const apideck = new Apideck({
  apiKey: process.env.APIDECK_API_KEY,
  appId: 'YOUR_APP_ID',
  consumerId: 'YOUR_CONSUMER_ID'
})

// Pull a balance sheet from any connected accounting platform
const result = await apideck.accounting.balanceSheet.get({
  serviceId: 'quickbooks', // or 'xero', 'sage-intacct', etc.
  filter: {
    startDate: '2025-01-01',
    endDate: '2025-12-31',
    periodCount: 12,
    periodType: 'month',
  },
})

For statement types that fall outside the unified schema (trial balance, cash flow, equity changes), Apideck's Proxy feature fills the gap. The Proxy lets you make native API calls to the downstream accounting platform while still using Apideck's managed authentication and connection infrastructure. You get the benefit of not having to handle OAuth flows or token refresh for each provider, while accessing any endpoint the provider exposes, including report types that aren't part of the unified model.

In practice, this means your integration architecture can use unified endpoints for P&L and balance sheet data (where you get normalized schemas across all connectors) and fall back to Proxy calls for provider-specific reports like trial balances or cash flow statements. You handle two code paths instead of twenty.

What to evaluate in a financial statement API provider

Not every unified API covers financial statements with the same depth. When you're evaluating options, a few things matter more than they might initially seem.

Connector coverage for report endpoints is the first thing to check. A provider might support 20 accounting platforms for invoices and bills but only three for balance sheets. Financial statement support is often the last thing to ship because it requires more complex mapping.

Filtering and date range support also matter more than you'd expect. Can you request a P&L for a specific quarter? A balance sheet as of a specific date? For forecasting and trend analysis, historical snapshots are critical.

Schema depth determines how useful the data actually is once it arrives. Does the unified schema preserve the chart of accounts hierarchy? Can you distinguish between current and non-current assets? Flattened schemas lose information that matters for financial analysis.

Then there's data freshness. Some unified APIs cache data and sync on a schedule. Others pass requests through to the source API in real time. For financial statements that inform lending decisions, stale data is a real risk. Apideck takes the real-time approach: API calls are processed and passed directly from source to your app, with no data stored in between.

Finally, check whether the provider offers a passthrough or proxy mechanism for report types outside the unified schema. If your product only needs P&L and balance sheets today but might need trial balances or cash flow statements tomorrow, a provider with a strong proxy layer saves you from having to build and maintain a separate direct integration later.

Where this is heading

Financial statement data is some of the most valuable information locked inside your customers' accounting systems. Getting to it programmatically is harder than it should be, because most accounting platforms designed their APIs around transactions, not reports. And the problem gets worse the further you move beyond P&L and balance sheets into trial balances and cash flow reporting.

You can build custom report-parsing logic for every platform and every statement type you need to support. Or you can use a unified API that covers the core statement types natively and gives you a clean fallback for everything else.

If your product depends on financial statement data from customers' accounting systems, Apideck's Accounting API gives you normalized Balance Sheet and P&L endpoints across 45+ platforms, plus aging reports and a Proxy layer for accessing any provider-specific report endpoint. One integration, the full reporting picture.