The first half of 2026 was a heavy stretch of connector work at Apideck. We shipped more than 25 new connectors and expanded coverage on the platforms our customers already build with. Most of the new connectors are accounting API connectors, and two of them are launches we had wanted to ship for a long time: **QuickBooks Desktop** and **SAP S/4HANA Cloud**, two of the most-requested platforms on our roadmap, both are now live in beta.

Together they extend the Unified Accounting API into the platforms that tend to decide deals, from on-premise SMBs through to enterprise ERP. Here is what shipped, starting with those two.

## The headline launches: QuickBooks Desktop and SAP S/4HANA

**QuickBooks Desktop** is the release we heard the most demand for. A large share of established small and mid-sized businesses still keep their books on the desktop product rather than QuickBooks Online, and reaching it directly has meant owning a SOAP-era Web Connector that few engineering teams want on their roadmap. The [QuickBooks Desktop connector](https://www.apideck.com/integrations/quickbooks-desktop) puts that platform behind Apideck's [unified accounting API](https://www.apideck.com/accounting-api), with read access to the core ledger, from customers and invoices through to journal entries and purchase orders.

**SAP S/4HANA Cloud** opens the opposite end of the market. Enterprise ERP usually sits behind SAP-specific tooling and consultants, which keeps smaller product teams out of enterprise deals. The [SAP S/4HANA Cloud connector](https://www.apideck.com/integrations/sap-s4hana-cloud) reads the core transaction set plus subsidiaries and departments for multi-entity structures, so an enterprise prospect on SAP no longer means a months-long bespoke build before you can pull their data.

Both shipped in beta and read-only first, on purpose: it lets teams start building and testing against real data right away, and it already serves the many use cases that only need to read accounting data. Write support is on the way, so anything that needs to push data back can switch on when it lands.

## Three more global platforms

Three more launches widen the global core:

- [Stripe](https://www.apideck.com/integrations/stripe) brings billing and payments data into the accounting model for any product that reconciles revenue, covering invoices, payments, refunds, and more
- [Intuit Enterprise Suite](https://www.apideck.com/integrations/intuit-enterprise-suite) connects alongside QuickBooks Online for customers moving up-market within the Intuit family, so a growing customer becomes a configuration change rather than a new integration
- [Odoo](https://www.apideck.com/integrations/odoo) , the open-source ERP from the fast-growing Belgian company, ships with one of the deepest resource sets we offer, spanning accounting and operations

That completes the Intuit lineup: with QuickBooks Desktop and Intuit Enterprise Suite added, all of Intuit's products now run through one schema.

## Broader reach across European accounting

A unified API is only as useful as its coverage in the markets where your customers operate, and Europe runs on local accounting platforms. This year added the ones that anchor their home markets:

- [Pennylane](https://www.apideck.com/integrations/pennylane), the fast-growing French platform for SMBs and their accountants
- [Moneybird](https://www.apideck.com/integrations/moneybird) and [Yuki](https://www.apideck.com/integrations/yuki), both widely used across the Netherlands and Belgium, Yuki especially among accounting firms
- [Datev Unternehmen Online](https://www.apideck.com/integrations/datev-unternehmen-online), the system most German tax advisors and their clients work in
- [Holded](https://www.apideck.com/integrations/holded), the all-in-one business and accounting platform common among Spanish SMBs
- [Spiris/Visma eAccounting](https://www.apideck.com/integrations/spiris) and [Fortnox](https://www.apideck.com/integrations/fortnox), two mainstays of the Swedish and Nordic market
- [Wafeq](https://www.apideck.com/integrations/wafeq), built for the Middle East and the GCC, where e-invoicing mandates in Saudi Arabia and the UAE are moving SMBs onto cloud bookkeeping

Expanding into one of these markets used to mean a fresh integration for the local platform your users expect. Increasingly it is already supported, which turns a regional launch into a configuration change.

## Next-generation ERP and accounting tools

Alongside the established names, a wave of modern and AI-native finance platforms got connectors this year. These are the tools fast-growing finance teams are adopting now:

- [Rillet](https://www.apideck.com/integrations/rillet), an AI-native general ledger, with read and write support
- [Dualentry](https://www.apideck.com/integrations/dualentry), built for multi-entity startups
- [Digits](https://www.apideck.com/integrations/digits) and [Campfire](https://www.apideck.com/integrations/campfire), two AI-native platforms aimed at modern finance teams
- [Wave](https://www.apideck.com/integrations/wave), the free accounting product popular with smaller businesses

Supporting these early keeps your product relevant to customers who have already moved off legacy software.

## Going deeper on the accounting API connectors you already use

New connectors are half the story. The platforms carrying the most production traffic also gained coverage, because a connector that handles 80 percent of a workflow still leaves the rest on your plate. The headline additions:

- [NetSuite](https://www.apideck.com/integrations/netsuite): Profit and Loss and Balance Sheet reports, plus Employees, Expense Categories, and Expense Reports
- [Sage Intacct](https://www.apideck.com/integrations/sage-intacct): Subsidiaries, Projects, Bank Feed Statements, and full Employee support
- [QuickBooks](https://www.apideck.com/integrations/quickbooks): a dedicated Refunds resource and Projects
- [Microsoft Dynamics 365 Business Central](https://www.apideck.com/integrations/microsoft-dynamics-365-business-central): Bill Payments and employee accounts on journals and expenses
- [Exact Online](https://www.apideck.com/integrations/exact-online) and [Workday](https://www.apideck.com/integrations/workday): Payments and Bill Payments

One release cuts across many of these at once: a multi-entity Companies resource across Xero, Sage Intacct, and other multi-company connectors. A customer running several legal entities under one login can now list those entities and target the right one through a single connection, which removes a common source of friction for accounting firms and multi-subsidiary businesses. The [changelog](https://developers.apideck.com/changelog) has the rest, down to the resource and operation.

## Beyond accounting

The year's work was not limited to finance:

- [Remote](https://www.apideck.com/integrations/remote), for HRIS data (employees, time off, payroll)
- [JobAdder](https://www.apideck.com/integrations/jobadder), for applicant tracking
- [Folk](https://www.apideck.com/integrations/folk), a CRM connector
- [Linear](https://www.apideck.com/integrations/linear) and Jira Teams, for engineering and issue-tracking workflows

Existing connectors improved too. Shopify and HiBob moved to modern OAuth, and connection reliability gained token-refresh webhook events. A maintained connector keeps getting better without anything changing on your side.

## Where to start

If a platform on this list maps to a deal you are working or a customer request you have parked, open the [connector library](https://www.apideck.com/integrations) and check the resource coverage, then wire it into your existing integration. You can test against any connector on a [free trial](https://www.apideck.com/signup), or [book a demo](https://www.apideck.com/demo-request) to walk through a specific market or system.

If the platform you need is not here yet, [tell us](https://requests.apideck.io/request). Customer demand is how we prioritise what to build next, and a good share of this year's releases started as exactly that kind of request.

Product

Explore Apideck’s 2026 connector updates, including 25+ new integrations across accounting, ERP, HRIS, CRM, and ATS. See what shipped for QuickBooks Desktop, SAP S/4HANA Cloud, Stripe, Odoo, NetSuite, Sage Intacct, and more.


QuickBooks Desktop, SAP S/4HANA, and 25 more new connectors in 2026

Most small businesses still run accounts payable the slow way. Someone keys the bills into a separate tool by hand, then exports a CSV at month end to reconcile against the accounting system. The work sits outside the products the business uses every day, and the lost time adds up.

Embedded finance agents change that, and Dolfin AI is building them. That is why we are partnering with them.

[Dolfin](https://www.dolfinai.co/) builds embedded, white-label accounts payable and receivable agents that banks and software platforms can offer their SMB customers. The agents run invoicing, bill payment, and reconciliation inside the product a business already logs into, and a user can instruct them in plain language instead of clicking through forms. Apideck provides the connectivity underneath: one unified API across more than 40 accounting and ERP systems. You can see the scale of the opportunity in our [State of B2B Embedded Finance report](https://www.apideck.com/embedded-finance-report), where BCG and Adyen put the SaaS-addressable market at 185 billion dollars with less than 20 percent captured so far.

## What Dolfin actually builds

Inside the bank or the software platform, fully white-labeled, a business sees a financial operations screen with its invoices and bills. Alongside it sits an agent. A user can type "invoice Acme for 10 units at 25 euros and send it," and the agent creates the customer if needed, then builds and sends the invoice with a payment link. On the payables side, the agent reads incoming bills and schedules them for payment once approved.

The product reflects where financial software is going. The job that used to live in a standalone destination like Bill.com is moving into the systems a business already uses, the bank and the platform, and increasingly an agent does the work. As James Regan, Dolfin's CEO, describes it, businesses would rather the system they already log into did more, instead of adopting yet another point solution to manage.

## Why embedded finance agents need a connectivity layer

An agent that drafts an invoice is only useful if that invoice lands in the customer's real accounting system, and the payment that follows is matched and posted back. That write-back is the part teams underestimate. Reading data from QuickBooks is one problem. Writing a bill into NetSuite and confirming it posted, with its tax logic applied correctly, is a harder one.

The difficulty grows with coverage. Accounting is regionally fragmented, with more than 20 major platforms and the top five vendors holding only about half of global share (BCG and Adyen). A bank serving SMBs in the Benelux needs Exact and Yuki. A US bank needs QuickBooks and NetSuite. Building and maintaining each of those connections in-house runs 50,000 to 150,000 dollars per integration per year, and the point where a unified API becomes cheaper arrives at four to five integrations, according to the same research.

Apideck handles that layer: the connection management and the write-back across accounting systems, behind one data model. For an agent builder, that means a single interface to read bills and push invoices across more than 40 systems, rather than a separate integration project for each platform. Dolfin builds the agent and the experience; we make sure it can reach what sits behind it.

## The use cases this unlocks

Three patterns matter most for the businesses Dolfin serves.

### Accounts payable that closes the loop

An agent ingests vendor bills and writes the payment back to the customer's ledger once approved, so the books stay current without anyone exporting a file. This is the [accounts payable automation](https://www.apideck.com/use-cases/accounts-payable-automation) pattern, run by an agent instead of a screen full of forms.

### Invoicing and accounts receivable

A user asks the agent to bill a customer. The agent creates the invoice in the connected accounting system and matches the incoming payment once it arrives. [Accounts receivable automation](https://www.apideck.com/use-cases/accounts-receivable-automation) becomes a conversation the user can have rather than a workflow they have to drive.

### Reconciliation across systems

When payments and invoices flow through the bank or platform, they can be matched and posted to the general ledger automatically. The alternative is the CSV-export-and-rekey routine that embedded financial products are meant to retire, a problem we have written about for [vertical SaaS](https://www.apideck.com/blog/embedded-finance-vertical-saas).

![Dolfin Financial OS](//images.ctfassets.net/d6o5ai4eeewt/4UAIUlXx6Xezbn41PDikNl/da2409669058cd4f5aadb3adbaadbc72/Dolfin_platform.png)

## Which customers this is relevant for

Three profiles fit best.

### Banks and neobanks serving SMBs

This is the clearest case. Business banking that wants to put real financial management in front of customers can offer AP and AR agents under its own brand, with the accounting write-back handled underneath. The white-label model is built for it.

### Vertical SaaS platforms for small businesses

A platform sitting in a daily workflow already owns the customer relationship and the data. Adding embedded financial operations deepens that without standing up an accounting integration team. About 60 percent of small US businesses already run on vertical SaaS (BCG and Stripe), which is the distribution that makes the model work.

### Agent-first B2B fintech

Teams building agent-native financial products from scratch get the operations agent from Dolfin and the connectivity from Apideck, instead of constructing both and maintaining the second one forever.

This is not the right fit for everyone. A product built around a single ERP with deep customization, or one that needs only one or two integrations, will see less return from a unified layer. The economics show up once you support several systems across regions, the four-to-five integration threshold again.

## What comes next

We are collaborating on product now, with Dolfin testing what we ship and telling us what agent builders need from a connectivity layer. As shared customers come on, the integration will deepen. The bet behind it is simple: financial operations are moving into the tools businesses already use, run by agents, and those agents need a dependable way to reach every accounting system behind them.

If you are building financial operations into a bank or a platform, the connectivity is the piece you do not want to maintain yourself. See how the [accounting API](https://www.apideck.com/accounting-api) handles read and write across systems, or read more on [what embedded finance means for B2B platforms](https://www.apideck.com/blog/what-is-embedded-finance).

Apideck is partnering with Dolfin AI to power embedded finance agents for banks and SaaS platforms. The AP and AR use cases, and who they fit.

Apideck and Dolfin AI: the connectivity layer for embedded finance agents

Toast generates over 80% of its roughly $5 billion revenue from financial services. Shopify originated $4.2 billion in merchant lending in 2025. Square has lent over $22 billion to small businesses with loss rates below 3%. These are not fintech companies. They are vertical SaaS platforms that figured out the same thing: the software gets you the customer, and the financial product gets you the revenue.

The question is whether your platform is next, or whether you are watching your competitors figure this out first.

We just published [*The State of B2B Embedded Finance*](https://www.apideck.com/embedded-finance-report) report: 60+ pages of market data, use cases, vendor analysis, risk frameworks, and implementation playbooks built from public SEC filings, independent research from BCG, Bain, McKinsey, and EY-Parthenon, a provider analysis of 300+ embedded finance vendors tracked by the [Open Banking Tracker](https://www.openbankingtracker.com/embedded-finance), and an original practitioner survey.

This post gives you a preview. The report gives you the full picture.

## The gap is closing fast

BCG and Adyen estimate $185 billion in addressable [embedded finance](https://www.apideck.com/blog/what-is-embedded-finance) revenue for SaaS platforms across North America and Europe. Less than 20% has been captured so far. That sounds like plenty of runway, but the window is narrowing. The platforms moving now are locking in the switching costs that will make it hard for latecomers to compete.

![he State of B2B Embedded Finance Report: $150B+ in Revenue That Most SaaS Platforms Haven't Touched 1](//images.ctfassets.net/d6o5ai4eeewt/6uHzkKnzKOaaceaaUpKLT2/bfd2441db4af913e129ed7c6aecd2ffe/Section_2__Market_Size___Growth_Trends_.png)

If your platform already offers embedded payments, you are in the majority: over 60% of North American ISVs do. But payments is the entry point, not the destination. The real revenue sits in the categories most platforms have not touched yet.

![he State of B2B Embedded Finance Report: $150B+ in Revenue That Most SaaS Platforms Haven't Touched 2](//images.ctfassets.net/d6o5ai4eeewt/5AblixxoGVBQgLB6FezBj5/1a3301236f0c084a1c6e82ad06c02ee0/Section_2.4__Adoption_and_Investment_.png)

Lending, banking, payroll, insurance, accounting: all below 40% adoption among platforms. Every one of these categories has documented evidence of 2x to 5x revenue per customer uplifts, significant churn reductions, and retention rates that software-only competitors cannot match. The report breaks down the exact benchmarks, sourced from SEC filings and randomized controlled trials, not vendor marketing.

Your competitors are reading those benchmarks right now. The practitioner survey in the report shows 68% of respondents are already live with embedded finance features, and another 18% are actively building. If you are still evaluating, you are in the remaining 14%.

## Your competitors are already moving into lending

Payments is where most platforms start. Lending is where the smartest ones are going next. In our practitioner survey, 68% named embedded lending as a target capability, ahead of payments at 59%. That is a significant shift, and the platforms acting on it are pulling ahead.

The report covers why [platform-based lending](https://www.apideck.com/blog/embedded-lending-revenue-financing-banking-accounting-commerce-data) works so well (your transaction data is a better underwriting signal than anything a bank has), which orchestration providers remove the balance-sheet objection so you can launch without a loan book, and which platforms are posting repeat rates above 70%. It also covers the specific revenue acceleration data from a published randomized controlled trial, the kind of evidence you can put in front of a board.

If lending is on your roadmap for the next 12 months, the lending section of this report will save you weeks of research.

## The data layer that makes or breaks your product

The [embedded finance products](https://www.apideck.com/blog/what-is-open-accounting) that generate the highest revenue in B2B (lending, reconciliation, financial health scoring) all depend on structured accounting data. Not bank transaction data. Accounting data: ledgers, invoices, receivables, margins.

The problem is fragmentation. QuickBooks dominates the US. Germany runs on DATEV. The Nordics run on Visma. France runs on Sage. The top five vendors globally hold only 45 to 53% of the market. If your platform serves customers in more than one region, you are facing an integration challenge that gets more expensive with every market you enter.

The report maps the full fragmentation picture across [20+ accounting platforms](https://www.apideck.com/blog/top-15-accounting-apis-to-integrate-with), breaks down the real cost of direct integrations versus [unified API aggregation](https://www.apideck.com/blog/what-is-a-unified-api), and identifies the inflection point where the economics flip. If you are about to commit engineering resources to accounting integrations, this section could save you six figures in the first year alone.

## Six companies got embedded finance wrong. Learn from them before you start.

This is the section of the report that should slow you down if you are moving fast. Synapse collapsed as a ledger intermediary in 2024, leaving a $65 to $95 million customer shortfall across 100+ fintechs. Blue Ridge Bank and Evolve Bank both received consent orders. Solaris faced BaFin restrictions. Railsr entered administration. Intergiro lost its licence with no warning.

Every one of these failures followed the same pattern: rapid growth without proportional compliance investment, combined with downstream platforms that had no contingency plan. BaaS-related enforcement accounted for 18.3% of all federal banking enforcement in H1 2024. The report analyzes each case and extracts specific lessons for sponsor bank selection, reconciliation architecture, and compliance staffing.

If your embedded finance strategy depends on a single infrastructure provider, you need to read this section before you sign that contract.

## What else is inside

The report covers more than what this post can. Seven [vertical deep dives](https://www.apideck.com/blog/embedded-finance-vertical-saas) with provider tables and documented implementations from Toast, Mews, Procore, Jobber, and ServiceTitan. A [four-layer vendor taxonomy](https://www.apideck.com/blog/embedded-finance-companies-landscape) with a build-buy-partner decision framework. [Provider evaluation criteria](https://www.apideck.com/blog/financial-api-integration) covering pricing at current and 10x volume. A phased implementation playbook with timelines and benchmarks. An ROI summary that consolidates every revenue, retention, and adoption number in one place.

The platforms that move on embedded finance in the next 12 months will capture a disproportionate share of the remaining opportunity. The ones that wait will find higher switching costs, more entrenched competitors, and fewer provider options.

The full report is [available here](https://www.apideck.com/embedded-finance-report). If you are evaluating accounting integrations as part of your embedded finance stack, start with [The Complete Guide to Accounting API Integrations for Fintech](https://www.apideck.com/blog/the-complete-guide-to-accounting-api-integrations-for-fintech).

## We're building something bigger

The report covers the market, the use cases, and the risks. The Embedded Finance Index goes further. We analyzed the public stacks of 3,580 embedded finance vendors across 781 verified providers, 12 infrastructure layers, and 9 regions to answer a question no one had mapped before: what does the embedded finance ecosystem actually run on? Which sponsor banks back which fintechs. Which providers dominate each layer. Where the compliance stack goes dark. The Index updates continuously as providers appear, disappear, and get acquired, so the data is always current in a market that shifts fast.

[![The State of B2B Embedded Finance in 2026 button](//images.ctfassets.net/d6o5ai4eeewt/51XARIuWaQkk42mW4lyvMa/a0a2b691f04df0e6300cc36520c381ef/ChatGPT_Image_Jun_2__2026__07_27_33_PM.png)](https://share-eu1.hsforms.com/1rufbeKxHShC53kUBGIto-g2e2k0f)


Company news

BCG and Adyen estimate $185 billion in addressable embedded finance revenue for SaaS platforms. Less than 20% has been captured. Our new 60+ page report covers market sizing, use cases, vendor analysis, risk frameworks, and implementation playbooks for B2B SaaS, vertical SaaS, and fintech decision-makers.

The State of B2B Embedded Finance Report: $150B+ in Revenue That Most SaaS Platforms Haven't Touched

Windsurf, one of the fastest-growing AI coding companies, runs its entire finance operation with two people. Postscript, a SaaS business doing more than $100M in ARR, closes its books in three days. Both run on [Rillet](https://www.rillet.com/), an AI-native ERP that has raised more than $100 million in funding inside its first year. Look past the funding to the two-person finance team.

For thirty years, bookkeeping and accounting software meant the same thing. QuickBooks. Xero. Sage. NetSuite. One product, one login, one ledger. That bundle is coming apart, and the unbundling matters for any SaaS, vertical SaaS, or embedded finance product that touches financial data.

## Bookkeeping and accounting software: always two jobs

Bookkeeping is the data layer. Recording transactions, categorizing expenses, matching payments to invoices, reconciling bank feeds. Mechanical work at high volume, where errors break everything downstream.

Accounting is the interpretation layer. Producing financial statements, running the month-end close, applying revenue recognition rules, generating reports for boards and lenders. Judgment work that depends on the bookkeeping being clean. If you build software that talks to accounting systems, [the data model of every accounting API](https://www.apideck.com/blog/accounting-for-developers) is shaped by these rules.

[QuickBooks](https://www.apideck.com/connectors/quickbooks) bundled both because in 1992 there was no practical way to separate them. The bookkeeping data lived inside the product, so the reporting had to live there too. Xero did the same in 2006. NetSuite did the same for the mid-market. The bundle was a constraint of the architecture, not a deliberate product choice.

Two things broke the constraint. First, accounting data moved out of the ledger and into upstream sources. Stripe pushed in revenue. Ramp and Brex pushed in card spend. Gusto and Rippling pushed in payroll. Mercury pushed in cash transactions. For a typical SaaS startup in 2025, much of the journal entry volume in QuickBooks comes from automated feeds. The ledger has become a destination. The system of record has moved upstream.

Second, language models got good enough to do the categorization and close work that used to require a person. Not perfectly, but well enough that a finance team of two can run a $100M ARR company.

## The new bookkeeping layer

The first wave of AI-native entrants attacked the bookkeeping job specifically.

[Kick](https://www.kick.co/) was founded by Conrad Wadowski. After his $250M Teachable exit, he set out to build what Kick calls self-driving bookkeeping for the self-employed. The company [raised a $9M seed](https://www.axios.com/pro/fintech-deals/2024/10/17/bookkeeping-startup-kick-9-million-ai) from General Catalyst and the OpenAI Startup Fund in October 2024. The product reads bank and card transactions, identifies which ones are business-related, and categorizes them for tax. Cash-basis only, which limits the addressable market to sole proprietors and very small businesses. Inside that segment, Kick removes most of the work that QuickBooks Self-Employed still requires a human to do.

[Puzzle.io](https://puzzle.io/) took a different angle. Sasha Orloff, who previously built LendUp, is the CEO. He has [raised more than $50M](https://puzzle.io/blog/puzzle-raises-an-additional-30m-to-fuel-a-new-era-of-ai-powered-accounting) from General Catalyst and Felicis to rebuild the general ledger from scratch for startups on accrual accounting. The product pulls transactions automatically from the fintech stack (Stripe, Brex, and similar spend and payroll platforms) and lets the AI handle the categorization and entry work that used to require a junior bookkeeper. The pitch is real-time accrual financials for venture-backed companies that need clean books for fundraising.

[Digits](https://digits.com/) sits somewhere between the two. Jeff Seibert founded it in 2018 and launched it publicly in November 2023. The company is now sitting on close to $100M from Benchmark and other top-tier funds. The product calls itself an Autonomous General Ledger. It runs vertical LLMs trained on accounting data and ships AI agents that handle bill pay and categorization. Craig Walker joined the Digits leadership team in March 2025. He had previously co-founded Xero and served as its CTO. Reported customers include Particle News and Wispr.

These products differ in target customer and depth. They share an assumption: the bookkeeping work is mostly mechanical and can be done by software that reads transactions and applies rules. They are betting the data layer no longer needs a person in the loop for most companies.

## The new accounting layer

The second wave is attacking the interpretation job. These products replace NetSuite.

Rillet was founded in 2024. The CEO is Nicolas Kopp, who had previously run N26 in the US. The company raised a $25M Series A from Sequoia in May 2025. [A $70M Series B from Andreessen Horowitz and ICONIQ](https://www.rillet.com/blog/rillet-raises-70m-series-b-from-andreessen-horowitz-and-iconiq) followed ten weeks later. The product is an AI-native ERP aimed at mid-market SaaS companies that have outgrown QuickBooks or Xero. These companies balk at a 12-month NetSuite implementation. Postscript closes its books in three days. Windsurf runs finance with two people. The close itself, the part that has always taken weeks of human judgment work, gets compressed by AI agents that reconcile entries and post accruals.

[Campfire](https://www.campfire.ai/) was founded by John Glasgow in 2023. He previously worked at Invoice2go, which Bill.com acquired for $625M. The company [raised $100M across Series A and B](https://www.prnewswire.com/news-releases/campfire-raises-65-million-series-b-to-redefine-how-finance-works-in-the-ai-era-302585077.html) inside twelve weeks in mid-2025, with Accel and Ribbit leading. The product replaces legacy ERPs with a general ledger and revenue automation, plus a conversational AI interface called Ember. Flex, one of Campfire's reference customers, cut its close from ten days to three with 67% fewer accounting resources.

[DualEntry](https://www.dualentry.com/) launched from stealth in October 2025. The $90M Series A was led by Lightspeed and Khosla. Co-founders Santiago Nestares and Benedict Dohmen had previously scaled an e-commerce company to nine-figure revenue on legacy ERP. They built DualEntry as an AI-native ERP covering general ledger, AR, AP, and FP&A in one system. The product leads with NextDay Migration, which moves historical data off legacy systems in 24 hours instead of the months that traditional ERP migrations take. [Slash](https://www.dualentry.com/customers/slash), a $140M revenue fintech, runs its entire finance function with one person on DualEntry. The migration was off QuickBooks Online. The platform automates roughly 90% of the manual tasks that team would otherwise be doing by hand.

These companies are going after the workload that Oracle and SAP have charged seven-figure ARRs to handle for decades. The close runs on AI agents with a small human team auditing the outputs.

## What this means if you build software

If your product writes data into accounting software, the integration surface is widening. A customer on QuickBooks today might move to an AI-native ledger like Puzzle in two years. The data shape is similar across all of them because the underlying accounting model has not changed. The API mechanics, the auth flows, the field names, and the rate limits are all different. This is the integration problem that any [accounting software integration](https://www.apideck.com/blog/accounting-software-integration) team is now planning around.

Two things follow.

Integration surface area used to be an engineering question. It has become a product question. Picking one accounting integration to start used to be reasonable because QuickBooks dominated the US SMB market. Intuit's small business and self-employed segment generated $8 billion in revenue in 2023, and QuickBooks Online has more than 6 million customers globally. The dominance is real. The long tail is moving faster than it ever has, and the customers most likely to switch to an AI-native ledger are the same customers most likely to be early adopters of your product. If your integration strategy assumes QuickBooks plus Xero is enough, you will lose deals to competitors with broader coverage.

The AI-native ledgers are also designed API-first. They expose cleaner transaction data than QuickBooks does, with fewer of the historical quirks that come from a thirty-year-old data model. This is the practical face of [open accounting](https://www.apideck.com/blog/what-is-open-accounting). For products that read from accounting systems, this is good news. For products that write, it is more complicated, because each new ledger has its own validation rules and its own opinions about what a clean journal entry looks like.

The honest answer is that the accounting integration problem is getting harder. The number of platforms is growing and the rate of change inside each platform is increasing. Customers expect your product to work across all of them. Our [accounting integration coverage radar](https://www.apideck.com/integrations/accounting-coverage) shows what each platform supports and where the gaps are.

Apideck offers a unified accounting API. It connects to QuickBooks, Xero, and 20+ other ledgers through one integration, with consistent data models across vendors. The [Apideck Accounting API](https://www.apideck.com/unified-apis/accounting) is free for 30 days.

Industry insights

Bookkeeping and accounting software have always been bundled. AI-native entrants like Kick, Puzzle, Rillet, Campfire, and DualEntry are splitting them apart.

Bookkeeping vs Accounting Software: Why AI Is Splitting the Bundle

Twinfield is the cloud accounting platform [Wolters Kluwer acquired in 2011](https://www.wolterskluwer.com/en/news/wolters-kluwer-tax-accounting-expands-european-online-software-solutions-with-acquisition-of-twinfield) to anchor its European tax and accounting suite. In the Netherlands it sits at the upper end of the SMB and mid-market segment, alongside Exact Online and AFAS, and it has meaningful presence in the UK through Wolters Kluwer's CCH ecosystem. If your product serves Dutch accounting firms, mid-sized businesses with multi-entity setups, or any customer that lives inside the WK financial suite, you will end up integrating with Twinfield.

This guide walks through the integration end to end: how OAuth works with the Wolters Kluwer identity platform, why you need to resolve a cluster URL before you can call anything useful, what SOAP services you will actually use, where rate limits hit a non-certified app first, and what the certification process costs in time and effort.

> Auth note: Twinfield uses OpenID Connect on top of OAuth 2.0 for authentication, but the API itself is primarily SOAP-based with XML payloads. You combine an OAuth access token with a SOAP header that includes a `CompanyCode`. Standard REST patterns do not apply.

## Prerequisites

Before you start:

- A Twinfield account with developer portal access. You can register at [developers.twinfield.com](https://developers.twinfield.com) and create an OAuth client.
- A backend service that can hold a client secret. The authorization code flow is the only sensible option for a production server-to-server integration.
- A working knowledge of SOAP and XML parsing. The API does not return JSON.
- A clear answer to whether you are building for a single organisation (one accountancy firm) or for many. The OAuth consent flow runs per organisation user.

## Step 1: Register an OAuth client in the developer portal

Log into the Twinfield developer portal and create a new application. You will get:

- A Client ID
- A client secret (only shown once; copy it now)
- A redirect URI you control on your side

Register the redirect URI exactly as your app will send it, including the trailing slash or absence of one. The token endpoint will reject a request where the redirect URI does not match byte-for-byte. This trips up almost every first integration.

Twinfield supports two OAuth flows: implicit and authorization code. Use the authorization code flow with the `offline_access` scope. Implicit flow exists for native and JavaScript-only clients, and the lack of a refresh token in that flow is a hard ceiling. Access tokens last 12 hours in implicit flow and 1 hour in code flow, and without `offline_access` you cannot extend them without sending the user back through the consent screen.

The full set of scopes you almost always want for a server-side accounting integration:

```
openid twf.user twf.organisation twf.organisationUser offline_access
```

The `twf.organisationUser` scope is mandatory for login. The `offline_access` scope is required for refresh tokens. Without it, you are stuck redoing the consent flow every hour.

## Step 2: Walk a user through the authorization flow

Redirect the user to the Twinfield authorize endpoint:

```
https://login.twinfield.com/auth/authentication/connect/authorize
  ?client_id=YOUR_CLIENT_ID
  &response_type=code
  &scope=openid+twf.user+twf.organisation+twf.organisationUser+offline_access
  &redirect_uri=YOUR_REDIRECT_URI
  &state=RANDOM_STATE
  &nonce=RANDOM_NONCE
```

After the user logs in and consents, Twinfield redirects to your callback with a `code` and the original `state`. Verify the state, then exchange the code at the token endpoint:

```http
POST https://login.twinfield.com/auth/authentication/connect/token
Authorization: Basic BASE64(CLIENT_ID:CLIENT_SECRET)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=THE_CODE_YOU_RECEIVED
&redirect_uri=YOUR_REDIRECT_URI
```

The response contains an access token, an ID token, an `expires_in` value (3600 seconds for the auth code flow), and a refresh token. Store all of these against the user record.

A note on refresh token lifetime: Twinfield documents refresh tokens as valid for [788,940,000 seconds, or roughly 25 years](https://developers.twinfield.com/documentation/api/authentication/openid-connect-auth). In practice, plan for them to fail earlier than that. If a user changes password, has their account disabled, gets deleted from their organisation, or the organisation itself is deactivated, the refresh token is invalidated immediately. Your only signal is an `invalid_request` error on the next refresh attempt.

## Step 3: Resolve the cluster URL

This is the step most teams miss in their first day.

Twinfield runs multiple data clusters. Your access token is issued by the central login service, but the actual web service endpoints live on whichever cluster your customer's organisation sits on. You do not know which cluster that is from the token alone.

Send the access token to the validation endpoint:

```http
GET https://login.twinfield.com/auth/authentication/connect/accesstokenvalidation?token=ACCESS_TOKEN
```

The response includes a `twf.clusterUrl` claim. That URL is the base for every subsequent SOAP call. If your customer is on `https://accounting.twinfield.com`, your calls go there. If they are on a different cluster, calls to the wrong one return what looks like an authentication error but is actually a routing problem. Cache the cluster URL alongside the customer's tokens.

## Step 4: Make your first authenticated SOAP request

Twinfield's API is organised around two patterns: Commands and Queries. Commands mutate data, Queries read it. Both wrap a payload in a SOAP envelope with an authentication header.

A simple ProcessXml query that reads the list of offices in an administration looks like:

```xml
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <Header xmlns="http://www.twinfield.com/">
      <AccessToken>YOUR_ACCESS_TOKEN</AccessToken>
      <CompanyCode>001</CompanyCode>
    </Header>
  </soap:Header>
  <soap:Body>
    <ProcessXmlString xmlns="http://www.twinfield.com/">
      <xmlRequest>
        <list>
          <type>offices</type>
        </list>
      </xmlRequest>
    </ProcessXmlString>
  </soap:Body>
</soap:Envelope>
```

POST that to `{clusterUrl}/webservices/processxml.asmx` with `Content-Type: text/xml; charset=utf-8` and a `SOAPAction` header set to `http://www.twinfield.com/ProcessXmlString`.

`CompanyCode` scopes every call to a single administration. If your customer manages 200 client books, you iterate by changing the company code in the header. You can pass `CompanyId` (a GUID) instead of `CompanyCode` for the same effect.

Twinfield maintains [official C# integration samples on GitHub](https://github.com/Twinfield/TwinfieldIntegrationSamples) if you want a working reference for the SOAP scaffolding.

## Key endpoints and data models

The Twinfield API exposes the core accounting object graph through a mix of typed SOAP services and a generic ProcessXml endpoint that handles XML documents directly.

Master data covers offices (administrations), users, periods, financial settings, VAT codes, currencies, and payment conditions. Dimensions cover customers, suppliers, general ledger accounts, projects, cost centers, and asset codes. Transaction data covers sales invoices, purchase invoices, bank statements, journal entries, cash entries, and memorial entries. Request data covers browse queries for financial reports and trial balance, hierarchy queries for the chart of accounts, and individual transaction reads by number.

The data model leans heavily on dimensions. In Twinfield, customers and suppliers are not first-class objects; they are dimensions of types `DEB` and `CRD` respectively. General ledger accounts are dimensions of type `BAS` or `PNL`. Once you understand that customers, suppliers, projects, cost centers, and accounts share a dimension data structure, the rest of the API gets easier to navigate. The [dimensions documentation](https://developers.twinfield.com/documentation/getting-started/dimensions) is worth reading before you write any code.

## Rate limits and concurrency

Twinfield enforces credit-based rate limiting as of December 2024. The credit system charges differently for reads and writes. Query requests (HTTP GET, OPTIONS, and SOAP actions starting with `Get`, `Query`, `Search`, or `Load`, plus ProcessXml requests with `list`, `read`, `columns`, `accountcode`, or `accountcodes` root elements) cost 1 credit. Everything else costs 3 credits.

The credit budget per minute:

- 1000 credits per IP address
- 1000 credits per Client ID
- 1000 credits per Organisation ID
- 500 credits per Client ID and Organisation ID combination

One wrinkle: those numbers apply to certified integrations. New and uncertified clients get 5% of those limits. That means a non-certified Client ID is capped at 50 credits per minute, and 25 credits per minute against a single organisation. You can hit that ceiling in a few seconds of synchronous backfill.

Twinfield also enforces concurrency: 20 simultaneous requests per Client ID, 10 per Client ID and Organisation combination. A 429 response with the `Retry-After` header is the signal to back off. The full rate limit rules are documented in the [fair use policy](https://developers.twinfield.com/documentation/getting-started/fair-use-policy).

Two practical implications:

- Build your client around exponential backoff and respect the `X-RateLimit-Remaining` header from day one. Adding it after you ship is harder than adding it before.
- Batch your writes. The XML format lets you submit up to 25 children per parent element and up to 500 lines per transaction (1000 is the hard ceiling). One batched call costs 3 credits; 25 individual calls cost 75.

## The certification process

Twinfield gates production access behind a partner program. Until you are certified, you live with the 5% rate limit, and you cannot publish your integration to the Twinfield marketplace, which is where most Twinfield-using accountants discover and install third-party apps.

The [certification process](https://wktaaeu.my.site.com/nlcommunity/articles/en_US/Knowledge/Wat-komt-er-aan-bod-tijdens-de-certificering) consists of a technical review against the [API best practices](https://wktaaeu.my.site.com/nlcommunity/s/article/API-Best-Practices-Introduction?language=en_US) document, a security review, and a recurring audit cadence. Wolters Kluwer charges a partner fee per active API link, and uncertified integrations are eventually phased out. Pricing is published in the partner price list and is worth confirming directly with WK before committing, since the numbers third-party blogs cite are not always current.

Plan for several weeks between submitting an integration for certification and getting marketplace approval. If your product launch depends on it, start the conversation with Wolters Kluwer's partner team before you finish the build, not after.

## Common gotchas

A few things that will cost you a day each if you do not know them upfront.

*Cluster URL caching.* If you skip the cluster resolution step or assume `accounting.twinfield.com` for every customer, you will hit silent authentication failures the first time a customer is on a different cluster. Cache the resolved URL against the customer's organisation ID.

*CompanyCode versus CompanyId.* Both work in the SOAP header, but they behave slightly differently across services. `CompanyCode` is the human-readable code (e.g. `001`); `CompanyId` is the GUID. Some downstream tooling and reporting flows expect one or the other. Pick a convention and stick with it.

*Refresh token revocation is silent.* When a user is disabled or password-rotated, your refresh token stops working with no upfront notice. Your only signal is an `invalid_request` error on the next refresh. Build for the case where you have to send the user back through consent without warning.

*XML size limits are unevenly documented.* The fair use policy says 25 children per parent and 500 lines per transaction recommended, 1000 hard. Some entities have their own internal limits that are not in the public docs. If a large payload fails with a generic error, split it and retry.

*The sandbox is a real Twinfield account.* Twinfield does not offer a separate sandbox API. Test environments are real Twinfield administrations that you request from your partner contact. Pollution between test data and live data is on you to manage.

*VAT handling does not match generic accounting models.* Twinfield's VAT logic is opinionated about Dutch and EU compliance rules. Submitting an invoice with an inconsistent VAT code and base amount returns errors that read as schema problems but are actually compliance validation failures. Read the [VAT calculation docs](https://developers.twinfield.com/documentation/getting-started/vat-calculation) before posting any invoices.

## Where this leaves you

A direct Twinfield integration is a meaningful build. You are looking at OAuth with cluster resolution, SOAP plumbing, XML payload construction, a credit-based rate limiter that throttles you to 5% until you certify, and a partner program with ongoing fees and a recertification cadence. None of it is unreasonable for a platform with Twinfield's market position, but it is a multi-week commitment for one connector.

If Twinfield is one of several accounting platforms on your roadmap, the math shifts. Your Dutch SMB customers also use [MoneyBird](https://www.apideck.com/blog/moneybird-api-integration) and [SnelStart](https://www.apideck.com/blog/how-to-integrate-with-the-snelstart-api). Your French ones use Pennylane. Your German ones use DATEV. Each has its own auth model, its own pagination behaviour, its own gotchas. Building and maintaining a portfolio of direct integrations is a real ongoing engineering investment.

Apideck does not yet have a Twinfield connector. Our [unified Accounting API](https://www.apideck.com/accounting-api) covers most of the rest of the Dutch and broader European SMB market, and custom connectors are part of the enterprise plan when a specific platform is missing. Twinfield is on the roadmap. If you would benefit from it being there sooner, you can [request Twinfield support](https://www.apideck.com/accounting-software/twinfield) or start building today against the 40+ accounting connectors already in the unified API with a [30-day free trial](https://www.apideck.com/signup).

Guides & Tutorials

Developer guide to integrating with the Twinfield API. Covers OAuth, cluster routing, SOAP requests, rate limits, and the partner certification process.

saurabh

Saurabh Rai

Developer Relations Engineer

How to Integrate with the Twinfield API

Rompslomp is a Dutch online bookkeeping product owned by Visma, built for freelancers and zzp'ers who want invoicing and VAT filing without learning double-entry bookkeeping. Pricing starts at €5 per month. The product ships with a mobile app for scanning receipts (the "shoe box"), a desktop UI for invoicing and quotations, and integrations with Shopify, Mijnwebwinkel, Simple-Simon, and Mollie. If your software touches money for the Dutch SMB market, Rompslomp will eventually come up alongside [MoneyBird](https://www.apideck.com/blog/moneybird-api-integration) and [SnelStart](https://www.apideck.com/blog/how-to-integrate-with-the-snelstart-api) as a platform your customers ask you to sync with.

Below is a working developer's view of the Rompslomp API, including the parts that don't behave the way you'd expect coming from QuickBooks or Xero.

## The API in brief

Rompslomp ships a REST API hosted at `https://api.rompslomp.nl`. Resource URLs follow a consistent pattern:

```
https://api.rompslomp.nl/api/v1/{company_id}/{resource_type}[/{id}]
```

Most operations happen in the context of a specific company administration, which is why `company_id` shows up in nearly every path. Requests and responses both use JSON. The official documentation lives at [app.rompslomp.nl/developer](https://app.rompslomp.nl/developer) and is in Dutch, which is worth flagging if your team isn't.

> Rompslomp supports two authentication paths: personal API tokens for internal scripts and single-account integrations, and OAuth 2.0 for commercial applications that connect on behalf of many Rompslomp users. The path you pick has real implications for how you handle credentials and refresh logic.

## Prerequisites

Before you start:

- A Rompslomp account. The API is available from the Puur Factuur tier upward; the free tier does not include API access.
- The API add-on activated on the company administration you want to access. The owner of the administration enables this from Settings.
- For commercial integrations: a registered OAuth application. You request one through the [Rompslomp API integration form](https://rompslomp.nl/formulier/api).
- A working understanding of OAuth 2.0 authorization code flow if you're going the commercial route.

## Authentication path 1: Personal API tokens

The fast path. Personal API tokens are what you generate when you only need to access your own administrations, or a single customer's administration that you have direct access to.

The flow:

1. Log in to rompslomp.nl.
2. Open the account menu in the top right and choose "Mijn account."
3. Go to "Mijn API tokens" and find the "Nieuw API token" section.
4. Pick the scopes you want the token to cover. Don't grant scopes the integration won't use.
5. Click "Aanmaken." The new token displays once.

Treat the token like any other secret: copy on creation and store in your secrets manager.

To use the token, send it in the Authorization header as a Bearer credential:

```bash
curl --request GET 'https://api.rompslomp.nl/api/v1/companies/54321/sales_invoices' \
  --header 'Authorization: Bearer NxtsAs1T6P9TcApiTl4DGcLulrLQDqzIWhdaOBI07gU'
```

These tokens don't expire. They keep working until you delete them, which makes them convenient for cron jobs and back-office integrations, and dangerous if you ever lose track of where they're stored.

The hard limit on personal tokens: if you're building a product where your customers connect their own Rompslomp accounts, personal tokens are not the right model. You need OAuth.

## Authentication path 2: OAuth 2.0

Standard authorization code flow, with one documentation quirk worth flagging up front.

After Rompslomp issues you a client ID and client secret, redirect the user to the authorize endpoint with the scopes you need:

```
https://api.rompslomp.nl/oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&scope={scope}
```

The `redirect_uri` must match exactly what's registered for your application. A trailing slash mismatch will cause the authorization to fail without a clear error message.

On approval, the user comes back to your callback with a `code` query parameter. Exchange it for an access token:

```bash
curl --request POST 'https://api.rompslomp.nl/oauth/token' \
  --form 'client_id={client_id}' \
  --form 'client_secret={client_secret}' \
  --form 'grant_type=authorization_code' \
  --form 'code={code}' \
  --form 'redirect_uri={redirect_uri}'
```

The response contains the access token, a refresh token, and the expiration window in seconds:

```json
{
  "access_token": "LvpR0xfTE437L_sMufuZxYs1iASUn3b9OLLbPihUMGg",
  "token_type": "Bearer",
  "expires_in": 7199,
  "refresh_token": "WzZmMMCAsKmIH8QMq8dCTpxMyELIUn3-pfz1zHHPsIM",
  "scope": "public",
  "created_at": 989532000
}
```

Access tokens expire after roughly two hours. When the API returns a 401 with `error="invalid_token"`, refresh:

```bash
curl --request POST 'https://api.rompslomp.nl/oauth/token' \
  --form 'client_id={client_id}' \
  --form 'client_secret={client_secret}' \
  --form 'grant_type=refresh_token' \
  --form 'refresh_token={refresh_token}'
```

One inconsistency in the official docs: the refresh example points to `rompslomp.nl/oauth/token`, while the initial token exchange uses `api.rompslomp.nl/oauth/token`. The `api` subdomain works for both. Use it consistently to avoid edge-case redirect issues.

Each refresh returns a new refresh token alongside the new access token. Persist the new refresh token. If you keep using the old one after a refresh, the next refresh will fail.

## Scopes

Rompslomp uses scope-based authorization. The available scopes:

| Scope | What it covers |
| --- | --- |
| `public` | Read general resources: companies, accounts, VAT rates. Default if you don't specify. |
| `manage:companies` | Manage company administrations. |
| `manage:contacts` | Manage contacts. |
| `manage:payments` | Manage payments. |
| `manage:products` | Manage products. |
| `manage:sales_invoices` | Manage outgoing invoices, plus their contacts and payments. |
| `manage:journal_entries` | Manage journal entries. |
| `manage:quotations` | Manage quotations. |
| `manage:hours` | Manage time entries. |
| `manage:rides` | Manage trip and mileage records. |
| `manage:expenses` | Manage expenses. |
| `read:accounts` | Read balance sheet and P&L accounts. |
| `read:me` | Read the authenticated user's profile. |

Pass scopes as a space-separated list in the authorize URL. Request the minimum your integration needs. Users see the permissions list during authorization, and an inflated set of scopes is one of the cheapest ways to lose them at consent.

One subtle behavior: an access token's `scope` value tells you what the user authorized in principle. Whether a given scope is usable for a specific company depends on the user's role in that administration. To check what's actually available, call the companies endpoint:

```
GET /api/v1/companies
```

Each company object in the response includes an `access_control.allowed_scopes` array. If the scope you need isn't in that list for the target company, the request will fail even though the token nominally has it.

## Making your first request

Once you have a token, fetch the list of companies the user can access:

```bash
curl --request GET 'https://api.rompslomp.nl/api/v1/companies' \
  --header 'Authorization: Bearer {access_token}'
```

A successful response returns the companies array with IDs, names, and allowed scopes. From there, every other request is scoped to a specific company:

```bash
curl --request GET 'https://api.rompslomp.nl/api/v1/companies/{company_id}/sales_invoices' \
  --header 'Authorization: Bearer {access_token}'
```

## Core resources

The resources you'll touch most often when building an integration are grouped below by what they cover.

For sales and customer-facing data: `contacts` (customers and suppliers), `sales_invoices` (outgoing invoices, with draft and sent states), `quotations` (outgoing quotes that can be converted to invoices), and `layouts` (invoice and quotation templates).

For bookkeeping: `expenses` (incoming costs and receipts), `payments` (records that link to invoices or expenses), `journal_entries` (direct ledger entries), `bank_transaction_journals` (bank transactions), and `accounts` (balance and P&L accounts, read-only via `read:accounts`).

For project and operational data: `products` (catalog), `hours` (time entries for project-based billing), and `rides` (mileage tracking, common for Dutch freelancers claiming kilometer allowances).

Write-only attributes prefixed with an underscore are "triggers": they cause side effects without being stored. The most common is `_publish` on a sales invoice, which moves a draft into a sent state.

## Pagination

Every list endpoint paginates. You control it with two query parameters:

- `page`: page number, starting at 1.
- `per_page`: items per page, between 1 and 100. Default is 40.

Responses include three headers that tell you where you are in the dataset: `X-Page` shows the current page, `X-Per-Page` reflects the page size, and `X-Total` returns the total number of items across all pages.

This is friendlier than MoneyBird, which doesn't return totals at all and forces you to walk the dataset until you hit an empty page. With Rompslomp you can compute the total page count up front and parallelize fetches if you need to.

## Rate limiting

Rompslomp enforces rate limits but doesn't publish exact numbers. When you hit the limit, the API returns 429 with a `Retry-After` header that tells you how many seconds to wait before retrying.

Build exponential backoff with retries, respect `Retry-After`, and cache where data doesn't change often. The docs explicitly ask integrators to be respectful of shared infrastructure. A sync job hammering the API every minute will be throttled.

## Common gotchas

A few things that catch developers off guard when they first build against this API.

The API add-on isn't on by default. If you're testing against your own account and getting 401s on everything, check that the API add-on is activated for the specific company administration. It's a per-administration toggle, not an account-wide one.

Scope authorization is not the same as scope usability. A token can carry `manage:sales_invoices` and still fail on a specific company because the user's role doesn't include invoice management for that administration. Always check `access_control.allowed_scopes` per company before assuming a scope works.

The documentation is in Dutch. If your team doesn't read Dutch, plan on either a translation layer in your dev workflow or extra time when you're investigating endpoint behavior. The Dutch terms `bedrijf` (company), `factuur` (invoice), and `offerte` (quotation) come up everywhere.

Personal tokens and OAuth tokens look identical at the call site. Both are passed as `Bearer {token}` in the Authorization header. If you're mixing both in the same codebase, label your secrets clearly so a personal token isn't accidentally fed to a refresh flow.

Refresh tokens rotate. Each successful refresh returns a new refresh token. If you store credentials in a database, update both tokens atomically. Storing only the new access token while keeping the old refresh token is a classic way to lock yourself out of an integration overnight.

Triggers use underscores. Fields starting with an underscore (`_publish` and similar) trigger an action rather than store a value. Easy to miss if you're auto-mapping fields between your data model and Rompslomp's.

## Where this fits if you're building broader accounting coverage

Rompslomp is one option in a Dutch SMB accounting market that also includes [MoneyBird](https://www.apideck.com/blog/moneybird-api-integration), [SnelStart](https://www.apideck.com/blog/how-to-integrate-with-the-snelstart-api), e-Boekhouden, Yuki, Exact Online, and Pennylane. If your product asks customers "what's your accounting software?", you're looking at building and maintaining several of these in parallel. Each comes with its own auth model and its own pagination behavior.

Apideck does not have a Rompslomp connector at the time of writing. The path to a Rompslomp integration today is the direct one described above. Our [unified Accounting API](https://www.apideck.com/accounting-api) covers most of the rest of the Dutch and European SMB market, and custom connectors are part of the enterprise plan when a specific platform is missing from the lineup. If you're already integrating with MoneyBird or SnelStart through Apideck and want Rompslomp added, that's the route.

For surrounding work, see our guides on [the SnelStart API](https://www.apideck.com/blog/how-to-integrate-with-the-snelstart-api) and [the MoneyBird API](https://www.apideck.com/blog/moneybird-api-integration). Between them, they cover the largest share of the Dutch SMB accounting market by user count.

Developer guide to integrating with the Rompslomp API. Covers personal tokens, OAuth 2.0, scopes, pagination, rate limits, and common gotchas.

Gertjan De Wilde

Co-founder

How to Integrate with the Rompslomp API

Visma eAccounting is one of the more widely deployed cloud accounting platforms in Northern Europe, particularly in Norway and the Netherlands. If your product targets SMEs in those markets, sooner or later a customer will ask you to sync invoices, pull expense data, or push payments into their eAccounting company. The API handles all of that, but the path to a working integration has a few non-obvious steps that are worth mapping out clearly.

One naming note before anything else: Visma has rebranded eAccounting to "Spiris" in some markets, and the official developer portal now refers to it as the Spiris API. The underlying API, authentication server, and endpoints are the same product. If you see the two names used interchangeably in documentation and forum posts, that's why. If your customers are specifically on Spiris in Sweden, see our [Spiris / Visma eAccounting API integration guide](https://www.apideck.com/blog/spiris-visma-eaccounting-api-integration) for the Sweden-specific differences around BAS accounts, Moms VAT, and ROT/RUT invoice handling.

## Getting Registered

Access to the Visma eAccounting API requires joining the [Spiris Partner Programme](https://selfservice.developer.vismaonline.com/). Registration is self-service for sandbox access: fill in the form at the Visma Developer Self-Service portal, and you'll receive a `client_id`, a `client_secret`, and credentials for a sandbox eAccounting company by email.

Use a business email. That address becomes the contact point for your developer account and the address Visma API support will reach out to. When you register, you also set your `redirect_uri`. This value is fixed unless you contact Visma support to update it, so plan ahead rather than hardcoding `localhost` and hoping to change it later.

Production access requires a separate request to API support after sandbox testing is complete. Visma will never ask you for your `client_secret`, not during registration and not in any support context. If that ever comes up, treat it as a red flag.

## Authentication: OAuth 2.0 with a Resource-Level Scope Model

The API uses the OAuth 2.0 authorization code flow, with the identity server hosted at `https://identity.vismaonline.com`. The two required scopes for any eAccounting integration are `ea:api` (grants access to the Bookkeeping & Invoicing/eAccounting API) and `offline_access` (required to receive a refresh token). Beyond those, each resource area has its own scope.

| Scope | Access |
|---|---|
| `ea:sales` | Full access to sales resources (invoices, customers) |
| `ea:sales_readonly` | Read-only access to sales resources |
| `ea:purchase` | Full access to purchase resources (bills, suppliers) |
| `ea:purchase_readonly` | Read-only access to purchase resources |
| `ea:accounting` | Full access to accounting resources (journal entries, accounts) |
| `ea:accounting_readonly` | Read-only access to accounting resources |

The scope model creates friction that isn't obvious until you've already shipped. You define the maximum set of scopes your app can request when registering in the developer portal. During the OAuth flow, you must explicitly include every scope you need in the authorization request. Your customer sees and approves those scopes as part of connecting their account.

If you omit a scope in the authorization request, even if your app registration permits it, the API returns an authorization error for that resource area. Correcting it requires your customer to go through the OAuth flow again. Get your scope list right the first time, and default to the `_readonly` variants unless your integration genuinely needs write access.

A sample authorization request looks like this:

```
GET https://identity.vismaonline.com/connect/authorize
  ?client_id=<client_id>
  &redirect_uri=<redirect_uri>
  &scope=ea:api+offline_access+ea:sales+ea:purchase+ea:accounting
  &state=<state_string>
  &response_type=code
  &prompt=select_account
  &acr_values=service:44643EB1-3F76-4C1C-A672-402AE8085934
```

After the user authorizes, the identity server redirects to your `redirect_uri` with an authorization code. Exchange it for an access token and refresh token at the token endpoint (`https://identity.vismaonline.com/connect/token`):

```js
async function exchangeCodeForTokens(code) {
  const response = await fetch('https://identity.vismaonline.com/connect/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code,
      redirect_uri: process.env.VISMA_REDIRECT_URI,
      client_id: process.env.VISMA_CLIENT_ID,
      client_secret: process.env.VISMA_CLIENT_SECRET,
    }),
  });

  if (!response.ok) {
    throw new Error(`Token exchange failed: ${response.status}`);
  }

  const { access_token, refresh_token, expires_in } = await response.json();
  // Store both tokens per tenant. expires_in is in seconds (typically 3600).
  return { access_token, refresh_token, expires_at: Date.now() + expires_in * 1000 };
}
```

## Token Management

Access tokens expire after 60 minutes. Your integration must handle token refresh for every tenant, not just on first authentication. For production systems that sync data on a schedule, you'll need to refresh before expiry and store updated tokens per tenant.

The refresh token is valid for two years, with one critical exception: if a user changes their Visma password, the refresh token is immediately invalidated. There is no webhook or notification for this. The first sign your integration will see is a 401 response on the next API call. Build explicit handling for this case: detect the 401, mark the tenant as requiring re-authorization, and trigger a new OAuth flow with a prompt to the user. Without this, the integration silently stops syncing data for any customer who resets their password.

```js
async function refreshAccessToken(tenant) {
  const response = await fetch('https://identity.vismaonline.com/connect/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      refresh_token: tenant.refresh_token,
      client_id: process.env.VISMA_CLIENT_ID,
      client_secret: process.env.VISMA_CLIENT_SECRET,
    }),
  });

  if (response.status === 400) {
    // Refresh token invalidated — most likely a password change.
    // Mark tenant as needing re-authorization and surface this to the user.
    await markTenantAsUnauthorized(tenant.id);
    throw new Error('REAUTH_REQUIRED');
  }

  const { access_token, refresh_token, expires_in } = await response.json();
  await saveTenantTokens(tenant.id, { access_token, refresh_token, expires_in });
  return access_token;
}

async function callApi(tenant, path) {
  // Proactively refresh if within 5 minutes of expiry.
  if (tenant.expires_at - Date.now() < 5 * 60 * 1000) {
    tenant.access_token = await refreshAccessToken(tenant);
  }

  const response = await fetch(`https://eaccountingapi.vismaonline.com/v2/${path}`, {
    headers: { Authorization: `Bearer ${tenant.access_token}` },
  });

  if (response.status === 401) {
    // Unexpected 401 after a valid token — catch any edge cases.
    await markTenantAsUnauthorized(tenant.id);
    throw new Error('REAUTH_REQUIRED');
  }

  return response.json();
}
```

## Working with Core Endpoints

The full API reference is available at [eaccountingapi.vismaonline.com/scalar/v2](https://eaccountingapi.vismaonline.com/scalar/v2). Required fields are marked in bold in the docs, which makes it easier to identify the minimum viable payload for each resource.

A few patterns apply across the entire API:

**Pagination.** Responses are paginated with a default page size of 50 results. Without explicit pagination handling, a sync that returns 50 records may be complete, or it may be missing hundreds more. Always check the pagination metadata in the response and implement full page traversal before shipping.

```js
async function getAllInvoices(tenant) {
  const invoices = [];
  let pageIndex = 1; // eAccounting uses 1-based page indexing

  while (true) {
    const data = await callApi(
      tenant,
      `customerinvoices?pagesize=50&pageindex=${pageIndex}`
    );

    invoices.push(...data.Data);

    // TotalNumberOfPages is returned in the response metadata
    if (pageIndex >= data.Meta.TotalNumberOfPages) break;
    pageIndex++;
  }

  return invoices;
}
```

**Fiscal years.** Account-related operations require a `FiscalYearId`. This is tenant-specific and must be fetched per customer before creating or querying accounts. Hardcoding a year or skipping this lookup is a common source of 400 errors in production.

```js
async function getActiveFiscalYear(tenant) {
  const data = await callApi(tenant, 'fiscalyears');
  // Find the fiscal year that contains today's date
  const today = new Date().toISOString().split('T')[0];
  return data.Data.find(
    (fy) => fy.StartDate <= today && fy.EndDate >= today
  );
}

async function createCustomerInvoice(tenant, invoicePayload) {
  const fiscalYear = await getActiveFiscalYear(tenant);

  const response = await fetch(
    'https://eaccountingapi.vismaonline.com/v2/customerinvoices',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${tenant.access_token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        ...invoicePayload,
        // FiscalYearId is required — the API returns 400 without it
        FiscalYearId: fiscalYear.Id,
      }),
    }
  );

  if (!response.ok) {
    // The response body includes an ErrorId — log it for support escalations
    const error = await response.json();
    throw new Error(`Invoice creation failed [ErrorId: ${error.ErrorId}]: ${error.Message}`);
  }

  return response.json();
}
```

**VAT and account codes.** VAT rates and chart of accounts structures vary by country and, for some fields, by individual tenant configuration. Norway and the Netherlands use different VAT rate structures and account number conventions. Your integration needs to handle this per-tenant rather than assuming a fixed mapping.

For customer invoices specifically, Visma's [Invoice Payments FAQ](https://developer.vismaonline.com/docs/invoice-payments) and [Autoinvoice guide](https://developer.vismaonline.com/docs/customer-invoices-faq) cover the workflows for payment reconciliation and automated sending in detail. These are worth reading before building the invoicing leg of an integration, since some behaviors (like triggering email delivery) require specific payload fields that aren't obvious from the endpoint reference alone.

## Rate Limits and Error Handling

The API enforces rate limits, documented in the developer portal. Every non-successful response includes a unique Error ID. Include that Error ID and your `client_id` whenever you contact Visma API support. Responses without the Error ID significantly slow down support resolutions.

Support is market-specific:
- Sweden / Spiris: [eaccounting.api@visma.com](mailto:eaccounting.api@visma.com)
- Norway: [eaccounting.api.no@visma.com](mailto:eaccounting.api.no@visma.com)
- Netherlands: [eaccounting.api.nl@visma.com](mailto:eaccounting.api.nl@visma.com)

## The Maintenance Burden

A working Visma eAccounting integration takes real engineering effort to build. The OAuth scope model requires careful upfront planning, the token refresh logic needs to handle password-change invalidation explicitly, pagination must be handled on every list endpoint, and country-specific VAT and account structures have to be resolved per tenant. None of these are blockers, but together they represent a meaningful investment to build correctly and to maintain as the API evolves.

If you're building accounting integrations across multiple platforms alongside eAccounting, a unified API layer can absorb the per-platform differences in authentication, data models, and error behavior. Apideck's [Accounting API](https://www.apideck.com/accounting-api) normalizes data across 35+ accounting platforms through a single schema, and the [Vault component](https://www.apideck.com/products/vault) handles OAuth flows and token management without requiring custom code per connector. For teams that need to ship integrations quickly across multiple markets and platforms, that tradeoff is often worth examining before committing to a stack of direct integrations.

For teams building specifically against Visma eAccounting, the [official developer portal](https://developer.vismaonline.com/) and [API reference](https://eaccountingapi.vismaonline.com/scalar/v2) are the ground truth. The sandbox registration is free and takes a few minutes. Get credentials, poke around in the sandbox company, and build the OAuth flow before writing any data-sync logic. It's the fastest way to catch scope issues before they become customer re-authorization requests.

A developer guide to Visma eAccounting API integration. Covers OAuth 2.0 scopes, token management, pagination, fiscal year handling, and country-specific VAT with JavaScript code examples.

How to Integrate with the Visma eAccounting API

Building a QuickBooks bank feed integration puts you into a different system than the standard QuickBooks Online API. Bank feeds in QuickBooks run through Intuit's Financial Data Partner (FDP) program and the [Open Financial Exchange (OFX)](https://ofx.net) protocol, completely separate from the accounting API you'd use for invoice sync or customer records. The FDP partnership covers the full Intuit product suite: one approved Branding ID makes your institution connectable in QuickBooks, [Quicken](https://www.quicken.com) (personal finance software), and [Credit Karma](https://www.creditkarma.com) (Intuit's financial health platform with 130+ million members).

This guide covers the native path: the three connection types, what the partner program actually requires, where FDX fits today, and what to expect for QuickBooks Desktop.

## The Three Connection Types

Intuit supports three distinct methods for bank connectivity across its products. They're not interchangeable, and each targets a different product surface with a different implementation approach.

**Web Connect** is the simplest option. The user downloads a `.qbo` file from their online banking portal and imports it manually into QuickBooks Desktop or QuickBooks Online. There's no direct server-to-server communication, and no credentials are stored inside QuickBooks. Intuit classifies it as a connectivity type, but the user is doing the work. It's the fallback for banks without an active Intuit BID (Branding ID) and still widely used by institutions that haven't gone through the full partner process.

**Direct Connect** is the real-time native option for QuickBooks Desktop and [Quicken](https://www.quicken.com). When a user initiates a download from inside QuickBooks, QuickBooks calls your OFX server, authenticates with the user's credentials, and retrieves transaction data. It's the only two-way connectivity type, so it also supports bill pay and in-product transfers if your OFX provider makes those available. This is the integration your users mean when they say they want their bank to "just connect."

**Aggregation** (called Express Web Connect in Quicken) is Intuit-managed. Instead of calling your OFX server directly, Intuit's infrastructure retrieves transactions from your online banking site. This covers QuickBooks Online, [Credit Karma](https://www.creditkarma.com), and Quicken. You don't maintain an OFX server for this path. Intuit creates and manages the connection once you have an approved Web Connect or Direct Connect BID. Whether aggregation is available for your institution depends on whether your online banking site is compatible with Intuit's extraction process.

For financial institutions trying to appear as a recognized provider inside QuickBooks, all three paths require becoming a contracted Intuit FDP partner. You receive a Branding ID, which is what makes your institution discoverable when a user searches for their bank in the "Link Account" flow.

![QuickBooks Online bank feed - Pending, Posted, and Excluded tabs (2025)](https://images.ctfassets.net/d6o5ai4eeewt/7x6eNC9oBOEoZSVuLu0B0H/1dcf7ff1659a532246fc918dd087f3ec/qbo-bank-feed-tabs-2025.png)

## Getting Listed as a Financial Institution

Getting your institution into QuickBooks isn't a self-serve process. There's no "create an app, get credentials, go live" flow like there is for the standard QBO accounting API. Intuit manages the FDP program separately, and the timeline is longer.

The process starts at [intuit.com/partners/fdp](https://www.intuit.com/partners/fdp). From there you choose either the direct OFX Connectivity path (for institutions running their own OFX servers) or the Third Party Provider path (if you're working through a service provider like Fiserv, Jack Henry, or a specialist middleware provider). Intuit's quote tool walks through pricing; there's a per-institution fee structure depending on which products and connection types you want to support.

Once contracted, you receive your Branding ID and begin implementation. For Direct Connect, that means building or configuring an OFX-compliant server that handles statement download requests and user authentication. Intuit certifies the connection before you go live in their institution list. The full timeline from initial inquiry to production listing can run 6 to 12 months or longer, and for smaller fintechs without established institutional credibility, Intuit often routes applicants through an approved service provider rather than engaging directly.

One nuance specific to QuickBooks Online: the bank feeds experience in QBO runs through aggregation, not Direct Connect. Intuit pulls data on their own schedule. You can't trigger a real-time push from your side. Transactions appear in the user's QuickBooks Banking tab on Intuit's pull cadence.

![QuickBooks Online bank feed transaction rows (2025)](https://images.ctfassets.net/d6o5ai4eeewt/5rTJLl13TZebfaHRDAS7Tu/26112eac1c0c829a5fb13143ac00286c/qbo-bank-feed-transaction-rows-2025.png)

## Geographic Scope

The FDP partnership program and OFX-based connectivity described in this guide applies to the US and Canada. Other markets run on different infrastructure.

In the **UK**, QuickBooks Online bank feeds operate through Open Banking under PSD2. Users connect through their bank's Open Banking authorization flow rather than an OFX server. The Intuit FDP program is not the path for UK institutions.

In **Australia**, Intuit is migrating all QBO bank feeds to Open Banking under the Consumer Data Right (CDR) framework. Legacy bank feed connections are being retired on 31 May 2026. Institutions connecting to QBO in Australia should be building toward CDR-compliant connectivity rather than OFX.

## Where FDX Fits Today

FDX (Financial Data Exchange) is the modern [open banking](https://www.openbankingtracker.com/open-banking-api) standard replacing OFX in North America. Founded in 2018 and recognized by the CFPB as an official standard-setting body in January 2025, FDX defines a RESTful API for consumer-permissioned financial data sharing, using OAuth 2.0 and the FAPI security profile. As of early 2026, more than 130 million consumer accounts are connected via FDX-aligned APIs, with major banks and aggregators including JPMorgan Chase and Plaid participating alongside more than 250 member organizations.

For a global view of open banking API coverage across financial institutions, see the [Open Banking Tracker](https://www.openbankingtracker.com).

Where OFX uses a flat SGML-like structure over HTTPS, FDX is a proper REST API covering a much wider data surface: deposit accounts, loans, investments, insurance, payroll, and tax data. For banks already building FDX-compliant APIs to meet Section 1033 requirements, the natural question is whether that same API can power QuickBooks bank feeds.

For now, no. Intuit's bank feeds infrastructure for QuickBooks still runs on OFX. FDX and OFX serve different roles in the current ecosystem: FDX is the data-sharing standard for third-party access (aggregators, lending platforms, open banking apps), while OFX remains the protocol Intuit's own products use to pull transaction data from financial institutions. Whether and when Intuit moves QuickBooks bank feeds to an FDX-based connection model is not publicly committed to on any specific timeline.

Apideck does not yet support FDX as a source format for bank feeds. This is on the roadmap. As the market converges on FDX-based connectivity, it becomes the obvious path forward. For now, the OFX-based partner program remains the only native route into QuickBooks.

## QuickBooks Desktop Bank Feeds

QuickBooks Desktop remains a material part of the market. When Intuit stopped selling Desktop Pro and Premier to new customers in July 2024, it moved that segment toward Enterprise rather than eliminating it. Roughly 3.7 million businesses run Desktop across the product line, and Enterprise continues to be sold, supported, and used by exactly the customers with the budget and complexity to care about deep accounting integrations.

Bank feeds in QuickBooks Desktop work through Direct Connect (OFX) and Web Connect. The user initiates a download from inside the Desktop application, which calls your OFX server, authenticates, and pulls the statement data. The experience is more synchronous than QBO's aggregation model. It requires your OFX server to be responsive when the user triggers a sync.

Apideck's support for QuickBooks Desktop bank feeds is coming. The [accounting connector](https://www.apideck.com/connectors/quickbooks) already covers QuickBooks Desktop for general accounting operations. Bank feed support for Desktop users who need automated transaction sync is the next step.

## How to Think About the Build Decision

The native Intuit FDP partnership gives you the cleanest in-product experience. Your institution appears in the QuickBooks institution list, users connect through the standard flow, and you control the data pipeline through your OFX infrastructure or a service provider. The cost is partnership overhead and timeline.

Building natively means maintaining an OFX-compliant server, clearing Intuit's certification process, and managing ongoing compliance. For institutions needing to support multiple accounting platforms alongside QuickBooks, repeating this for Xero, Sage, and NetSuite multiplies that investment considerably.

Apideck's [bank feeds connector](https://www.apideck.com/use-cases/bank-feeds) is the alternative: one API integration that routes transaction data into QuickBooks, Xero, Sage, NetSuite, and 20+ other platforms through normalized endpoints, with Apideck managing the partnership and connection infrastructure on your behalf. If your engineering team's time is better spent on product than on OFX server certification cycles, that tradeoff is worth understanding clearly before you start.

For more on how bank feeds sit within a broader accounting integration strategy, see [Bank API Integration: How Banks Connect to Accounting and ERP Systems](https://www.apideck.com/blog/bank-api-integration).

Start a [30-day free trial](https://www.apideck.com/signup) to see how the bank feeds connector fits your architecture.

A technical guide to QuickBooks bank feed integration: the OFX partner program, three connection types, FDX format, and QuickBooks Desktop bank feeds support.

How to Build a QuickBooks Bank Feed Integration Natively

The most complete embedded finance companies landscape for 2026. 250+ providers mapped across 17 categories — BaaS, card issuing, payments, lending, compliance, payroll, investing, FX, insurance, and more. Data sourced from the Open Banking Tracker by Apideck.

Embedded Finance Companies Landscape 2026

Build robust accounting API integration for vertical SaaS products. Learn how to connect with platforms like QuickBooks, Xero, NetSuite, and Sage Intacct, handle authentication, normalize data models, and ensure reliable sync in production.

Developer's Guide to Accounting API Integration for Vertical SaaS

Saudi Arabia made e-invoicing mandatory in 2021 under ZATCA regulations. The UAE followed with its own FTA e-invoicing rollout. If you're building a product that handles money for businesses in the Gulf, you will run into customers on Wafeq.

Wafeq processed over 2 million invoices worth $400 million every month as of its November 2024 Series A, with roughly 90% of that volume coming from Saudi Arabia. That concentration tells you most of the traction is in the market with the strictest compliance requirements. Notable customers include Tabby and Platinumlist, category-defining companies in MENA fintech and ticketing. If your product touches their accounting layer, a Wafeq API integration will come up.

This guide covers authentication with the Wafeq accounting API, the core data model, contact and invoice creation, idempotency, webhooks, and where to route KSA Phase 2 traffic separately.

## Authentication

Wafeq supports two authentication methods: API key and OAuth2.

For internal tools or direct integrations where your company manages its own Wafeq workspace, API key auth is the simpler path. You pass the key as a header on every request:

```
Authorization: Api-Key <YOUR_API_KEY>
```

To get your key, log into the Wafeq dashboard, navigate to API Keys under Developer in the sidebar, click "Create Key", give it a name, and click Create.

For multi-tenant applications where your users connect their own Wafeq accounts, you need OAuth2. Contact Wafeq directly to obtain client credentials. The header shifts to:

```
Authorization: Bearer <access_token>
```

All v1 endpoints live at `https://api.wafeq.com/v1/`. Saudi Arabia Phase 2 e-invoicing (ZATCA Phase 2) uses a completely separate service at `https://zatca.wafeq.com`. The standard invoicing API covers Phase 1 and countries that don't implement e-invoicing; for KSA Phase 2, Wafeq maintains dedicated ZATCA API docs. If you're building for KSA compliance, consult those separately before writing integration code — the data models diverge.

## The Wafeq accounting API data model

A few structural things worth knowing before writing code.

Entity IDs are prefixed strings. A contact ID looks like `cnt_7mWREbbgavfh6JCGsQCSkz`, an account like `acc_FSD8TuroF3ywN...`. The prefix makes it easy to identify the object type from the ID itself when reading logs.

Pagination uses `?page=1&page_size=25` and returns responses shaped like:

```json
{
  "count": 142,
  "next": "https://api.wafeq.com/v1/contacts/?page=2",
  "previous": null,
  "results": [...]
}
```

For idempotency on writes, pass a UUID v4 in the `X-Wafeq-Idempotency-Key` header. Wafeq caches the response for one hour and replays it for duplicate requests, returning `X-Wafeq-Idempotent-Replayed: true` on replays. Use this on invoice creation and payment recording, where duplicates are expensive to unwind.

## Creating a contact

Before you can create an invoice, you need a contact to bill. The contacts endpoint is `POST https://api.wafeq.com/v1/contacts/`.

```javascript
const res = await fetch("https://api.wafeq.com/v1/contacts/", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Api-Key " + process.env.WAFEQ_API_KEY
  },
  body: JSON.stringify({
    name: "Acme Trading LLC",
    email: "billing@acme.com",
    phone: "+971500000000"
  })
});

if (!res.ok) {
  const err = await res.text();
  throw new Error(`Create contact failed: ${res.status} ${err}`);
}

const contact = await res.json();
```

The response includes the contact's `id` (prefixed `cnt_...`), which you pass into invoice creation. You can extend the request body with address data and tax registration numbers per the [Contacts API reference](https://developer.wafeq.com/reference/contacts_create).

## Resolving accounts

Wafeq uses a chart of accounts to categorize where money comes from and goes to. Before creating an invoice, you need two account IDs: a revenue account (where sales post in the P&L) and a payment account (where you received the money, typically a bank account).

```javascript
const res = await fetch("https://api.wafeq.com/v1/accounts/", {
  headers: { "Authorization": "Api-Key " + process.env.WAFEQ_API_KEY }
});

const { results } = await res.json();

const revenueAccount =
  results.find(a => a.code === "4000") ||
  results.find(a => a.name?.toLowerCase() === "sales");
```

Filter by account code or exact name rather than classification — classification strings can vary between workspaces, but chart of account codes like `4000` for Sales are more consistent. For the payment account, use the `is_payment_enabled` filter:

```
GET https://api.wafeq.com/v1/accounts/?is_payment_enabled=true
```

Cache these IDs. They don't change between requests, and re-fetching them on every invoice creation adds unnecessary latency.

## Creating an invoice

With a contact ID, revenue account ID, and payment account ID in hand, you can create an invoice. The bulk send endpoint is `POST https://api.wafeq.com/v1/api-invoices/bulk_send/` and accepts an array of invoice objects.

```javascript
const res = await fetch("https://api.wafeq.com/v1/api-invoices/bulk_send/", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Api-Key " + process.env.WAFEQ_API_KEY,
    "X-Wafeq-Idempotency-Key": crypto.randomUUID()
  },
  body: JSON.stringify([{
    reference: "ORDER-001",
    invoice_number: "INV-2024-001",
    invoice_date: "2024-11-01",
    currency: "AED",
    paid_through_account: "<payment_account_id>",
    language: "en",
    tax_amount_type: "TAX_INCLUSIVE",
    contact: { id: "<contact_id>" },
    channels: [{
      medium: "email",
      data: {
        subject: "Invoice from Acme",
        message: "<p>Please find your invoice attached.</p>",
        recipients: { to: ["customer@example.com"], cc: [], bcc: [] }
      }
    }],
    line_items: [{
      name: "Consulting services",
      description: "Q4 2024 advisory",
      account: "<revenue_account_id>",
      quantity: 1,
      price: 5000,
      tax_rate: "<tax_rate_id>"
    }]
  }])
});
```

A successful request queues the invoice and returns `{"queued": 1}`; Wafeq then delivers the invoice PDF as an email attachment.

The `reference` field is your internal identifier. Use it to check for duplicates before creating — Wafeq does not enforce uniqueness on `invoice_number`, so deduplication logic needs to run on `reference`.

For tax rates, fetch the list from `GET https://api.wafeq.com/v1/tax-rates/` and match by name or code. In Saudi Arabia, the standard VAT rate is 15%. In the UAE, it's 5%.

## Error handling

Wafeq returns standard HTTP status codes. A few patterns worth handling explicitly:

`400 Bad Request` usually means a missing required field or a malformed account ID. The response body includes field-level error detail — parse it and log it, as the message is specific enough to act on.

`401 Unauthorized` means the API key is wrong, expired, or missing from the header. Check that your environment variable is set and the `Api-Key ` prefix (with the space) is included.

`429 Too Many Requests` means you've hit the rate limit. Implement exponential backoff with jitter. Wafeq's rate limits are not publicly documented, so treat any 429 as a signal to back off for at least 30 seconds before retrying.

`500 Internal Server Error` from Wafeq should be retried with idempotency keys in place. If the error persists across multiple retries, contact Wafeq support before assuming a code issue on your end.

## Webhooks (ZATCA Phase 2)

Webhooks in the Wafeq ecosystem are currently specific to the ZATCA Phase 2 API, not the standard invoicing API. Every document submitted to ZATCA generates a webhook about its current reporting state, which your integration can consume to stay in sync with ZATCA's response.

The webhook payload arrives as a POST to your registered endpoint and carries an `X-Wafeq-Webhook-Secret` header that is unique per integration, which you use to verify the request came from Wafeq. If that secret is ever compromised, Wafeq lets you regenerate it.

A reported invoice payload looks like this:

```json
{
  "payload": {
    "document": {
      "id": "61d7226e-c04a-4e55-a459-ad442812dbf0",
      "document_number": "INV-2023-001",
      "issue_datetime": "2023-09-04T13:05:38.113425Z",
      "supply_date": "2023-01-01"
    },
    "status": "reported",
    "response": { }
  },
  "event_id": "68158622-72be-4e53-8a2d-5e813c959abf",
  "event_type": "zatca.simplified_invoice.reported",
  "timestamp": "2023-09-04T13:05:44.887378Z"
}
```

The `status` field can be `failed`, `pending`, or `reported`. In your webhook handler, verify the secret first, then update your local record based on status. Return HTTP 200 promptly — processing should happen asynchronously.

For the standard invoicing API outside KSA Phase 2, Wafeq does not currently publish webhook events. Poll the invoices endpoint for status updates if your use case requires it.

## When to use a unified API instead

Building a direct Wafeq integration takes meaningful engineering time, and Wafeq is one of several accounting platforms you'll need to support if you're selling across MENA and beyond. Apideck's [accounting API](https://www.apideck.com/accounting-api) normalizes Wafeq alongside QuickBooks, Xero, Sage, and 20+ other systems behind a single interface. You write the integration once and activate connectors per customer from the full [accounting connectors list](https://www.apideck.com/connectors).

The trade-off is coverage: a unified layer gives you a common data model across platforms but cannot expose every Wafeq-specific field, particularly around ZATCA compliance details. For standard invoice creation, expense sync, and contact management, the unified model covers the common ground. For compliance-heavy workflows tied to KSA Phase 2 regulations, direct API access gives more control.

For teams integrating multiple accounting systems in parallel, starting with a unified accounting API and adding direct integration for edge cases is typically the faster path to production. If Wafeq is your only target and compliance depth matters, go direct.

---

To connect to Wafeq and 200+ other APIs without rebuilding the integration for each one, [start a free trial of Apideck](https://app.apideck.com/signup) and get running within 30 days.

A developer guide to the Wafeq accounting API: authentication, invoices, contacts, error handling, and ZATCA webhooks for KSA.

How to Build a Wafeq API Integration

Every accounting API integration project starts the same way. Your team picks the most popular platform (usually [QuickBooks](https://www.apideck.com/integrations/quickbooks)), builds the connector, ships it, and moves on. Then a customer asks for [Xero](https://www.apideck.com/integrations/xero). Another needs [NetSuite](https://www.apideck.com/integrations/netsuite). A third is on [Sage Intacct](https://www.apideck.com/integrations/sage-intacct). And suddenly you're looking at the same invoice object modeled three completely different ways, with different required fields, different tax logic, and different rules about what you can and can't write back.

The hard part of multi-platform accounting integration isn't connecting to each API. It's making the data look the same once it arrives. This article covers the specific places where QuickBooks, Xero, NetSuite, and Sage diverge at the field level, the mapping decisions that trip up most teams, and how to build normalization logic that handles platform gaps without breaking. If you're already familiar with [accounting software integration architecture](https://www.apideck.com/blog/accounting-software-integration) and you're past the build vs. buy decision, this picks up where those guides leave off.

## Where exactly do the data models diverge?

The four major platforms agree on the broad strokes. They all have invoices, contacts, payments, chart of accounts, and journal entries. The disagreements are in the details, and the details are where bugs live.

### How do invoices differ across platforms?

Invoices are the most common integration object, and they're also where the most field-level variation shows up.

QuickBooks Online structures an invoice with `Line` items, each containing a `DetailType` (usually `SalesItemLineDetail`) that references an `ItemRef` and a `TaxCodeRef`. Tax is computed per line. Discounts are their own line item type (`DiscountLineDetail`), not a property on the invoice. Currency is set at the customer level, not the invoice level, so a multi-currency invoice requires the customer record to already be configured for that currency.

Xero uses `LineItems` with a `TaxType` field per line, but adds a global `LineAmountTypes` enum on the invoice itself that determines whether amounts are tax-inclusive (`Inclusive`), tax-exclusive (`Exclusive`), or have no tax (`NoTax`). This distinction doesn't exist in QuickBooks. If you don't set it correctly, your totals will be off. Discounts in Xero are a `DiscountRate` or `DiscountAmount` on each line item, not a separate line. Xero also enforces a hard limit of 4,000 characters per `Description` field.

NetSuite models invoices as transaction records. Each line references an `item` with an `amount`, but the transaction itself carries dimensional data (subsidiary, department, class, location) that QuickBooks and Xero handle through separate mechanisms. Tax in NetSuite is handled through tax schedules and nexus configuration, which are set at the subsidiary level. A single invoice in NetSuite can easily have 30+ fields that don't exist in QuickBooks.

Sage (Business Cloud Accounting) uses `SalesInvoice` objects with `LineItems` that reference a `LedgerAccount`, a `TaxRate`, and a `Quantity`/`UnitPrice` pair. The tax structure changes depending on the regional edition (UK, US, Canada, Australia all differ). Sage also requires a `ContactId` on every invoice, where QuickBooks uses `CustomerRef` and Xero uses `Contact.ContactID`.

The practical consequence: you can't just map field names. You need transformation logic that understands how each platform computes totals, applies tax, and represents discounts. A "simple" invoice sync touches at least five areas of divergence per platform.

### Why are contacts the most deceptive normalization problem?

Contacts look straightforward until you realize each platform draws the entity boundaries differently.

QuickBooks Online maintains completely separate objects for `Customer` and `Vendor`. They have different endpoints, different fields, and different IDs. A business that is both a customer and a vendor exists as two unrelated records.

Xero collapses everything into a single `Contact` object. A contact's role is determined by a `IsCustomer`/`IsSupplier` boolean. One record can be both. This means a Xero contact ID maps to either a QuickBooks Customer ID or a Vendor ID (or both), and your normalization layer needs to track that relationship.

NetSuite goes further with separate entity types: `customer`, `vendor`, `partner`, `employee`, and `contact` (which is a person associated with a company). A vendor in NetSuite can have multiple `contact` sub-records, each with their own email, phone, and role.

Sage uses a `Contact` with a `ContactType` of `CUSTOMER` or `VENDOR`. Similar to Xero's model, but the field names and structures differ.

If your canonical model uses a single "contact" entity, you need bi-directional mapping rules that can split one record into two on write (Xero contact to QuickBooks customer + vendor) and merge two records into one on read (QuickBooks customer + vendor to a single canonical contact). Most teams don't account for this until a customer reports duplicate entries.

### What makes tax the hardest field to normalize?

Tax handling varies not just by platform but by jurisdiction, and the platforms encode jurisdictional rules differently.

QuickBooks Online has deep U.S. sales tax integration through its Automated Sales Tax (AST) engine. When AST is enabled, QuickBooks calculates tax automatically based on the customer's shipping address and the tax category of each line item. Your integration can't override this calculation; you can only pass the `TaxCodeRef` and let QuickBooks compute the amount. For non-U.S. QuickBooks companies, tax works more like Xero (manual tax rates applied per line).

Xero uses a `TaxType` per line that references a `TaxRate` object. The `TaxRate` contains a `TaxComponents` array, because a single tax rate can be a composite (e.g., Canadian GST + PST = HST). Your integration needs to handle composite rates if you're normalizing tax breakdowns across platforms.

NetSuite uses tax schedules, tax codes, and nexus records. Tax is configured at the subsidiary level, and the applicable tax depends on the combination of ship-to address, nexus, and item tax schedule. You can write a tax code to a transaction, but the actual tax calculation is governed by NetSuite's tax engine (or a third-party tax provider like Avalara).

Sage's tax handling depends on the regional API edition. The UK edition expects VAT rates tied to `TaxRate` objects. The U.S. edition handles sales tax differently. A single normalization model for tax needs to account for these regional variants within the same vendor.

The safe approach: normalize the tax output (rate, amount, whether it's inclusive or exclusive) rather than trying to normalize the tax configuration. Let each platform compute tax its own way. Push the minimum required tax references, and read back the computed amounts.

## How do you handle features that only some platforms support?

This is where most normalization layers get brittle. Your canonical model assumes a certain set of fields, but not every platform supports every field. Pushing a value that doesn't exist on the target platform can cause silent data loss or API errors.

### What does capability detection look like in practice?

Before writing any transaction, your integration should check what the connected account actually supports. This goes beyond checking the platform name. QuickBooks Online has Classes and Locations as optional tracking dimensions, but they need to be explicitly enabled in the company settings. An integration that blindly sends `ClassRef` on an invoice to a QuickBooks account that hasn't enabled class tracking will get an error.

Xero limits tracking categories to two per organization. Not two per transaction, two total across the entire organization. If a customer has already used both tracking category slots, your integration can't add a third. You need to query available categories at connection time and adapt your mapping.

NetSuite supports virtually unlimited custom segments, but each segment needs to be configured per subsidiary. A segment that exists on one subsidiary might not exist on another.

The pattern that works: at connection time (or on a scheduled refresh), query the available dimensions, tax rates, account categories, and feature flags for the connected account. Cache the results and use them to validate outbound data before sending it. This prevents runtime errors and gives you a basis for telling customers which features are available for their specific setup.

For a detailed walkthrough of how tracking dimensions work across all four platforms, see [Understanding Tracking Dimensions in Accounting Integrations](https://www.apideck.com/blog/tracking-dimensions-in-accounting-integrations).

### How should your integration degrade when a field isn't supported?

There are three options when your canonical model includes a field that the target platform doesn't support: drop the field silently, surface a warning, or block the write. The right choice depends on the field.

For optional metadata (internal notes, custom tags, reference numbers that aren't used for reconciliation), silent drop is usually fine. Log it, move on.

For fields that affect financial accuracy (tax codes, tracking dimensions, account mappings), a warning is the minimum. The customer needs to know that data they expected to flow through didn't land on the other side. Build this into your sync status reporting so customers can see exactly which fields were included, which were dropped, and why.

For required fields where the absence would create an incorrect financial record (wrong GL account, missing tax treatment, missing subsidiary in NetSuite), block the write. Return a clear error that tells the customer what's missing and how to fix it. A rejected sync is better than a posted transaction in the wrong account.

## What are the hard normalization cases most teams miss?

The first version of any normalization layer handles the common fields. These are the cases that break it.

### How do you normalize chart of accounts?

Chart of accounts is where customer-specific configuration collides with platform-specific structure. Your product categories need to map to GL accounts in the customer's accounting system, and every customer's chart is different.

QuickBooks Online organizes accounts by `AccountType` (Asset, Liability, Revenue, Expense, etc.) and `AccountSubType` (a more granular classification). Account numbers are optional and need to be enabled in settings.

Xero uses `Type` and `Class` with different enum values. Xero's types don't map 1:1 to QuickBooks' types. For example, QuickBooks has separate types for `Accounts Receivable` and `Other Current Asset`; in Xero, both fall under the `CURRENT` class.

NetSuite's chart of accounts is segmented by subsidiary. A GL account might exist in one subsidiary but not another. Account numbers are mandatory in NetSuite (unlike QuickBooks where they're optional).

The practical approach: don't try to auto-map your product's categories to GL accounts. Expose a mapping UI that lets customers choose which GL account corresponds to each of your categories. Query the chart of accounts from the connected platform, present it as a dropdown, and let the customer decide. Store the mapping per customer, per platform. This is one area where automating the decision creates more problems than it solves. For more on how to structure this mapping layer, the [Accounting API Integrations for Fintech](https://www.apideck.com/blog/the-complete-guide-to-accounting-api-integrations-for-fintech) guide covers the architecture in depth.

### How do you handle multi-entity and multi-currency?

Multi-entity (subsidiaries in NetSuite, organizations in Xero) means that a single customer connection might span multiple legal entities, each with its own chart of accounts, tax configuration, and base currency.

NetSuite requires a `subsidiary` field on most transactions. If the connected account has multiple subsidiaries and you don't specify one, the write fails. Your integration needs to detect multi-subsidiary accounts at connection time, present the available subsidiaries to the customer, and scope all subsequent reads and writes to the selected subsidiary.

Xero handles multi-organization through separate OAuth connections per organization. Each organization is a distinct tenant with its own `Xero-Tenant-Id`. This is simpler from a data isolation perspective but means your customers need to authorize each organization separately.

Multi-currency adds another layer. QuickBooks requires the customer record to be configured for a specific currency before you can create a foreign-currency invoice against that customer. Xero allows multi-currency invoices but requires the `CurrencyCode` on the invoice and computes exchange rates from its own rate feed (or lets you specify a manual rate). NetSuite handles exchange rates through its multi-currency configuration at the subsidiary level.

Your normalization layer needs to know: does this account have multi-currency enabled? What currencies are available? Does the platform compute exchange rates, or do I need to provide them? Getting this wrong produces invoices with incorrect amounts in the base currency, which surface as reconciliation errors at month-end.

## When does a unified API make more sense than building this yourself?

Everything above needs to be built and maintained per platform. For teams that need two platforms, building the normalization layer in-house is realistic. The work gets heavy at three, and by four or five platforms, the maintenance cost (tracking API changes, managing auth token lifecycles, handling edge cases per provider) tends to consume more engineering time than the core product work.

A [unified accounting API](https://www.apideck.com/accounting-integrations) like Apideck absorbs this normalization work. You integrate once against a single canonical model, and the unified API handles the per-platform field mapping, auth, rate limiting, and transformation for 25+ accounting providers. When QuickBooks changes its token policy or Xero adjusts its rate limits, the unified API provider handles the update.

The trade-off is that you work within the unified model's field coverage. For the common accounting objects and the field-level variations described in this article, unified APIs cover the vast majority of cases. For highly platform-specific features that fall outside the normalized model, Apideck supports a [passthrough mechanism](https://www.apideck.com/blog/accounting-software-integration) that lets you send raw requests to the downstream API alongside normalized calls.

If you're evaluating whether to build or buy, the [Build vs Buy Accounting Integrations](https://www.apideck.com/blog/build-vs-buy-accounting-integrations) breakdown covers the cost and timeline math in detail. The short version: the normalization work described in this article is exactly the part that gets expensive to maintain at scale, and it's the part a unified API is specifically designed to absorb.

Learn how to standardize data across accounting software during API integration projects. See how QuickBooks, Xero, NetSuite, and Sage differ across invoices, contacts, tax, chart of accounts, and multi-currency workflows.

How to Standardize Data Across Accounting Software: QuickBooks, Xero, NetSuite, Sage

The worst API integration challenges don't show up during development. A team building a cash flow dashboard for SMBs connected to Xero, FreshBooks, and Sage Intacct in their first year. By year two, two engineers were spending most of each sprint on maintenance. Not new features. Maintenance. The culprits were a FreshBooks field rename that turned `amount_outstanding` into `outstanding_balance` without a version bump, a Sage Intacct session expiry that only surfaced in multi-tenant setups, and a Xero cursor that expired mid-sync on accounts with more than 1,000 invoices. None of those failures were in the original build.

That pattern is common. The initial implementation is manageable: authenticate, map the data model, handle pagination, ship. What accumulates is maintenance driven by changes the provider controls. Four categories account for most of it.

## Authentication breaks in ways the docs don't warn you about

The OAuth 2.0 flow itself isn't the problem. The edge cases are.

Xero access tokens expire after 30 minutes. QuickBooks Online access tokens expire after 60 minutes, with Intuit having moved to daily refresh token rotation in late 2025 per their [developer changelog](https://truto.one/blog/how-to-integrate-with-the-quickbooks-online-api-2026-guide). Sage Intacct uses a session-based model that doesn't follow standard REST token conventions at all. Each additional accounting platform means another auth lifecycle to manage and another set of failure modes to handle.

Token revocation creates a different class of failure. The trigger can be as simple as a user disconnecting their accounting software, or as broad as an auth infrastructure change from the provider. Your system sees a 401 and needs to decide: retry automatically or surface a re-auth prompt to the user. Most teams build this flow after the first production incident.

The fix for the most common case — access token expiry — is proactive refresh with a buffer window:

```python
def get_valid_token(connection):
    # Refresh if expiry is within 5 minutes
    if connection.expires_at - time.time() < 300:
        connection = refresh_oauth_token(connection.refresh_token)
        save_connection(connection)  # persist both new tokens immediately
    return connection.access_token
```

This eliminates the failure mode where you make a request, receive a 401 mid-flight, and have to handle refresh and retry in the error path. Refresh in the happy path, not the error path.

Scope additions create a third scenario. Xero added the `payroll.read` scope to cover payroll data that was previously bundled under `accounting.read`. Teams with existing authorized connections couldn't read payroll data until users completed a new auth flow. Handling the transition — some connections with the new scope, some without — requires logic that was never part of the original spec.

## Schema changes break sync without throwing errors

In early 2024, Harvest renamed `client.name` to `client.display_name` in their API response. There was no breaking change by their definition because both fields coexisted temporarily. Teams relying on `client.name` got empty strings. No error, no 400, just null data flowing downstream into reporting tables.

FreshBooks did something similar with invoice line items. The `tax1_name` and `tax2_name` fields were deprecated in favor of a `taxes` array. Old responses still included the flat fields for existing integrations, but new invoices created after the migration only populated `taxes`. Teams that hadn't updated their mapping got tax data on historical invoices but not new ones.

Defensive parsing handles both shapes without breaking during the transition period:

```python
def parse_invoice_tax(invoice: dict) -> tuple:
    # New shape: taxes array (post-migration FreshBooks invoices)
    if invoice.get("taxes"):
        return (
            invoice["taxes"][0].get("name"),
            invoice["taxes"][0].get("amount", 0),
        )
    # Old shape: flat fields (pre-migration or legacy responses)
    return invoice.get("tax1_name"), invoice.get("tax1_amount", 0)
```

For accounting data, that kind of silent failure is worse than an error. An invoice that syncs with `tax_amount: 0` because the field moved doesn't fail reconciliation — it passes with wrong numbers. That error surfaces at month-end, by a human, after the data has already been used. The [API integration best practices](https://www.apideck.com/blog/api-integration-best-practices) post covers defensive mapping patterns that catch field-level changes before they reach your data layer.

## Pagination fails in edge cases you won't hit in development

Most staging environments have tens of records. Production accounts have thousands. The difference exposes pagination bugs that never appear in testing.

Xero's pagination uses page numbers with a 100-record limit. On an account with exactly 100 invoices, the first page returns 100 results with no `hasNextPage` flag, and some implementations treat that as complete. At 101 invoices, the second page exists — but if your logic stops when it gets a full page back rather than checking the flag, you miss the last batch. This is a real edge case that has caused missed-record bugs on [Xero](https://www.apideck.com/connectors/xero) integrations at exactly the page-size boundary.

The correct termination condition uses the pagination flag, not the result count:

```python
def fetch_all_invoices(xero_client):
    invoices, page = [], 1
    while True:
        result = xero_client.get_invoices(page=page, pageSize=100)
        invoices.extend(result.get("Invoices", []))
        # Never use len(result) == 100 as the continuation condition
        if not result.get("pagination", {}).get("hasNextPage"):
            break
        page += 1
    return invoices
```

NetSuite's SuiteQL pagination uses `hasMore` and `offset`, and the total count returned in the first response is an estimate. If records are deleted during traversal, the estimated count becomes incorrect. An integration syncing 5,000 transaction records that sees 200 deletions mid-sync can stop pagination early, leaving a gap that shows up in reconciliation but not in error logs.

Cursor expiry is its own problem. Some providers issue cursors that expire after a fixed window. If a large [QuickBooks Online](https://www.apideck.com/connectors/quickbooks) account sync takes longer than expected due to rate limiting or network conditions, a mid-traversal cursor expiry forces a restart from page one. Without deduplication logic, that produces duplicate records. The [third-party API integration](https://www.apideck.com/blog/third-party-api-integration) post covers rate limit strategies across multi-provider setups.

## Webhooks are reliable enough to trust and unreliable enough to verify

Stripe's webhook delivery is explicitly at-least-once per their [documentation](https://stripe.com/docs/webhooks). That means a `charge.succeeded` event may arrive twice. If your payment confirmation handler isn't idempotent — checking whether you've already processed the event ID before writing — you can record the same payment twice. Stripe provides an event ID on every webhook payload specifically to enable this check:

```python
def handle_charge_succeeded(event_id: str, payload: dict):
    if ProcessedEvent.objects.filter(event_id=event_id).exists():
        return  # duplicate delivery — already handled
    with transaction.atomic():
        record_payment(payload["data"]["object"])
        ProcessedEvent.objects.create(event_id=event_id)
```

Xero sends full payloads on its webhooks, which makes handler logic straightforward. QuickBooks Online sends only a notification: entity ID and operation type. Your handler then makes a follow-up API call to fetch the current record state. Under high event volume — a batch payroll run, a bulk invoice import — those follow-up calls can hit rate limits, creating a queue of pending fetches that lags minutes behind real-time.

Xero signs webhook payloads with HMAC-SHA256 using a webhook signing key. Stripe uses its own HMAC-SHA256 mechanism via `Stripe-Signature`. Verifying the signature before processing is a one-time implementation that eliminates the attack surface:

```python
import hmac, hashlib, base64

def verify_xero_signature(payload_bytes: bytes, header_sig: str, signing_key: str) -> bool:
    expected = hmac.new(signing_key.encode(), payload_bytes, hashlib.sha256).digest()
    return base64.b64encode(expected).decode() == header_sig
```

If you're not verifying signatures on inbound events, any system that can reach your webhook endpoint can trigger your handler. On a multi-tenant accounting integration where a single event can write to multiple company records, that's a meaningful exposure.

## Solving API integration challenges at scale

Each of these challenges is solvable individually. You build a token refresh manager. You write a schema validation layer that catches unexpected nulls before they hit your database. You implement cursor checkpointing. You add idempotency keys to webhook handlers.

The question is whether building and maintaining that infrastructure is the actual product you're trying to ship. Most teams supporting [multiple accounting platforms](https://www.apideck.com/blog/third-party-api-integration) find that it isn't — it's a prerequisite for the product.

A [unified API](https://www.apideck.com/blog/what-is-api-integration) handles that layer. A single auth model and normalized data schema for all providers, with one webhook format regardless of the source. When a provider renames a field, the normalized schema doesn't change on your side. When a token rotation policy shifts, that's the unified API vendor's problem to absorb.

The [custom vs. unified](https://www.apideck.com/blog/custom-api-integration) tradeoff changes once you're past three or four accounting platforms. If you're evaluating where your stack sits, the [30-day free trial](https://app.apideck.com/signup) is the fastest way to compare directly.

Real API integration challenges with concrete examples: auth edge cases, silent schema failures, pagination bugs, and webhook reliability.

API Integration Challenges: What Actually Breaks at Scale

Most integration teams get the happy path working in the first sprint. The rest of the work shows up later: token refresh cycles, pagination edge cases, idempotent writes, rate limit handling under sustained load. It surfaces when a customer reports a problem in production.

The sequencing makes this predictable. The behaviors that matter most for integration reliability are invisible in development and testing. Your test environment has 50 records and a stable network. Production has 50,000 records, a QuickBooks rate limit that varies by subscription tier, and a webhook endpoint that was briefly down during a deployment last Tuesday. These API integration best practices are written for developers building integrations with accounting platforms and payment processors, not generic horizontal SaaS.

## Authentication best practices: build for the token lifecycle

Most integrations implement OAuth correctly for the initial authorization flow. The failure point is token management afterward.

Access tokens expire. QuickBooks Online tokens expire after 60 minutes; Xero tokens expire in 30 minutes. If your integration stores the access token without implementing refresh logic, requests start returning 401s when the token expires. The user doesn't see a clear error. They see data that stopped syncing.

The correct pattern: store both the access token and refresh token alongside the expiry timestamp. Before every API call, check whether the access token is within a few minutes of expiry. If it is, refresh proactively before making the request. This eliminates the failure mode where you make a request, get a 401, and have to handle refresh mid-flight.

```python
def get_valid_token(connection):
    if connection.expires_at - time.time() < 300:  # 5-minute buffer
        connection = refresh_token(connection.refresh_token)
    return connection.access_token
```

For API key-based auth (common across many [accounting integrations](https://www.apideck.com/blog/financial-api-integration)), the practice most teams skip is rotation planning. API keys don't expire on their own, which makes them feel lower-maintenance than OAuth. But when a key is compromised or a team member with access leaves, you want a rotation procedure that doesn't require an hour of coordination. Store API keys in environment variables or a secrets manager, never in application code or config files committed to version control.

For customer-facing integrations where you're managing credentials on behalf of users, [Apideck Vault](https://www.apideck.com/vault) handles token storage and lifecycle across connectors without your application touching raw credentials directly. For a deeper look at the [authentication methods](https://www.apideck.com/blog/api-auth-authentication-methods-and-examples) used across different accounting APIs (OAuth, API keys, HMAC, OIDC), that guide covers each one in detail.

## Pagination: handle every pattern

APIs implement pagination differently. Offset-based pagination (`?page=2&limit=100`) is intuitive but breaks at scale: if records are added or deleted between requests, you can miss records or process duplicates. Cursor-based pagination (where the API returns a `next_cursor` value you pass on the next request) is more reliable for large datasets.

QuickBooks Online and Xero both use offset-based pagination. When syncing invoices from a customer's account, you need to handle results that come in under the page size limit, APIs that don't return total record counts (you only learn there's no next page when you get an empty result), and termination conditions based on `has_more` rather than result count alone.

A reliable pagination loop:

```python
def fetch_all_invoices(client):
    invoices = []
    offset = 0
    page_size = 100
    
    while True:
        page = client.get_invoices(offset=offset, limit=page_size)
        invoices.extend(page.results)
        
        if len(page.results) < page_size or not page.has_more:
            break
            
        offset += page_size
    
    return invoices
```

One pattern that breaks in production: assuming that if `len(results) == page_size`, there's always another page. APIs sometimes return exactly `page_size` results on the final page. Build your termination condition around `has_more` or a `next_cursor` field when available.

## Idempotency and the idempotent API: required for financial writes

When your integration creates an invoice, syncs a payment, or posts a journal entry, network failures can leave you uncertain whether the operation succeeded. A naive retry creates duplicate records in your customer's accounting system. That's a support issue that takes real time to unwind.

Some financial APIs support idempotency keys directly. Stripe accepts an [`Idempotency-Key` header](https://stripe.com/docs/api/idempotent_requests); if you send the same key on a retry, Stripe returns the original response rather than processing the request again. QuickBooks Online doesn't have a native idempotency header, so you implement it at the application layer:

1. Generate a UUID for each operation before sending the request.
2. Store that UUID with the pending state in your own database.
3. On success, update to completed with the remote ID returned.
4. On failure, check the remote system for the record before retrying, using your internal reference ID, amount, date, and description as the lookup key.

This is more work than a simple API call, but accounting integrations have low tolerance for duplicate records. A billing platform that double-posts revenue to a customer's general ledger will hear about it.

## Error handling: separate 4xx from 5xx

4xx errors are your fault or your user's fault. 5xx errors are the upstream API's fault. Retry logic should reflect this distinction.

For 4xx responses:
- **400 Bad Request:** your payload is malformed. Retrying won't help. Log the full request payload and fix the code.
- **401 Unauthorized:** your token is expired or invalid. Refresh the token, then retry once.
- **403 Forbidden:** the token is valid but lacks the required scope. Surface this to the user as a configuration issue, not a transient error to retry.
- **404 Not Found:** the record doesn't exist. If it's a lookup, handle the empty case. If it's an update, the remote record was deleted.
- **429 Too Many Requests:** you've hit the rate limit. Back off using the `Retry-After` header value.

For 5xx errors, retry with exponential backoff plus jitter:

```python
import random
import time

def retry_with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return fn()
        except ServerError as e:
            if attempt == max_retries - 1:
                raise
            wait = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait)
```

The `random.uniform` component (jitter) prevents the thundering herd problem: without it, multiple failed requests all retry at the same interval and hit the API simultaneously.

## API rate limiting: read the headers on every response

Every accounting API publishes rate limit information in response headers. QuickBooks Online returns rate limit headers when requests approach the limit; Xero returns them on every response (enforcing 60 calls per minute and 5,000 per day per organization). If your integration ignores these headers, you'll hit the limit hard and get blocked rather than pacing requests naturally.

A rate-limit-aware client reads the remaining count on each response. When remaining drops below a threshold, it slows down proactively rather than waiting for a 429. When it receives a 429, it reads `Retry-After` and waits exactly that long before retrying.

QuickBooks Online's per-minute limits vary by subscription tier. A Simple Start account has a lower limit than a Plus account. If you assume a fixed limit and run the same request cadence against all customers, you'll hit limits on lower-tier accounts without understanding why. Build handling that adapts to the headers returned, not to a hardcoded assumption.

For large initial syncs, queue write operations rather than firing them in parallel. Pulling three months of transactions for a new connection involves a lot of requests across invoices and payments. A queue with a controlled dispatch rate is more reliable than parallel batches competing for the same rate limit budget.

## Schema drift: subscribe to changelogs and parse defensively

APIs change. Accounting APIs change often. Regulatory requirements and feature launches create constant pressure to modify data models.

Scope requirements for QuickBooks Online have evolved as Intuit has added features and deprecated legacy access patterns. Xero introduced granular scopes for apps created from March 2026 onward, changing how permissions are requested and authorized. Integrations that don't account for these changes break for new user authorizations while continuing to work for existing ones, which makes them particularly hard to diagnose.

Two practices protect against most drift. Subscribe to the API changelog: [QuickBooks Online Developer](https://developer.intuit.com/app/developer/qbo/docs/get-started) and [Xero Developer](https://developer.xero.com/documentation/api-guides/changelog/) both publish release notes and notification feeds. Parse defensively: don't fail if a response contains unexpected fields. A JSON parser configured to error on unknown properties will break the first time a provider adds a new field to their response.

The third thing is to test against staging with realistic data volumes on a schedule, not just at build time. Minimal test datasets miss edge cases that only show up at production scale.

## Webhook reliability: verify signatures, handle replays

Webhooks require a different reliability model than polling. With polling, you control when you ask. With webhooks, the upstream API decides when to send data, and your job is to receive it reliably even during brief outages.

Verify every webhook payload signature before processing it. Most accounting and payment APIs include HMAC signatures in their headers. Stripe uses a `Stripe-Signature` header; QuickBooks Online uses a verifier token in the payload. An unverified webhook endpoint accepts spoofed events. For integrations that post journal entries on payment receipt, a spoofed payment event could trigger incorrect financial records.

Respond with 200 immediately, then process asynchronously. Stripe requires a response within 30 seconds; most accounting APIs enforce similar windows. If your processing involves slow database writes or downstream API calls, you'll miss the timeout and trigger retries. Acknowledge receipt first, then handle the payload in a background worker.

Expect replays. Providers retry on non-200 responses and network timeouts. Your handler needs to be idempotent: processing the same event twice should produce the same result as processing it once. Store the event ID and check it before processing to deduplicate.

## When to stop building and start abstracting

These practices get one integration to production reliability. The maintenance math changes when you need five, then ten. Each one needs its own OAuth implementation, its own rate limit handler, its own pagination logic, its own drift monitoring.

[Unified APIs](https://www.apideck.com/blog/what-is-api-integration) normalize authentication, pagination, and data models across accounting platforms. You implement these patterns once against a single endpoint, and the connector layer handles the provider-specific implementations. For vertical SaaS teams supporting whatever accounting system their customers use, this is where the build vs. buy calculation changes. The [API integration cost analysis](https://www.apideck.com/blog/api-integration-cost) covers that math in detail.

If you want to see how it works in practice, Apideck's [30-day free trial](https://app.apideck.com/signup) gives you access to the full connector catalog and sandbox environments for QuickBooks and Xero, along with 20+ other platforms.

Practical API integration best practices covering OAuth token lifecycle, pagination, idempotency, error handling, and rate limits — with code examples for accounting and fintech integrations.

API Integration Best Practices for Developers

Tripletex is the accounting platform that owns the Norwegian SMB market. With [150,000 customers as of late 2025](https://www.visma.com/news/tripletex-reaches-150000-customers) and Visma's acquisition in 2016 bringing deeper engineering investment, it's a required integration for any SaaS product serving Nordic customers. The API covers the full accounting lifecycle: customers, suppliers, orders, invoices, vouchers, hours, projects, and inventory.

This guide walks through the complete integration path, from setting up a test environment to production approval, with working code examples for authentication and the endpoints you'll use most.

> **Auth note:** Tripletex does not use OAuth 2.0. It uses a proprietary two-token system where a consumer token and an employee token are combined to generate a session token. That session token is then used as the password in HTTP Basic authentication. The setup is different enough from standard OAuth flows that it trips up developers who assume they can reuse boilerplate. Read this section carefully before writing any code.

## Prerequisites

Before you start:

- A Tripletex test account, registered at [api-test.tripletex.tech](https://api-test.tripletex.tech). You get both tokens and an activation email on signup — the test environment is fully self-service.
- Familiarity with HTTP Basic authentication and REST APIs.
- A decision on integration scope: are you integrating for a single company (regular employee token) or building a multi-client accountant integration (accountant token)? The auth flow differs.
- For production: a submitted [access application](https://docs.google.com/forms/d/e/1FAIpQLSdvZXwahq8sr4YKz3h9e4THhE4Gk6vO1F0Hf4rUPIsDD2E0KA/viewform). Approval takes 2–3 weeks with no expedited option.

## Step 1: Create a test account

Go to [api-test.tripletex.tech](https://api-test.tripletex.tech) and register. You'll receive:

- A **consumer token** — this identifies your application. One token per integration, shared across all end users.
- An **employee token** — this represents the user within a specific company. End users create their own employee tokens from the Tripletex GUI in production; in the test environment you get one automatically.
- An email for user activation.

Test credentials only work against `api-test.tripletex.tech`. They will not work against the production API at `tripletex.no`, and vice versa. Keep them in separate environment variable files.

Test accounts stay active for six months. If you lose your tokens, Tripletex cannot recover them. Create a new test account to get fresh ones.

## Step 2: Generate a session token

The session token is created by combining your consumer token and employee token in a single API call. You exchange these credentials once to receive a session token, which you then use for all subsequent requests.

Session tokens expire at midnight CET on the expiration date you specify. The API does not issue refresh tokens — you generate a new session token before the current one expires.

```bash
curl -X PUT \
  "https://api-test.tripletex.tech/v2/token/session/:create?consumerToken=YOUR_CONSUMER_TOKEN&employeeToken=YOUR_EMPLOYEE_TOKEN&expirationDate=2026-05-10" \
  -H "Content-Type: application/json"
```

The response contains your session token:

```json
{
  "value": {
    "id": 12345,
    "token": "eyJjb25zdW1lclRva2VuIjoiYWJj...",
    "expirationDate": "2026-05-10"
  }
}
```

In Python:

```python
import requests
from datetime import date, timedelta

CONSUMER_TOKEN = "your_consumer_token"
EMPLOYEE_TOKEN = "your_employee_token"

tomorrow = (date.today() + timedelta(days=1)).isoformat()

response = requests.put(
    "https://api-test.tripletex.tech/v2/token/session/:create",
    params={
        "consumerToken": CONSUMER_TOKEN,
        "employeeToken": EMPLOYEE_TOKEN,
        "expirationDate": tomorrow
    }
)

session_token = response.json()["value"]["token"]
```

Store this session token. You'll use it as the password in every subsequent request.

## Step 3: Authenticate requests

Tripletex uses HTTP Basic authentication for all API calls after session creation. The username is `0` (zero), which tells the API you want to access the company owned by the employee token. The password is the session token.

```python
import requests

session = requests.Session()
session.auth = ("0", session_token)

# Test it with a simple company info request
response = session.get("https://api-test.tripletex.tech/v2/company")
print(response.json())
```

If you're building an accountant integration — where your application accesses multiple client companies through one accountant user — the username is not `0`. You first call `GET /company/>withLoginAccess` to get the list of accessible companies, then use the company ID as the username for subsequent requests to that company's data.

## Step 4: Core endpoints

The Tripletex API covers most accounting objects. The [OpenAPI documentation](https://api-test.tripletex.tech/v2-docs/) is the canonical reference, with interactive testing built in.

The endpoints you'll use most in standard SaaS integrations:

**Invoices and orders**

```
GET  /v2/invoice          # List invoices with filters
POST /v2/invoice          # Create an invoice
GET  /v2/invoice/{id}     # Get a specific invoice
PUT  /v2/invoice/{id}     # Update
GET  /v2/order            # List orders
POST /v2/order            # Create an order
```

**Customers and suppliers**

```
GET  /v2/customer         # List customers
POST /v2/customer         # Create a customer
GET  /v2/supplier         # List suppliers
POST /v2/supplier         # Create a supplier
```

**Ledger and vouchers**

```
GET  /v2/ledger/voucher   # List vouchers
POST /v2/ledger/voucher   # Create a voucher (bookkeeping entry)
GET  /v2/account          # Chart of accounts
```

**Products and inventory**

```
GET  /v2/product          # List products
POST /v2/product          # Create a product
GET  /v2/inventory        # Inventory records
```

Tripletex supports the `fields` parameter on GET endpoints to limit response size:

```
GET /v2/customer?fields=id,displayName,email
```

Use it. Responses without field filtering return the full object graph, which is large for customers and orders. On high-volume syncs, the bandwidth and processing overhead adds up.

For date-range filtering on orders:

```
GET /v2/order?orderDateFrom=2026-01-01&orderDateTo=2026-03-31&isClosed=false
```

## Step 5: Sync data with webhooks

Polling is the wrong sync pattern for Tripletex. The API has a full [webhook system](https://developer.tripletex.no/docs/documentation/webhooks/) with guaranteed delivery, which means you should use it for anything that updates frequently: invoices, payments, orders.

Subscribe to events by registering a webhook endpoint:

```python
response = session.post(
    "https://api-test.tripletex.tech/v2/event/subscription",
    json={
        "event": "v2.Invoice.*",  # Covers create, update, delete
        "targetUrl": "https://your-app.com/webhooks/tripletex",
        "fields": "id,status,amountIncludingVat"
    }
)
```

Available event namespaces include `v2.Invoice`, `v2.Order`, `v2.Customer`, `v2.Supplier`, `v2.Voucher`, and more. Wildcards (`v2.Invoice.*`) subscribe to all event types within that namespace.

Tripletex guarantees webhook delivery as long as your endpoint is available. If your server is offline temporarily, events are queued and retried. Set up proper HTTP 200 acknowledgment on receipt — the system treats anything other than 2xx as a failure and retries.

For smaller or infrequently changing datasets, the [checksum API](https://developer.tripletex.no/docs/documentation/checksum/) gives you a hash of a dataset. Compare the hash on a schedule; if it changes, pull the delta. This works well for product catalogs and chart of accounts where webhooks would be over-engineered.

## Step 6: Apply for production access

Tripletex requires a formal application before you can use the production API at `tripletex.no`. Submit the [production access form](https://docs.google.com/forms/d/e/1FAIpQLSdvZXwahq8sr4YKz3h9e4THhE4Gk6vO1F0Hf4rUPIsDD2E0KA/viewform) after you've finished testing. You'll need to describe your integration, your application name, and your use case.

The approval takes 2–3 weeks for everyone, no exceptions. Plan your launch timeline accordingly. Once approved, you receive a production consumer token via email along with your official application name in the Tripletex ecosystem. End users then generate their own employee tokens through the Tripletex GUI by selecting your application name from the dropdown.

## Common gotchas

**Test and production tokens are completely separate.** This is obvious in retrospect but causes real problems when developers test successfully and then deploy. Your test consumer token will fail against `tripletex.no`. Your production consumer token will fail against `api-test.tripletex.tech`. Use distinct environment variables and fail loudly on startup if the wrong base URL is configured.

**Session tokens expire at midnight CET, not 24 hours from creation.** If you create a session token at 23:50 CET with an expiration date of today, it expires in 10 minutes, not 24 hours. Set expiration dates relative to CET, not UTC, and build in a buffer. A background job that regenerates the session token once per day at a fixed time in the morning is the simplest approach.

**Employee tokens inherit the owner's permissions.** If a user creates an employee token with "All entitlements" but they don't have those entitlements themselves, the excess permissions are granted but disabled. Your API calls will fail on those scopes. The fix is to either get the user to grant the correct entitlements on their account, or scope your token request to only what you need.

**Application name is case-sensitive.** When end users create employee tokens in the Tripletex GUI without your application in the dropdown (using "Adapted setup"), they have to type your application name exactly as registered. A single capital letter difference means Tripletex won't recognize the token as belonging to your integration. Make this instruction explicit in your onboarding flow.

**Accountant token access doesn't work with username `0`.** If you're using an accountant token to access client companies, every request to a specific client's data needs that client's company ID as the username. Using `0` will either return the accountant's own (usually empty) account data or return an error, depending on the endpoint.

**The OpenAPI docs have two instances.** The test environment documentation is at `api-test.tripletex.tech/v2-docs/` and the production docs are at `tripletex.no/v2-docs/`. They're nearly identical, but when debugging, make sure you're reading the documentation for the environment you're testing against. Credentials authenticated in one environment won't work in the other's documentation either.

## Security practices

Store your consumer token in an environment variable, never in source code. It's a long-lived credential that applies across all your end users — a leak affects everyone connected to your integration.

Scope employee token permissions to what your integration actually needs. If you only sync invoices and customers, don't request voucher or payroll access. End users are more likely to approve and less likely to revoke tokens with a narrow scope.

Set session token expiration dates intentionally. A session token that expires in 30 days and isn't refreshed will break your integration silently at midnight on day 30. Build explicit token lifecycle management into your integration layer: track expiration dates, refresh proactively, and surface connection errors to users when tokens expire unexpectedly.

Use separate test and production configurations in your deployment pipeline. Environment-level validation on startup prevents deploying test credentials to production or accidentally writing to production data during development.

## What to build toward

For teams building integrations across multiple Nordic or European accounting platforms alongside Tripletex — Exact Online in the Netherlands and Belgium, Yuki for Dutch bookkeeping workflows, or Visma's own eAccounting platform under the Spiris brand — the maintenance cost of managing separate authentication flows and data models adds up quickly.

The [complete guide to accounting API integrations](https://www.apideck.com/blog/the-complete-guide-to-accounting-api-integrations-for-fintech) covers the architecture decisions that matter when you're supporting more than one platform: how to isolate your integration layer, handle partial failures across systems, and structure your data models to avoid per-platform branching in your core product.

Apideck doesn't yet have a Tripletex connector on its [unified accounting API](https://www.apideck.com/accounting-api), though Tripletex support is in the pipeline. If you're integrating with QuickBooks, Xero, or other major accounting platforms alongside Tripletex, the unified API approach can handle those connections through a single normalized interface while you manage the Tripletex integration directly.

Step-by-step guide to integrating with the Tripletex API — token auth, session management, core endpoints, webhooks, and production access in one guide.

How to Integrate with the Tripletex API

Fortnox is the dominant accounting platform in Sweden, used by more than 600,000 businesses across the Nordics. For SaaS companies, fintechs, and vertical software vendors targeting that market, a Fortnox API integration is not a nice-to-have. It's a table-stakes requirement.

This guide walks through everything you need to build a working Fortnox API integration: OAuth 2.0 authentication, token management, key endpoints with real request and response examples, the pagination model, webhook limitations, and the rate limits that will bite you at scale if you don't plan for them.

## Setting up your Fortnox developer account

Before you can make any Fortnox API calls, you need to register as a developer at [apps.fortnox.se/developer](https://apps.fortnox.se/developer). This gives you access to the Developer Portal where you create your integration and receive your Client ID and Client Secret.

One constraint for international teams: Fortnox requires a Swedish personal or organization ID to complete registration. If your company is not Swedish, you'll need to partner with a local entity or use a third-party sandbox provider to start testing. This is worth confirming before you schedule any development sprints.

Once registered, you create an integration record. This is where you configure your redirect URI, define your requested scopes, and optionally submit for Fortnox Marketplace listing.

## OAuth 2.0 authentication

Fortnox uses the [OAuth 2.0 Authorization Code Flow](https://www.fortnox.se/developer/authorization). The old fixed access token authentication was fully deprecated on April 30, 2025. Any integration still using the legacy `Client-Secret` / `Access-Token` header combination needs to migrate.

Step one is sending the user to the Fortnox authorization URL:

```
GET https://apps.fortnox.se/oauth-v1/auth
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &scope=invoice%20customer%20companyinformation
  &state=RANDOM_CSRF_TOKEN
  &access_type=offline
  &response_type=code
```

`access_type=offline` is required to receive a refresh token. The `state` value should be a random string you verify on callback. For a service account not tied to a specific user, add `account_type=service`.

After the user authorizes your app, Fortnox redirects to your redirect URI with an authorization code valid for 10 minutes. Exchange it immediately:

```bash
curl -X POST https://apps.fortnox.se/oauth-v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=authorization_code&code=AUTH_CODE&redirect_uri=https://yourapp.com/callback"
```

The response:

```json
{
  "access_token": "eyJhbGc...",
  "refresh_token": "def50200...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "invoice customer companyinformation"
}
```

Access tokens expire in one hour. Refresh tokens are valid for 45 days and are rotated on every use. When you refresh, store the new refresh token immediately and discard the old one:

```bash
curl -X POST https://apps.fortnox.se/oauth-v1/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN"
```

All subsequent API requests use the access token as a Bearer token:

```
Authorization: Bearer YOUR_ACCESS_TOKEN
```

## Scopes

[Fortnox scopes](https://www.fortnox.se/developer/guides-and-good-to-know/scopes) grant both read and write access per resource. There is no read-only variant. Requesting `invoice` gives write access to invoices, even if your use case is read-only sync. Be explicit in your consent screen about what write permissions you're granting.

Common scopes: `invoice`, `supplierinvoice`, `customer`, `supplier`, `payment`, `bookkeeping`, `companyinformation`, `salary`.

One planning note: scopes cannot be silently added to existing connections. If you need to expand scope after users have connected, they must reactivate. Get this right before go-live.

## The invoice API

Invoices are the core of most Fortnox integrations. The invoice endpoint is at `https://api.fortnox.se/3/invoices`.

### List invoices

A GET to the list endpoint returns a summary object per invoice, not the full record. This is by design. Here's what a list response looks like:

```bash
curl https://api.fortnox.se/3/invoices?limit=10&filter=unpaid \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```json
{
  "MetaInformation": {
    "@TotalResources": 142,
    "@TotalPages": 15,
    "@CurrentPage": 1
  },
  "Invoices": [
    {
      "@url": "https://api.fortnox.se/3/invoices/204",
      "Balance": "5000",
      "CustomerName": "Acme AB",
      "CustomerNumber": "100",
      "DocumentNumber": "204",
      "DueDate": "2025-06-15",
      "InvoiceDate": "2025-05-15",
      "Total": "5000"
    }
  ]
}
```

Notice what's missing: line items, tax codes, payment terms, address fields. To get the full invoice, you need a second call:

```bash
curl https://api.fortnox.se/3/invoices/204 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```json
{
  "Invoice": {
    "@url": "https://api.fortnox.se/3/invoices/204",
    "Address1": "Industrivägen 1",
    "Balance": "5000",
    "CustomerName": "Acme AB",
    "CustomerNumber": "100",
    "DocumentNumber": "204",
    "DueDate": "2025-06-15",
    "InvoiceDate": "2025-05-15",
    "InvoiceRows": [
      {
        "ArticleNumber": "ART-001",
        "Description": "Consulting services",
        "DeliveredQuantity": "10.00",
        "Price": "500",
        "Total": "5000"
      }
    ],
    "Total": "5000",
    "VAT": "1250",
    "VATIncluded": false
  }
}
```

This two-call pattern applies to most list endpoints. For any sync that needs complete data, your request volume doubles.

### Create an invoice

```bash
curl -X POST https://api.fortnox.se/3/invoices \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Invoice": {
      "CustomerNumber": "100",
      "InvoiceDate": "2025-05-01",
      "DueDate": "2025-05-30",
      "InvoiceRows": [
        {
          "ArticleNumber": "ART-001",
          "DeliveredQuantity": "5.00",
          "Price": "1000"
        }
      ]
    }
  }'
```

The customer (`CustomerNumber`) must already exist in Fortnox. If you're creating invoices for new customers, create the customer record first via `POST /3/customers`.

### Record a payment

Once an invoice is paid, mark it with an invoice payment:

```bash
curl -X POST https://api.fortnox.se/3/invoicepayments \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "InvoicePayment": {
      "InvoiceNumber": "204",
      "Amount": 5000,
      "PaymentDate": "2025-05-28",
      "ModeOfPaymentAccount": "1930"
    }
  }'
```

`ModeOfPaymentAccount` is the bank account number in Fortnox's chart of accounts where the payment lands.

## Pagination

The [Fortnox API pagination](https://www.fortnox.se/developer/guides-and-good-to-know/parameters) uses `limit` (default 100, max 500) and `offset` parameters. `MetaInformation` in list responses tells you total pages and current position:

```bash
# First page
GET /3/invoices?limit=500&offset=0

# Second page
GET /3/invoices?limit=500&offset=500
```

The `@TotalResources` field gives you the total count. For a complete sync of 2,500 invoices at limit=500, that's 5 pages (5 list calls) plus one detail call per invoice (2,500 calls), totaling 2,505 requests.

## Rate limits

Fortnox enforces a limit of 25 requests per 5-second window, which equals 300 requests per minute. Exceeding this returns a 429 status. Given the two-call pattern, a full sync of 2,500 invoices requires 2,505 requests, which takes at minimum 8-9 minutes at max throughput even without any throttling.

Implement exponential backoff on 429 responses. Avoid running parallel sync loops against the same connection. For initial historical syncs, schedule them during off-peak hours.

## Error handling

Common HTTP status codes you'll encounter:

| Status | Meaning |
|--------|--------|
| 200 | Success |
| 400 | Bad request (missing required field, invalid value) |
| 401 | Unauthorized (expired or invalid token) |
| 403 | Forbidden (insufficient scope) |
| 404 | Resource not found |
| 429 | Rate limit exceeded |

Fortnox returns error details in the response body:

```json
{
  "ErrorInformation": {
    "Error": 2000552,
    "Message": "Customer not found",
    "Code": 404
  }
}
```

Always check `ErrorInformation` in non-2xx responses.

## Webhooks

Fortnox supports webhooks natively for customers and invoices. For most other objects (supplier invoices, vouchers, payments, accounts), there's no native webhook. If your integration needs to react to changes across the full accounting object model, you'll need a polling layer for the gaps.

## The Fortnox Marketplace

If you want to distribute your integration to Fortnox users, publishing on the Fortnox Marketplace is the route. The process involves submitting your integration for review, providing a security whitepaper, and meeting Fortnox's technical requirements. Integrations can be kept hidden for private use while still using your Client ID for direct activation, which is useful during testing.

Marketplace pricing can be handled by Fortnox directly (they invoice your customers and handle revenue sharing) or by redirecting users to your own website for billing.

## Direct integration vs. a unified API

Building directly against Fortnox makes sense when Fortnox is the only accounting platform you need. The documentation is solid, the REST structure is predictable, and the OAuth 2.0 implementation is standard enough that most of it won't surprise you.

The calculus shifts when Fortnox is one of several platforms on your roadmap. The two-call pattern, partial webhook support, all-or-nothing scopes, and the Swedish registration requirement all add up. If you're also integrating with [other European accounting platforms](https://www.apideck.com/integrations/accounting-coverage/europe) like Pennylane or SnelStart alongside Fortnox, maintaining each integration independently is a real ongoing commitment. Teams that take that route often find the second or third connector is when the maintenance overhead catches up.

Apideck's unified accounting API is designed for that scenario. You write once against a normalized data model for invoices, payments, customers, and ledger entries, and the platform handles the per-connector translation across 12+ accounting platforms. Fortnox is on the roadmap. You can [request Fortnox support](https://www.apideck.com/accounting-software/fortnox) or explore the existing connector coverage with a [30-day free trial](https://app.apideck.com/signup).

Complete guide to Fortnox API integration: OAuth 2.0 auth, invoice and payment endpoints with code examples, pagination, rate limits, and webhooks.

How to Integrate with the Fortnox API

At some point in a SaaS product's life, the integration list starts looking like a liability ledger.

Third-party API integration is the process of connecting your product to external services (accounting software, CRMs, HR systems, payment providers) through their published APIs. The first integration is straightforward enough. You read the docs, write the connector, handle error cases, ship it. The second is similar. By the time you're maintaining connections to eight or ten external APIs in production, the character of the work changes. What started as a feature has become a maintenance surface, and every integration you add extends that surface.

This is the part that rarely shows up in tutorials about 3rd party API integration.

## Why third-party API dependencies compound differently than you'd expect

Most third-party APIs follow versioning conventions that look responsible on paper. A provider ships v1, then v2, promises backward compatibility for some window, posts deprecation notices in a changelog. The reality for an engineering team maintaining integrations is more fragmented: a different notification channel per provider, breaking changes across response schemas with no shared structure, field renames that show up only after something breaks in production, and authentication requirement updates that sometimes arrive with minimal warning.

That's manageable for two or three integrations. Scale it to ten providers and the overhead stops being manageable as background work. The engineering cost of keeping each connector current doesn't vanish; it spreads across the team as recurring interruption. Every sprint has a tax line that shows up as "keep integrations working."

The versioning problem is worse than most teams anticipate because the failure mode is asymmetric. Building a new integration takes a defined amount of time. Maintaining an existing one is open-ended. You can't estimate how often a provider will push a breaking change, when they'll deprecate an endpoint, or whether their migration guide will be accurate. What you can estimate is that across ten providers, something will break several times a year.

When those providers include [webhook-heavy systems like accounting platforms](https://www.apideck.com/blog/webhook-vs-api-endpoint), schema changes don't just affect REST calls — they break event-driven flows that are harder to monitor and test.

## How custom API integration projects accumulate hidden costs

When companies build integrations in-house or contract out custom API integration services, they're typically solving a specific, time-bounded problem: connect system A to system B, handle the error states, ship it. The integration works. Six months later the upstream provider updates their API. Authentication requirements change. A webhook format is deprecated. The connector that was a completed feature becomes a support ticket.

This is how integration maintenance becomes a persistent overhead. Unlike new feature work, it doesn't produce compounding value. Every connector is a recurring commitment to monitoring provider changelogs and responding when something changes. When a provider rotates their OAuth implementation or changes pagination behavior, someone on your team absorbs that work.

The companies that run into trouble here usually aren't negligent. They built integrations as the product needed them, which is rational. The problem is that the maintenance burden of a ten-connector portfolio isn't proportional to a two-connector portfolio. At two connectors, the overhead is invisible. At ten, it's visible but defensible. At twenty, it's a material fraction of engineering capacity, and that capacity isn't building anything new.

The [real cost of custom API integration](https://www.apideck.com/blog/custom-api-integration) includes more than the initial build. It includes the monitoring, the re-auth work, the schema migrations, and the unplanned sprint interruptions every time a provider ships a breaking change. A related dynamic shows up in AI-assisted builds: [letting AI write your integrations](https://www.apideck.com/blog/top-pitfalls-of-letting-ai-build-your-integrations) creates connectors that work at build time but inherit all the same maintenance surface.

For companies evaluating [API integration services](https://www.apideck.com/blog/api-integration-services) to build on their behalf, the scope question is the same: who owns the connector once it's live, and how quickly can they respond when a provider changes something?

For companies offering custom API integration services to clients, the dynamic is more acute. Every client integration you build and hand off becomes a long-term support commitment if the client expects it to stay current. That's a scope question worth making explicit upfront.

## Where OpenAPI standardization helps and where it still falls short

[Apideck is a member of the OpenAPI Initiative](https://www.openapis.org/), the organization that maintains the [OpenAPI Specification](https://www.apideck.com/blog/introduction-to-openapi-specification). The spec is the most widely adopted standard for describing REST APIs in a machine-readable format: endpoints, schemas, request and response structures, authentication flows, versioning. When a provider publishes a well-maintained OpenAPI spec, their API becomes formally describable and diff-able.

This matters for third-party API integration because a significant share of integration fragility comes from undocumented or poorly communicated change. A provider updates an endpoint and the field rename is in a changelog entry nobody received. An OpenAPI-first provider reduces that surface considerably. The spec can be diffed between versions. Tooling can detect schema changes before they hit production. Breaking changes become explicit rather than discovered through runtime failures.

The limitation worth acknowledging: most providers in the accounting, CRM, and HRIS categories don't publish OpenAPI specs, and those that do maintain them at varying levels of accuracy. The spec is a standard for description, not a guarantee of adoption discipline. The OAI works to push for broader adoption across the ecosystem, and the direction is positive, but the current reality is still highly fragmented. Different authentication schemes, different pagination models, different error formats, different versioning philosophies. Teams building across multiple providers inherit all of that variation.

## The case for a unified layer in third-party API integration

The argument for a [unified API layer](https://www.apideck.com/blog/what-is-a-unified-api) follows from that fragmentation. Instead of maintaining N integrations where each speaks a different dialect, your application makes one call. The translation to each specific third-party API lives in the layer. When a provider changes their API, the connector in the layer absorbs that update. Your codebase stays unchanged.

The practical effect is that your integration surface stays constant as the number of providers grows. You don't add maintenance overhead for each new integration because you're not managing each provider relationship directly. When QuickBooks Online updates their API, or Xero changes how they handle pagination, the connector updates and you're not involved.

Apideck's unified API covers accounting, CRM, HRIS, and commerce categories across 200+ connectors. The testing, validation, and changelog monitoring for each provider lives with us. Companies using the platform get new integrations added to their roadmap without the corresponding maintenance cost per connector. That math becomes more favorable as the number of integrations grows.

The unified layer approach isn't always the right answer. For a product that needs one or two integrations and has no near-term plans to expand, building a connector directly is reasonable. The crossover point is roughly when the integration roadmap runs into double digits and the maintenance overhead starts showing up in sprint planning.

## Questions worth asking before you scope third-party API integration work

Before deciding how to approach third-party API integration, a few things are worth answering:

How many integrations does your product roadmap need over the next 12-18 months? If the number is more than six or seven, the maintenance math shifts.

What's the cost to users when an integration breaks? If downstream financial reporting, payroll processing, or revenue operations depends on an integration staying current, the risk profile of a custom approach is different than for a supplementary data sync.

Does your team have capacity to monitor provider changelogs and respond quickly? The delay between a breaking change and a fix has a cost that scales with how critical the integration is.

Are you building integrations for clients, or for your own product? Client integrations carry implicit SLAs around uptime and currency that can surprise teams who didn't price that in.

---

The third-party API ecosystem is not converging toward simplicity. More providers means more variation in authentication, versioning strategy, and schema conventions. The companies that handle this well tend to make a deliberate decision early: invest in infrastructure to manage integrations as a product, with dedicated capacity for monitoring and maintenance, or find a layer that handles the variation for them. The teams that don't make that decision eventually find themselves with a growing connector list, an expanding maintenance backlog, and diminishing capacity to ship anything else.

---

*Apideck is a member of the [OpenAPI Initiative](https://www.openapis.org/) and provides a unified API for accounting, CRM, HRIS, and commerce integrations. You can explore the connector catalog and start a free 30-day trial at [apideck.com](https://www.apideck.com).*

Managing third-party API integration at scale means more than connecting to an endpoint. Here's what the versioning and dependency problem actually looks like in production.

Third-Party API Integration: The Dependency Problem at Scale

When a customer reports that their invoices stopped syncing with QuickBooks three days ago, you have two options. If you have good logs, you look up the failed request at 2:47 AM on Tuesday and have a root cause in three minutes. Without them, you're adding `console.log` statements to a production codebase and asking the customer to re-authenticate while hoping the issue reappears.

That gap is what API logging actually solves.

API logs matter whether you're building an API or consuming one. If you're building your own service, logs tell you which endpoints are slow and what the traffic looked like before an outage. If your product integrates with third-party APIs, like accounting platforms and CRMs, the picture is more complex: you're not just logging your own traffic, you're capturing every request your code sends to downstream services and every response that comes back. Both cases matter. The second one is harder, and most guides don't cover it.

## What is an API log?

An API log is a structured record of every request sent to and response received from an API. When your application calls an external service, the request travels over HTTP: it carries a method (GET, POST, etc.) and a target URL, along with request headers and usually a body. The API sends back a status code and a response body. An API log captures all of this for a single transaction, timestamped, so you can reconstruct exactly what happened and when.

Here's what a minimal API log entry looks like in practice:

```json
{
  "timestamp": "2025-04-15T09:42:17Z",
  "method": "POST",
  "url": "https://api.xero.com/api.xro/2.0/Invoices",
  "request": {
    "headers": {
      "Authorization": "Bearer [redacted]",
      "Content-Type": "application/json"
    },
    "body": { "Type": "ACCREC", "Contact": { "ContactID": "abc123" } }
  },
  "response": {
    "status": 422,
    "body": {
      "Elements": [{
        "ValidationErrors": [{ "Message": "Account code is required" }]
      }]
    }
  },
  "latency_ms": 312,
  "consumer_id": "tenant_88f3k",
  "service": "xero"
}
```

That 422 from Xero is invisible if you're only storing status codes. With the response body logged, you know exactly what field is missing and which customer hit the problem.

## How API logs are generated

API logs are created at the point where an HTTP request is made or received. For APIs you own, this typically happens through middleware: a function that runs after your request handler and captures the request and response before writing a structured record to your log store. Express middleware and Django's request logging both work this way, as do serverless environments that intercept the invocation context.

For APIs you consume, log generation is your responsibility. When your code makes an outbound request to QuickBooks or Xero, nothing automatically records it. You either wrap the HTTP call in your own logging layer, or route traffic through a proxy that captures it automatically. The log store is a separate concern: it might be a cloud service like Datadog or a self-hosted solution like the ELK stack.

One common approach for integration teams is a centralized proxy layer that sits between your application and all downstream API calls. Every outbound request passes through it and is logged before being forwarded to the target API. This gives you a single place to capture logs across every integration without instrumenting each one individually.

## What a useful API log entry contains

An API log is a record of an API interaction. What matters is which fields make an entry actionable rather than just archival.

At minimum, a log entry should capture:

- Timestamp with timezone (UTC throughout)
- HTTP method and full endpoint URL
- Request headers, minus sensitive credentials
- Request body, or a reference to it if you're not storing payloads in logs
- Response status code
- Response body
- Latency (time from request sent to response received)
- A correlation ID that ties the log to a specific customer and job

That last field is where most teams under-invest. A 429 from Xero means something very different if you're reading it alongside the other 48 requests from the same customer sync job. Without a correlation ID, you're reading isolated sentences from a story you can't follow.

For integration teams specifically, two additional fields often go missing: the downstream service name and the tenant or customer identifier. When you're syncing data for 200 customers across five accounting platforms, a log entry that says `GET /invoices` with a 200 response tells you almost nothing. A log entry that says `GET /invoices` on `xero` for customer `tenant_88f3k` with a 200 response in 340ms is one you can act on.

## Types of API logs

Not every log entry serves the same purpose. Teams dealing with complex integration infrastructure typically work with four categories:

Access logs record every request and response regardless of outcome. They're your audit trail: proof that specific requests were made and what the API returned. Compliance frameworks like SOC 2 and GDPR that require demonstrating what data moved where are answered by access logs.

Error logs filter for requests that resulted in failures: 4xx and 5xx status codes, along with timeouts and dropped connections. They're higher-signal than access logs for debugging, but you need access logs alongside them to understand the volume of failed requests relative to total traffic.

Performance logs focus on latency and throughput. They capture response times and sync durations. For integration teams running background sync jobs, a performance log that shows a customer's sync taking 45 seconds when it used to take 4 seconds is early warning of a rate limit or downstream API degradation.

Security logs track authentication events. When a token is issued or later revoked, that event should appear in a log with a timestamp and customer identifier. In an integration context, this is where you capture OAuth token revocations and failed signature validations.

Most modern logging setups capture all four in the same log stream and tag entries by type, rather than routing them to separate systems. That approach makes it easier to correlate events across categories when debugging a complex issue.

## Why integration logging is different

If you're building your own REST API, logging is primarily an inward-looking activity. You own the endpoints and the response formats. Debugging means finding the right log line and reading the stack trace.

[Third-party API integrations](https://www.apideck.com/blog/what-is-api-integration) flip this model. The downstream API belongs to someone else. Its error formats and rate limit behavior are outside your control, and deprecation schedules are decided by the platform vendor. Your logs have to capture enough context about the downstream system's behavior to diagnose problems you didn't anticipate and can't reproduce locally.

Three categories of integration-specific logging are worth calling out:

Error body capture. QuickBooks returns validation errors as a JSON object with a `Fault` property. Xero returns them as an array of `Elements` with nested `ValidationErrors`. Salesforce wraps them in an `errorCode` field. If your logs store the raw response body, you can debug any of these. If they only store HTTP status codes, a 422 from QuickBooks and a 422 from Xero look identical even though they mean completely different things. Log the raw downstream response.

Rate limit events. According to a 2024 Postman survey, 66% of developers rely on API gateway logs for debugging production issues, and rate limits are one of the most common production issues in integration work. QuickBooks allows 500 requests per minute per tenant, and Xero allows 60. NetSuite takes a different approach, limiting concurrent requests per integration rather than applying a per-minute cap. When you hit these limits, you get a 429. When you log the 429 alongside the tenant identifier and the request volume over the preceding window, you can see whether the problem is your retry logic or a burst from a large customer. Without that context, you're guessing.

Token refresh failures. OAuth tokens expire. Refresh tokens get revoked when a customer changes their accounting platform password. Connections break silently when the user who authorized the integration leaves the company. These are not errors your application generates; they're events that happen upstream. Logging every token refresh attempt alongside the outcome and the customer identifier is what allows your support team to tell a customer "your Xero connection was revoked on March 15th" rather than "we're not sure why your data stopped syncing."

## Per-tenant visibility

[Accounting integrations](https://www.apideck.com/blog/the-complete-guide-to-accounting-api-integrations-for-fintech) are multi-tenant by definition. Your product serves dozens or hundreds of customers, each with their own platform connection. The logs that help you debug one customer's broken sync will be useless if they're mixed with logs from every other customer without clean separation.

The practical requirement is per-tenant filtering. You should be able to enter a customer ID in your logging interface and see every API call that customer's integration has made, in chronological order, with status codes and latency. This sounds obvious. In practice, teams skip the tenant identifier in early versions and spend weeks retrofitting it after the first serious support incident.

Apideck's Vault exposes a paginated log of request logs scoped to both application and consumer. That scoping lets you isolate a specific customer's traffic in seconds rather than filtering through application-wide logs, which matters when a customer calls support at 6 PM and needs an answer before morning.

## What to actually watch for

Raw logs are data. The patterns in logs are information. Once you have reasonable coverage, the most actionable signals are error rate by connector and latency trends.

If 3% of requests to QuickBooks are returning 500 errors this morning and your baseline is under 0.1%, that's a platform incident you should know about before customers do. Tracking error rates per downstream service catches this faster than tracking them across your entire integration layer. Similarly, an endpoint that usually responds in 200ms and is now responding in 4 seconds is not broken, but it's about to cause timeouts for customers with large sync jobs. Latency rising before errors appear is a signal you can act on before anyone calls support.

The other pattern worth monitoring is repeated identical failures. A single 404 on a customer invoice endpoint might mean a deleted record. A hundred identical 404s on the same endpoint for the same customer within an hour is almost certainly a configuration problem or a stale resource reference. That pattern is only visible if you're looking at sequences, not individual lines.

Auth error clustering is worth watching separately. When multiple customers lose their connections within the same hour, that often signals a platform change: a Xero OAuth scope update or a new QuickBooks credential rotation requirement. Catching this in your logs before customers report it gives you time to communicate first.

## API logging best practices

A few principles separate useful logs from a log file nobody reads:

Log at the boundary. Capture the raw request and response at the point where your code touches the external API, not after you've processed or transformed the data. Transformation loses information. Raw logs preserve the full context you need when something unexpected happens.

Redact credentials, not content. Strip `Authorization` headers and any field that carries secrets. Keep everything else, including request bodies. The instinct to scrub sensitive-looking fields often goes too far and removes exactly the data you'll need to debug a validation error two weeks later.

Use structured formats. JSON logs are queryable. Plain text logs require parsing. If you're shipping logs to a centralized system like Datadog or the ELK stack, structured JSON lets you filter by `status_code:422` or `consumer_id:tenant_88f3k` without writing regex.

Set retention that matches your support cycle. If your average support ticket is resolved within 30 days, 90-day log retention gives you headroom. If you're in a regulated industry and customers can file complaints months later, your compliance team sets this number.

Don't sample in development or staging. Sampling is a valid cost-reduction strategy for high-volume production APIs. For integration work, where issues often appear once and vanish, sampled logs miss the one request you needed to see.

## Tooling

For teams building their own integration infrastructure, Datadog handles log aggregation well at scale. Its strength is correlating log data with APM traces, which is useful if your integration runs across complex infrastructure. The ELK stack gives you more query flexibility if you're willing to manage the operational overhead. Moesif is purpose-built for API logging and adds product analytics on top of raw log data.

For teams using a unified API platform, the logging layer is typically included. Apideck logs every request and response across all connectors, including webhooks, and surfaces per-customer, per-connector visibility through the Vault interface. Your support team can diagnose most integration issues without escalating to engineering, which means faster resolutions and customers who don't wait 48 hours for a root cause.

## The underlying decision

Good API logging is an investment that returns value in proportion to how many integrations you support and how many customers are running them. For a product with two integrations and ten customers, a structured log pipeline and Datadog is probably enough. For a product with fifteen integrations and hundreds of customers, building and maintaining your own logging infrastructure starts to compete with building the product itself.

The [accounting integration guide](https://www.apideck.com/blog/accounting-integration) covers the broader reliability requirements for financial integrations, including sync strategies and rate limit management. If you're building on top of multiple accounting platforms, the logging decisions you make early will determine whether your support team can work independently or whether every customer escalation needs an engineer at a keyboard.

If integration observability is becoming a bottleneck, [Apideck API Logs](https://www.apideck.com/api-logs) gives you per-tenant logging and error alerting across 200+ connectors, with no separate logging infrastructure to manage. Start a free 30-day trial and see what's actually happening inside your integrations.

What developers and integration teams need to know about API logs: what fields to capture, the types of logs, best practices, and how to use them in production.

API Logs: A Complete Guide

A custom API integration is a direct connection between two software systems, built and maintained by your engineering team rather than sourced from a third-party connector or platform. Your team handles the authentication flow, rate limiting, error handling, data mapping, and ongoing maintenance as the upstream API changes.

For a single integration with well-defined requirements, building custom is often the right call. The economics shift when you need more than one, when the upstream API changes frequently, or when your customers use multiple different systems that all need to connect to your product.

Accounting integrations sit at the hard end of this spectrum. The data models are inconsistent across providers, the APIs are repricing, and the maintenance tail is longer than most teams budget for. Here's what that actually looks like.

A custom API integration for QuickBooks sounds like a three-week project. An engineer reads the docs, sets up OAuth 2.0, maps a handful of endpoints for invoices and payments, and ships it. The PM marks the roadmap item done.

Six months later, that integration is the source of two open support tickets, one on-call incident, and a recurring Tuesday morning task where someone manually reruns a sync that failed silently overnight.

This is the pattern. Not because the engineers were careless, but because accounting API integrations have a maintenance profile that doesn't show up in sprint estimates. And as AI features move from roadmap to requirement, the cost of getting it wrong has gone up.

## What it actually takes to build a QuickBooks integration

The QuickBooks Online API is well-documented. Intuit has invested in developer tooling, and the REST endpoints cover the core accounting entities: customers, invoices, payments, journal entries, and chart of accounts. For straightforward read-write operations, a capable engineer can have something working in three to four weeks.

The problems start after launch.

OAuth access tokens expire after 60 minutes. Refresh tokens are valid for 101 days, but each token can only be used once, and if two threads race to refresh the same token, one of them fails. You need atomic storage and concurrency locks, plus a re-authentication UX for when a customer's credentials expire completely. Most teams build this correctly once they've been burned by it.

![QuickBooks REST API docs](//images.ctfassets.net/d6o5ai4eeewt/TlcfwWQFqfAta9AS4O5Wm/ee20116fdd77f31eac944301e157bee0/Screenshot_2026-04-28_at_21.32.40.png)

Rate limits are 500 requests per minute per company, with a hard cap of 10 concurrent requests. For a platform with 500 customers running background syncs, that ceiling fills up quickly. You need per-company throttling, backoff logic, and queue management.

In July 2025, Intuit introduced the App Partner Program, which changed the pricing model for data retrieval. GET operations are now metered. The free Builder tier gives you 500,000 CorePlus read operations per month before requests are blocked entirely. Paid tiers run from $300 to $4,500 per month, with overage fees on top. Write operations remain free, but if your product does any meaningful data pull for reconciliation, reporting, or sync verification, you will hit the free tier ceiling as your customer base grows. Your Intuit API bill scales with customer acquisition, not with the value you're delivering.

That Intuit repriced in 2025 is now a variable to model before committing to a native build. As we noted in our [overview of QuickBooks API pricing](https://www.apideck.com/blog/quickbooks-api-pricing-and-the-intuit-app-partner-program), Xero made a parallel move in the same period, adding connection-based pricing tiers and premium-gating key endpoints like Journals. Two of the three most common accounting integration targets repriced within a year of each other.

## What breaks in accounting specifically

Generic discussions of custom API integration focus on authentication and rate limits. Accounting integrations have a deeper failure mode: the data model.

Every accounting system has a different structure for the chart of accounts. In QuickBooks Online, accounts are flat records with a type and subtype. In Xero, the structure is similar but the type taxonomy differs. In NetSuite, the chart of accounts is hierarchical, and multi-subsidiary setups add another dimension. A field called "account" in one system does not map cleanly to "account" in another. The differences matter when your platform does anything beyond simple display: pushing journal entries, reconciling transactions, or reporting across a customer's books.

Discount handling in QuickBooks Desktop illustrates the problem concretely. Discounts appear as separate line items that automatically apply to the line above them, not as a property on the line itself. If you're summing invoice lines to calculate a total, you will get the wrong number unless you account for this. The API won't warn you. As the [accounting for developers guide](https://www.apideck.com/blog/accounting-for-developers) documents, a developer on the Apideck team once spent three days debugging why invoice totals in QuickBooks Online didn't match what the connector was sending. The amounts were correct. The problem was chart of accounts mapping defaulting to an expense account instead of a revenue account. Every invoice landed on the wrong side of the books.

Tax handling varies by region. The US version of QuickBooks does not support adding tax to purchases; the UK and Canadian versions do. An integration that works correctly for your US customers will produce errors or incorrect data for customers in other markets.

These are not edge cases. They're the reason accounting integrations have longer tails than CRM or HRIS integrations. And they're the reason teams who try to build a general-purpose [accounting integration](https://www.apideck.com/blog/accounting-integration) often end up with four separate codepaths masquerading as one.

## The second integration problem

Truto's 2026 analysis of QuickBooks builds describes the pattern: the initial integration takes three to four weeks, but within six to twelve months, customers start asking for Xero. Then NetSuite. Then Sage Intacct.

At that point, you're not maintaining one custom API integration. You're maintaining three, each with its own token lifecycle, rate limit strategy, and data model quirks. The second build is faster than the first because you've solved authentication. It's still slow because every accounting system models the general ledger differently, and your internal data model needs to handle all of them.

Invoice2go by BILL worked through exactly this before switching to Apideck's Unified Accounting API. Rather than building and maintaining separate integrations for each accounting platform, they connected once and scaled to support major systems across their 220,000+ customers. The ability to add a new accounting connector without a full build cycle changed the economics of their integration roadmap.

## What AI does to this calculation

The AI in accounting category is moving fast. As documented in the [AI in accounting overview](https://www.apideck.com/blog/ai-in-accounting), well-funded startups including Digits and Mimo are rebuilding the accounting stack from the ledger up, with AI as the architecture rather than a feature. Datarails CEO Didi Gurfinkel launched FinanceOS, described as a governed data layer connecting to 400+ sources.

What this means for teams building custom accounting integrations: AI features are not optional extras anymore. Finance teams expect budget forecasting, anomaly detection, and automated categorization. Those features need clean, structured financial data.

Custom integrations that return raw QuickBooks schemas make AI features harder to build. When an AI model ingests transaction data from QuickBooks for one customer and Xero data for another, the inconsistency between schemas creates a data preparation problem that sits upstream of every AI call. You end up building transformation logic on top of integration logic, doubling the maintenance surface.

A normalized accounting API changes this. When account records, invoice objects, and journal entries follow a consistent schema regardless of the source system, your AI features work across all accounting platforms without per-provider handling. Platforms building [lending decisions](https://www.apideck.com/blog/using-accounting-apis-for-smart-lending-decisions) on top of accounting data, or FP&A tools pulling [financial statements](https://www.apideck.com/blog/financial-statement-api) across platforms, need this normalization as a prerequisite. The AI layer is only as reliable as the data layer beneath it.

The same logic extends to agentic workflows. AI agents pushing journal entries or reconciling transactions need a stable, predictable interface. Provider-specific schemas, inconsistent field names, and per-region quirks all create failure points that agents don't recover from gracefully.

## What normalization actually gives you

A unified accounting API solves a different problem than "we don't want to write OAuth code." The OAuth code is the easy part. What a unified API provides is a consistent data model across accounting systems.

When a unified accounting API normalizes account records from different systems into a single Account object, your platform writes its sync logic once. When a customer uses QuickBooks Online in the US and another uses Xero in the UK, the response structure is the same. When Intuit changes how it handles a specific endpoint, that change is absorbed at the connector level.

Accounting APIs are not stable. Intuit repriced in 2025. QuickBooks added Premium API endpoints exclusive to higher-tier partners in July 2025. NetSuite releases updates on a fixed schedule that regularly breaks integrations relying on undocumented fields. Absorbing those changes across 35+ accounting connectors is a full-time job. At minimum, it's one engineer dedicated to integration maintenance, and that engineer's time is worth more on core product.

The build-versus-buy framing for custom API integrations usually focuses on initial build time. The more accurate frame is total cost of ownership: engineering hours per month per connector, multiplied by the number of accounting systems your customers use, plus the cost of every AI feature that breaks because the data model under it isn't consistent. For most platforms targeting SMB or mid-market customers, that number justifies the alternative before the third integration is on the roadmap.

Building a custom API integration for QuickBooks costs more than the initial sprint. Here's the real engineering cost: OAuth complexity, Intuit's 2025 pricing changes, data model gaps, and why AI features demand normalization from day one.

Custom API Integration for Accounting: What It Actually Costs to Build Your Own

Most engineering teams underestimate how much a financial API integration actually involves until they're three months in, spending most of their time on OAuth token refresh logic and webhook debugging rather than product features. The "integration" itself is rarely the problem. The maintenance is.

Financial API integrations sit at the center of almost every modern SaaS product that touches money: expense tools, embedded lending platforms, vertical SaaS with billing workflows, payroll systems.

## What a financial API integration actually is

An API integration connects two software systems so they can exchange data or trigger actions in each other. A financial API integration does that specifically with financial systems: banks, accounting platforms, payment processors, lending data providers, and payroll systems.

The term gets used to mean different things depending on context. For some teams it refers to open banking: a user grants permission for an app to access their bank account data. For others it means accounting software integration or payment processing. These categories have different auth requirements and compliance obligations. Treating them as interchangeable is how projects get scoped wrong.

## Types of financial API integration

There are five main categories worth understanding. Each involves a different technical profile and different compliance exposure.

Banking and account data integrations give your application access to a user's bank account: transaction history and balance data, sometimes payment initiation depending on the provider. Plaid is the dominant aggregator in the US, connecting to 12,000+ financial institutions through a single API. In Europe, open banking runs on PSD2-mandated bank APIs, though coverage and quality vary by country. The [Open Banking Tracker](https://www.openbankingtracker.com) tracks which jurisdictions have active open banking regulations and how many institutions are covered in each market. This category is what most people mean by "open banking." For a technical breakdown of how banks connect to accounting and ERP systems, see [Bank API Integration](https://www.apideck.com/blog/bank-api-integration).

Accounting and ERP integrations connect to general ledger systems: QuickBooks and Xero on the SMB end, NetSuite and Sage further up the market. These are the integrations that matter most for B2B software that touches money movement: expense management, embedded lending, payroll, procurement, or vertical SaaS that needs financial records in its core workflow. They're also central to financial close automation, where syncing transactions and journal entries across systems is what makes month-end reconciliation fast or slow. This is the category where complexity is most underestimated, and where coverage matters most for B2B SaaS. For a deeper look at the accounting layer, see [The Complete Guide to Accounting API Integrations for Fintech](https://www.apideck.com/blog/the-complete-guide-to-accounting-api-integrations-for-fintech). For the bank-to-ERP connectivity angle specifically, see [ERP Banking: The Shift From Portal to Platform](https://www.apideck.com/blog/erp-banking).

Payment APIs handle money movement at the transaction level: charging cards and initiating bank transfers or contractor payouts. Stripe is the most widely used in SaaS. Adyen is common in enterprise and marketplace contexts. Payment APIs are generally the most standardized category and the least painful to integrate.

Credit and income verification integrations serve lenders, landlords, and any company offering financial products on credit. These pull data from payroll providers or bank transaction history to produce a verified income or creditworthiness assessment. Plaid Check and Pinwheel both operate in this space, among others. For a detailed look at how lending platforms use banking and accounting data together, see [Embedded Lending](https://www.apideck.com/blog/embedded-lending-revenue-financing-banking-accounting-commerce-data).

KYC, AML, and identity integrations connect to identity verification services and AML watchlist screening. For most SaaS companies, this category only becomes relevant when you're handling money movement on behalf of users, not just aggregating data.

## How financial API integrations work

The mechanics depend on the type of integration, but there are three common patterns.

The simplest is a direct connection (often called a partner API) between your application and one financial system. You get API credentials from the provider, implement the auth flow, call the endpoints you need, and handle the responses. This is what most teams start with when they integrate QuickBooks or a single bank.

More common for banking use cases is the aggregator model: instead of connecting directly to each financial institution (which would mean building hundreds of separate integrations), you connect once to an aggregator like Plaid that has already built those connections. Your users authenticate through the aggregator's hosted flow (Plaid Link, for example), and you get back a token you can use to retrieve their data via the aggregator's normalized API. This model is what makes it practical to support any bank your users might have.

A third pattern, increasingly relevant for accounting and ERP integrations, is the unified API model. This works like the aggregator model but across different types of software rather than different banks. Instead of integrating separately with QuickBooks, Xero, and a handful of other accounting systems, you connect once to a unified API that normalizes the data model across all of them. The normalized layer handles field mapping and entity translation across different auth models, and you build to a single consistent interface.

Underneath any of these patterns, the actual data exchange uses REST endpoints authenticated via OAuth 2.0, with webhooks providing real-time change notifications. Some integrations also require batch sync jobs for historical data pulls.

## Why financial integrations cost more than the initial build

The first working version of a financial API integration is not the expensive part. Calling a QuickBooks endpoint and returning a list of invoices takes a few days. The cost accumulates differently.

Every financial system has its own data model. QuickBooks organizes data around accounts and customers, each with its own sub-entity structure. Xero uses contacts and tracking categories as its primary organizing concepts. NetSuite has a multi-entity model built around subsidiaries. When you're integrating one system, you build to that model. When you need to support five systems, you're maintaining five separate models and all the transformation logic between them and yours.

Authentication is another compounding cost. Most accounting APIs use OAuth 2.0, but token lifetimes and refresh mechanics differ considerably. Xero access tokens expire in 30 minutes. QuickBooks Online tokens last longer but the refresh flow has edge cases that surface in production. Banks have their own auth requirements, and some still use credential-based flows that require handling session tokens differently.

Webhooks add another layer. Financial data changes constantly, and polling is expensive. Most modern financial APIs offer webhooks, but the event schemas are inconsistent, delivery guarantees vary, and you need idempotency handling for duplicate events. NetSuite's SuiteScript webhooks behave differently from QuickBooks' change data capture. Xero's model differs from both.

Then there's versioning. QuickBooks Online has gone through multiple major API versions and deprecated older ones with limited migration windows. Xero has made breaking changes in the years since its launch. Every API version migration means regression testing across your entire integration surface. If you're maintaining six or seven accounting integrations, this becomes a recurring event.

None of this is insurmountable, but it's ongoing. A team that builds a QuickBooks integration in Q1 will be maintaining it for years. Upstream API changes require regression testing each time. Auth edge cases and field mapping bugs appear at unpredictable intervals, often after a customer changes their chart of accounts or upgrades their accounting software.

This is the part that usually isn't in the build estimate.

## Security and compliance requirements

Financial data is a high-value target, and the compliance requirements reflect that.

If you're handling payment card data, PCI DSS applies. Most teams avoid scope by using payment APIs that handle card data on their behalf (Stripe, for example, issues tokens so your servers never touch raw card numbers), but you still need to verify your scope and maintain compliance documentation.

If you're accessing bank account data, data residency requirements may apply depending on where your users are. European users' financial data falls under GDPR, which imposes restrictions on storage location and data transfer outside the EU. In the UK, the FCA regulates third-party access to open banking data; Section 1033 of the Dodd-Frank Act is establishing similar requirements in the US. The [Open Banking Tracker](https://www.openbankingtracker.com) is a useful reference for understanding the regulatory status across different markets, covering 80+ global regulations.

OAuth 2.0 with PKCE is the current standard for user authorization in financial APIs. Avoid any provider that still supports credential stuffing flows (where your app collects the user's bank login). Beyond the security risk, regulators in most jurisdictions are moving to require explicit API-based data sharing rather than screen scraping.

For accounting integrations specifically, the main exposure is around data integrity. Write access to a customer's general ledger is a significant permission. A bug that creates duplicate invoices or corrupts journal entries is a support escalation that damages the relationship. Sandbox environments and thorough integration testing before production access are non-negotiable.

## How to choose a financial API integration approach

A few factors determine whether to build native integrations or rely on an abstraction layer.

Start with scope. If you need one accounting integration and have no plans to expand, building native is straightforward. If you're a vertical SaaS company that needs to support whatever accounting system your customers use, the maintenance cost of building native for each one compounds quickly. For how this plays out in practice, see [Embedded Finance for Vertical SaaS](https://www.apideck.com/blog/embedded-finance-vertical-saas).

Then consider who maintains it. Integration work doesn't end at launch. If your team doesn't have dedicated capacity for ongoing maintenance, integrations degrade as APIs change. This is a real cost that rarely appears in the initial build estimate.

The direction of data flow matters too. Read-only integrations are substantially simpler than write integrations. Write integrations require understanding the target system's validation rules, handling partial failures, and building reconciliation logic. The complexity goes up considerably.

For accounting and ERP specifically, a unified API approach is worth evaluating. Apideck, for example, covers 200+ connectors across accounting, HRIS, CRM, and commerce categories through a single API. For the accounting category, it normalizes entities like ledger accounts, invoices, bill payments, and journal entries across systems that model them differently. A field like `AccountRef` in QuickBooks maps to the corresponding concept in Xero or NetSuite without your application needing to know about the difference.

The trade-off is coverage depth. A unified API gives solid coverage of the most common fields and operations. If you need deeply system-specific features (NetSuite's advanced inventory module, or Xero's tracking categories at a granular level), you may hit the limits of the normalized model and need native calls for those cases. But that edge represents a small fraction of most integration surfaces.

For banking and account data, the aggregator model (Plaid in the US) makes sense for most use cases. Building direct connections to individual banks isn't practical for most companies.

For payments, building native to Stripe or Adyen makes sense given the maturity and stability of those APIs.

The integration layer that most teams underinvest in, and where the build vs. buy argument is clearest, is accounting. After Visa's planned acquisition of [Plaid](https://www.openbankingtracker.com/api-aggregators/plaid) collapsed in early 2021, Plaid raised at a $13.4 billion valuation a few months later. That pricing was partly a signal of how much companies are willing to pay to avoid building and maintaining bank connectivity themselves. The same logic applies to accounting integrations, which are often more complex and more numerous than their banking counterparts.

The companies that build native accounting integrations and maintain them well tend to be large enough to afford dedicated integration teams or focused enough on a single system that the investment pays off. For everyone else, a layer of abstraction is the faster path.

A practical guide to financial API integration: types, how they work, what they cost to maintain, and how to choose between native builds, aggregators, and unified APIs.

Financial API Integration: What It Is, How It Works, and What It Actually Costs to Get Right

When you make an API call, the status code in the response is the first thing your code should read. That three-digit number tells you whether to parse the response or fix what you sent. Most applications handle this badly: they check for 200, maybe catch a generic exception, and log everything else as "API error." That works until it doesn't, which is usually the moment a customer's data is silently wrong.

This guide covers the codes you'll actually encounter when building accounting and financial integrations, and the error-handling patterns that make the difference between applications that degrade gracefully and ones that corrupt state.

A minimal response handler looks like this:

```javascript
async function apiRequest(url, options) {
  const res = await fetch(url, options);

  if (res.ok) return res.json();

  const body = await res.json().catch(() => ({}));

  switch (res.status) {
    case 400: throw new BadRequestError(body);
    case 401: throw new UnauthorizedError(body);
    case 403: throw new ForbiddenError(body);
    case 404: throw new NotFoundError(body);
    case 409: throw new ConflictError(body);
    case 422: throw new ValidationError(body);
    case 429: throw new RateLimitError(res.headers, body);
    default:  throw new ApiError(res.status, body);
  }
}
```

The rest of this guide explains what each of those branches means and how to handle it correctly.

## The 2xx range: success has more than one shape

200 OK is the simple case. The request worked, the response body contains what you asked for. For GET requests that means data; for PATCH or PUT, it typically means a representation of the updated resource.

201 Created means the request worked and a new resource exists on the server. POST requests to create invoices or transactions should return 201, not 200. If you're using a provider that returns 200 for POST requests, that's a design choice, not an error, but it means you can't distinguish creation from retrieval by status code alone.

202 Accepted is the one developers most often mishandle. The server got your request and will process it, but it hasn't finished yet. Sync operations for accounting platforms frequently use this pattern: you kick off a sync, get a 202, and then poll a status endpoint to know when it's complete. Read the response body for a job ID, store it, and poll at a sensible interval with a maximum retry count. Polling every 100ms until you get a result is not a sensible interval.

```javascript
async function triggerSyncAndWait(connectionId) {
  // Kick off the sync
  const { jobId } = await apideck.accounting.triggerSync(connectionId);

  // Poll until complete or max attempts reached
  const MAX_POLLS = 20;
  const POLL_INTERVAL_MS = 3000;

  for (let i = 0; i < MAX_POLLS; i++) {
    await sleep(POLL_INTERVAL_MS);
    const { status } = await apideck.accounting.getSyncStatus(jobId);
    if (status === 'complete') return;
    if (status === 'failed') throw new Error(`Sync ${jobId} failed`);
  }

  throw new Error(`Sync ${jobId} did not complete after ${MAX_POLLS} polls`);
}
```

## The 3xx range: redirects you shouldn't ignore

301 Moved Permanently and 302 Found are largely handled by HTTP libraries, but they matter for one specific reason: if you're hardcoding API endpoints rather than building them from a base URL config, you'll hit 301s when providers update their URL structure and your library might follow the redirect silently without updating your stored endpoint. The right response to a 301 is to update your configuration, not just let the redirect happen forever.

## The 4xx range: your code has a problem

This is where most integration bugs live.

400 Bad Request means the server couldn't parse or accept the request as sent. This might mean malformed JSON or missing required fields, but it can also be a type mismatch between what you sent and what the endpoint expects. The response body usually contains an error message worth logging verbatim. Handling 400 generically as "invalid request" leaves you debugging blind.

422 Unprocessable Entity is often confused with 400, but the distinction matters for how you respond. 400 is a structural problem: the request couldn't be parsed or is missing required shape. 422 is semantic: the request was well-formed but the data failed business-rule validation. A date range where the end date precedes the start date is a 422. An account ID reference that doesn't exist in this company is a 422. An invoice total that doesn't reconcile with its line items is a 422. Some providers use 400 for both; when that happens you need to parse the error body to distinguish them, because the fix is different in each case.

```javascript
// QuickBooks returns 400 for validation errors; Xero returns 422.
// Parse the body to determine the actual problem.
function handleValidationError(status, body) {
  const message = body?.Fault?.Error?.[0]?.Message    // QuickBooks
    ?? body?.Elements?.[0]?.ValidationErrors?.[0]?.Message // Xero
    ?? body?.message
    ?? 'Unknown validation error';

  console.error(`Validation error (${status}):`, message);
  // Surface to user, do not retry
}
```

401 Unauthorized means the request didn't include valid credentials, or the credentials have expired. For OAuth-based integrations, a 401 typically means your access token needs refreshing. Most libraries handle token refresh automatically, but the failure mode when they don't is silent: the refresh fails, the 401 propagates, and whatever data operation you were trying to do gets skipped. Treat 401 responses as a trigger for explicit token refresh logic, not just a retry.

```javascript
async function requestWithRefresh(url, options, connection) {
  let res = await fetch(url, withAuth(options, connection.accessToken));

  if (res.status === 401) {
    // Attempt token refresh once
    connection.accessToken = await refreshAccessToken(connection.refreshToken);
    await saveConnection(connection);
    res = await fetch(url, withAuth(options, connection.accessToken));
  }

  if (!res.ok) throw new ApiError(res.status, await res.json().catch(() => ({})));
  return res.json();
}
```

403 Forbidden is different from 401. The credentials are valid, but they don't have permission to do what you're asking. This comes up regularly when a user connects an accounting platform with a read-only role and your integration tries to write data. A retry won't help. Surface a meaningful error to the user explaining what permissions they need to grant, not a silent failure.

404 Not Found is usually one of three things: a typo in your endpoint URL, a resource that was deleted, or an ID that doesn't exist in that account. For accounting integrations, deleted resources come up regularly. Customers archive invoices and deactivate accounts without warning. Your application needs to handle 404s gracefully rather than throwing an unhandled exception.

409 Conflict means the request conflicts with the current state of the resource. Duplicate invoice creation is a common trigger, as is concurrent modification. If your integration retries a POST after a timeout, you may get a 409 on the second attempt because the first request actually succeeded. For financial data, 409 handling requires explicit deduplication logic, typically using idempotency keys if the provider supports them.

429 Too Many Requests means you've hit a rate limit. The response usually includes a [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After) header telling you how long to wait, or X-RateLimit-Remaining and X-RateLimit-Reset headers showing the current window state. Many implementations ignore these and retry after a fixed delay, which either under-waits (triggering another 429 immediately) or over-waits unnecessarily. When Retry-After is present, use it. When it's absent, start short and increase exponentially.

```javascript
async function handleRateLimit(res) {
  // Prefer Retry-After if present
  const retryAfter = res.headers.get('Retry-After');
  if (retryAfter) {
    const delayMs = isNaN(retryAfter)
      ? new Date(retryAfter) - Date.now()  // HTTP-date format
      : Number(retryAfter) * 1000;         // delta-seconds format
    await sleep(Math.max(delayMs, 0));
    return;
  }

  // Fall back to X-RateLimit-Reset if available
  const resetAt = res.headers.get('X-RateLimit-Reset');
  if (resetAt) {
    await sleep(Math.max(Number(resetAt) * 1000 - Date.now(), 0));
    return;
  }

  // No header: start with 1 second (caller handles backoff)
  await sleep(1000);
}
```

## The 5xx range: the server has a problem

500 Internal Server Error means something broke on the provider's side. The response body often contains a request ID or trace ID. Log it. If you report the issue to the provider's support team, that ID is how they'll find it in their logs. Retrying a 500 sometimes works if it was a transient failure; cap the retries and log each attempt.

502 Bad Gateway and 503 Service Unavailable are both forms of temporary unavailability. 502 typically means a proxy received an invalid response from an upstream server. 503 means the server is explicitly unavailable, often due to maintenance or overload. Both are candidates for retry with exponential backoff. The practical difference is that 503 responses often include a Retry-After header while 502 responses rarely do.

504 Gateway Timeout creates a specific problem for write operations. If a POST to create a transaction times out with a 504, you don't know whether the transaction was created or not. Treat 504s on write operations as "state unknown," check for the resource explicitly before retrying, and use an idempotency key on the retry so that if the original request succeeded, the retry returns the original response rather than creating a duplicate.

```javascript
// For writes, check before retrying after a 504
async function createInvoiceSafe(payload) {
  const idempotencyKey = payload.externalRef; // a stable ID from your system

  try {
    return await apideck.accounting.createInvoice(payload, { idempotencyKey });
  } catch (err) {
    if (err.status !== 504) throw err;

    // State unknown: check whether the invoice was actually created
    const existing = await apideck.accounting.getInvoices({
      filter: { externalRef: payload.externalRef }
    });

    if (existing.length > 0) return existing[0]; // already created

    // Not found: safe to retry with the same idempotency key
    return apideck.accounting.createInvoice(payload, { idempotencyKey });
  }
}
```

## Error-handling strategies

When retrying, use [exponential backoff with jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/): a 1-second base delay that doubles on each retry, with a random offset added to prevent multiple clients from retrying in lockstep. Set a maximum retry count and a ceiling on the wait time. On which codes to retry: 400 and 422 errors rarely benefit from a retry without also changing the request. 401 warrants a token refresh first. 403 warrants a user-facing error. The 5xx codes and 429 are worth retrying with backoff, respecting any Retry-After header that's present.

```javascript
const RETRYABLE = new Set([429, 500, 502, 503, 504]);

async function withRetry(fn, maxAttempts = 4) {
  let attempt = 0;

  while (true) {
    try {
      return await fn();
    } catch (err) {
      attempt++;
      if (!RETRYABLE.has(err.status) || attempt >= maxAttempts) throw err;

      // Respect Retry-After if present
      if (err.retryAfterMs != null) {
        await sleep(err.retryAfterMs);
        continue;
      }

      // Exponential backoff with full jitter
      const cap = 30_000;
      const base = 1_000 * Math.pow(2, attempt - 1);
      const delay = Math.random() * Math.min(cap, base);
      await sleep(delay);
    }
  }
}
```

For POST requests that create financial records, include an idempotency key if the provider supports it. [Xero](https://developer.xero.com/documentation/guides/idempotent-requests/idempotency/) and [Stripe](https://docs.stripe.com/api/idempotent_requests) both support idempotency keys natively. If a request with a given key succeeds, subsequent requests with the same key return the original response rather than creating a duplicate. This makes retries on network timeouts safe without risking duplicate invoices or transactions in the customer's accounting system.

```javascript
// Xero: pass idempotency key as a header
const res = await fetch('https://api.xero.com/api.xro/2.0/Invoices', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': invoice.externalRef, // stable ID from your system
  },
  body: JSON.stringify(invoice),
});
```

If an endpoint is returning 5xx errors consistently, stop retrying it. A circuit breaker watches for consecutive failures and automatically pauses requests to the failing endpoint for a configured period before attempting a probe request to see if it has recovered. Libraries like [Resilience4j](https://resilience4j.readme.io/docs/circuitbreaker) in Java or [Polly](https://github.com/App-vNext/Polly) in .NET handle this well. For simpler setups, a flag that disables retries after 10 consecutive errors is better than a loop that hammers a failing endpoint.

Structured logging is the investment teams undervalue until they're in an incident. For every non-2xx response, log the status code and the request ID returned by the provider, along with the endpoint and HTTP method. Include enough of the response body to understand what failed. Avoid logging full request payloads (API keys, PII) in production, but log enough to reconstruct what happened.

```javascript
function logApiError(method, url, status, responseBody) {
  const requestId =
    responseBody?.requestId ??
    responseBody?.id ??
    responseBody?.Fault?.Error?.[0]?.Detail ?? // QuickBooks
    null;

  console.error(JSON.stringify({
    level: 'error',
    method,
    url,
    status,
    requestId,
    message: responseBody?.message ?? responseBody?.detail ?? null,
    ts: new Date().toISOString(),
  }));
}
```

For teams building against multiple accounting APIs, provider inconsistency is a real operational cost. QuickBooks returns a 400 where Xero returns a 422 for the same class of validation error, and rate limit handling diverges just as sharply across providers. [Apideck's Accounting API](https://www.apideck.com/accounting) normalizes these differences before they reach your application, so your error-handling logic doesn't need to branch by provider.

The status code is the first word in every API conversation. If your application isn't listening to it, it's guessing.

How to handle every HTTP status code your API integration will encounter. From 2xx edge cases to 504 write-operation unknowns, this guide covers retry strategies, idempotency keys, circuit breakers, and structured error logging for accounting and financial integrations.

API response codes: examples and error-handling strategies

**Short answer:** An API endpoint is a URL you call to request or send data. A webhook is a URL on your server that a third party calls when an event happens. Endpoints pull. Webhooks push. Both are HTTP URLs, which is why they get confused, but they flow in opposite directions.

If you're building software integrations, you've run into both of these terms. They get conflated often enough that it's worth being precise about what each one actually means and where the confusion comes from.

## Webhook vs API endpoint at a glance

| Aspect | API Endpoint | Webhook |
|---|---|---|
| **Direction** | Client pulls from server | Server pushes to client |
| **Trigger** | Your code makes a request | An event in the source system |
| **Who initiates** | You (the consumer) | The third-party system |
| **HTTP method** | Usually GET, POST, PUT, DELETE | Almost always POST |
| **Timing** | On demand or scheduled polling | Real time, as events happen |
| **Best for** | Reads, writes, complex queries | Notifications, state changes, sync |
| **Latency** | Equal to polling interval | Milliseconds |
| **Failure handling** | Retry immediately with backoff | Depends on sender's retry policy |
| **Setup on your side** | API key, request code | A public URL that accepts POST |
| **Resource cost** | Higher when polling frequently | Low under normal conditions |

![webhook vs api endpoint](//images.ctfassets.net/d6o5ai4eeewt/21yjwTb2AlYLHJf5w4nN5m/e60df0c9200012774f0acdd838502538/Screenshot_2026-05-22_at_04.17.43_2x.png)

## What an API endpoint is

An endpoint is a URL that exposes a resource through an API. When you make a request to `https://api.apideck.com/accounting/invoices`, that URL is the endpoint. It specifies the host, the API version (implied in the path or header), and the resource you want to interact with.

Endpoints are passive. They sit there and respond to requests. You call them; they answer. The client controls the timing: your code decides when to ask for data, and the API returns whatever matches the query at that moment.

A typical request to an endpoint looks like this:

```bash
curl -X GET "https://api.apideck.com/accounting/invoices" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-apideck-consumer-id: user_123" \
  -H "x-apideck-app-id: app_456"
```

The server responds with a JSON body containing the invoices that match the query, plus pagination cursors.

This model, often called polling when done on a schedule, is how most [API integrations](/blog/api-integration-services) start out. Your app hits an endpoint every minute or every hour, fetches recent invoices, and processes the results. It works, but it has a cost: you're making requests even when nothing has changed, and you always have at least one polling interval of latency before you see new data.

## What a webhook is

A webhook is a mechanism for pushing data from one system to another when something happens. Instead of your app asking for data, the source system sends it to you automatically.

Here's how it works in practice: you register a URL on your own server (your webhook endpoint) with the source system. Then you tell that system which events you care about, something like "notify me when an invoice is created" or "send me a payload when a payment is marked as received." From that point on, every time that event fires, the source system makes an HTTP POST request to your URL with the event data in the body.

A typical webhook payload arriving at your server looks something like this:

```json
{
  "id": "evt_01HX8Y9N4ZQX8K7M2P3R5T6V8W",
  "type": "invoice.paid",
  "created_at": "2026-04-27T14:23:11Z",
  "data": {
    "invoice_id": "inv_8821",
    "amount": 4250.00,
    "currency": "USD",
    "customer_id": "cus_4419",
    "paid_at": "2026-04-27T14:23:09Z"
  },
  "service": "quickbooks",
  "consumer_id": "user_123"
}
```

Your handler receives this POST request, verifies the signature, looks up the invoice in your own database, and updates the status. No polling, no delay.

This is event-driven rather than request-driven. You're not pulling data on a schedule; the data comes to you the moment it's available.

## Where the two terms overlap

The confusion usually comes from the fact that your webhook listener is technically an API endpoint. It's a URL that accepts HTTP requests. When a source system sends you a webhook, it's hitting your endpoint with a POST request. So "webhook endpoint" is a real phrase with a real meaning: it's the URL you registered to receive webhook payloads.

The distinction is about role and direction. An API endpoint is what you call to get or update data in a third-party system. A webhook endpoint is what that third-party system calls on your server when something changes.

## A real-world example: invoice paid in QuickBooks

Let's walk through what actually happens when a customer marks an invoice as paid in QuickBooks, and how your app finds out.

**With polling (API endpoints only):**

1. Your app runs a cron job every 5 minutes.
2. It hits `GET /accounting/invoices?updated_since=2026-04-27T14:18:00Z`.
3. QuickBooks returns the recently updated invoices, including the one just paid.
4. Your app processes the change and updates your database.
5. Total latency: up to 5 minutes. You also made 287 other requests today that returned nothing new.

**With webhooks:**

1. The customer marks the invoice as paid in QuickBooks at 14:23:09.
2. QuickBooks fires a webhook to your registered URL at 14:23:11.
3. Your handler verifies the signature, processes the payload, updates your database.
4. Total latency: 2 seconds. Zero wasted requests.

For something like revenue recognition or sending a thank-you email to the customer, those minutes matter. For a nightly accounting reconciliation, they don't. That is the whole decision.

## Which one to use

For most [accounting integrations](/blog/accounting-for-developers), you want both.

Endpoints handle reads and writes. When a user connects their QuickBooks or Xero account to your product, you use API endpoints to fetch their chart of accounts, pull historical invoices, create new transactions, or reconcile payments. All of that is request-driven because you're the one initiating the operation.

Webhooks handle real-time sync. When an invoice gets paid in QuickBooks, you don't want to poll every minute hoping to catch it. You want to be notified immediately. QuickBooks fires a webhook to your listener, you process the payload, and your system updates without any delay.

The practical split: use endpoints when you're acting on data, use webhooks when you need to react to changes.

## Webhook security: what most guides skip

A webhook endpoint is a public URL. Anyone who knows it can POST to it. Without verification, an attacker can forge events: fake invoice payments, fake refunds, fake user signups. Three things you need:

**Signature verification.** Every major webhook sender signs the payload with an HMAC using a shared secret. Stripe, GitHub, Shopify, QuickBooks all do this. Your handler recomputes the signature from the raw request body and the secret, then compares it to the header. If it doesn't match, you reject the request. Use the raw body bytes, not the parsed JSON, or you'll get false negatives from whitespace differences.

**Replay protection.** A valid signed payload captured by an attacker can be replayed. Include a timestamp in the signed payload and reject requests where the timestamp is more than a few minutes old. Most senders include this by default; check the timestamp.

**IP allowlisting (when available).** Some providers publish the IP ranges their webhooks come from. If yours does, restrict your endpoint to accept only from those ranges. This is belt and suspenders on top of signature verification, not a replacement.

For more on production-grade webhook handling, the [Standard Webhooks](https://www.standardwebhooks.com/) spec codifies most of this if you're designing your own webhook system.

## Reliability considerations

Webhooks introduce a delivery problem that polling doesn't have. If your server is down when a webhook fires, that event payload is gone unless the source system retries it. Most will retry a few times with backoff, but if your service has extended downtime, you can miss events.

This is why webhook-based integrations typically pair with a fallback polling strategy: webhooks keep you current under normal conditions, and a periodic full sync ensures nothing falls through during outages. Stripe's webhook documentation describes this pattern explicitly: subscribe to events for real-time updates, but also reconcile via the API on a schedule.

For accounting data in particular, missed events have real consequences. A payment update that doesn't sync means your revenue recognition is wrong, your reconciliation breaks, and someone in finance ends up chasing ghosts in a spreadsheet. Building retry logic and idempotency into your webhook handler is not optional. Understanding [how to handle API errors and HTTP status codes](/blog/api-response-codes) is a prerequisite for any production webhook implementation.

## Idempotency matters

One detail that trips up a lot of webhook implementations: you'll sometimes receive the same event more than once. Source systems retry on network failures, and it's not always clear whether your server received and processed the first attempt. A well-built webhook handler checks whether it has already processed a given event ID before doing anything with the payload. This is called idempotency: processing the same event twice produces the same result as processing it once.

The simplest implementation: store the event ID from the payload (the `id` field in the example above) in a table with a unique constraint. On every incoming webhook, try to insert the ID first. If the insert fails because the ID already exists, skip processing. If it succeeds, do the work.

For accounting integrations, where a duplicate invoice creation or a double-applied payment can create real accounting errors, idempotency in your webhook handler is non-negotiable.

## What a unified API changes

When you're building integrations across multiple accounting platforms, managing webhooks per-platform adds real complexity. QuickBooks, Xero, Sage, and FreshBooks each have their own webhook schemas, different event names for the same underlying concept, different retry policies, and different verification mechanisms for confirming that a payload actually came from them.

A [unified API](/blog/what-is-a-unified-api) layer normalizes this. Rather than wiring up separate webhook listeners for each platform, you subscribe once to a normalized event stream and receive consistent payloads regardless of which accounting system is on the other end. The same `invoice.paid` event format arrives whether the underlying system is QuickBooks or Xero, and your application logic doesn't have to know the difference.

That's the actual distinction. Endpoints are how you talk to external systems; webhooks are how those systems talk to you. Both are built on HTTP, which is why they look similar at first glance, but they serve opposite directions of data flow.


Webhooks push data to your server when events fire. API endpoints sit and wait for your requests. Here's what each one does, when to use each, and how a unified API handles webhook complexity across accounting platforms.

Webhook vs API Endpoint: What's the Difference?

The internet runs on [OAuth 2.0](https://datatracker.ietf.org/doc/html/rfc6749). Since 2012, it has handled how applications request access to user data, how APIs delegate permissions, and how login buttons across billions of apps connect to identity providers. It has worked well enough that most developers stopped questioning it.

Then agents arrived, and OAuth started showing its seams.

When a human logs into Salesforce via Google, the flow is synchronous: redirect, consent screen, token issued. The user was there. The user said yes. When an AI agent books a flight, queries a ledger, and triggers a payment while you sleep, there is no consent screen moment. The agent makes decisions mid-task, calls services it discovered at runtime, and may hand off to sub-agents that hand off further down the chain. OAuth was not designed to track any of that.

The spec Dick Hardt wrote in 2012 was designed for clients known at build time. In OAuth and OIDC, a client has no independent identity: a client_id at Google is meaningless at GitHub. Agents pick their tool chain at runtime, one call at a time, choosing the next tool as the task unfolds. A scope like `mail.read` looks identical whether the agent is summarizing your inbox or exfiltrating it. The protocol cannot tell them apart.

This is the problem the industry is currently trying to solve.

## What MCP and A2A changed

Anthropic's [Model Context Protocol](https://modelcontextprotocol.io/), published in 2024, gave agents a standard interface to tools and data sources. Early MCP servers had minimal authentication, typically API keys in environment variables. That worked for local stdio transport but not for remote servers where tokens could be intercepted.

MCP's March 2025 specification standardized authorization using OAuth 2.1, requiring PKCE from all clients and adding metadata discovery and dynamic client registration. Remote MCP servers running over Streamable HTTP now have a recommended authentication path that developers can implement consistently. The spec is clear: authorization is optional but strongly recommended for any server that lets agents take action.

One gap in that flow is discovery. An agent hitting a remote MCP server for the first time needs to know where the authorization server lives before it can start any OAuth exchange. [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) (OAuth Protected Resource Metadata) addresses this by letting the server publish its auth endpoint at `/.well-known/oauth-protected-resource`. Cloudflare added native support for this discovery flow in [Cloudflare Access](https://blog.cloudflare.com/managed-oauth-for-access/) in April 2026, showing how established infrastructure is adapting to support it.

The gap MCP did not address was agent-to-agent communication. If your orchestrator agent needs to delegate to a specialized research agent or a payment processor, MCP provides no protocol for that handoff. Each agent authenticates independently, with no standard way to reduce permissions or prove the delegation chain.

Google published [A2A](https://a2a-protocol.org/latest/) on April 9, 2025, with backing from more than 50 launch partners across enterprise software, including Salesforce and SAP. A2A is built on existing web infrastructure standards, making it compatible with systems businesses already run. It was designed to support enterprise-grade authentication and authorization, with parity to OpenAPI's authentication schemes.

Where MCP handles the connection between an agent and its tools, A2A handles the connection between agents themselves. An inventory agent built by your team can communicate with a supplier agent built by a third party, using [Agent Cards](https://google.github.io/A2A/specification/#agent-card) to publish capabilities and OAuth 2.0 flows to handle authentication.

Google donated A2A to the Linux Foundation in June 2025. IBM's ACP (Agent Communication Protocol) merged into it voluntarily in August 2025. By April 2026, A2A had grown to 150+ organizations with production deployments in place across major enterprise software vendors.

## The deeper problem: bearer tokens don't work in multi-hop chains

Both MCP's OAuth 2.1 and A2A's authentication schemes still rely on bearer tokens. If you hold the token, you can use it. In a multi-agent pipeline, that creates a structural problem.

Multi-agent delegation chains require a constraint that standard token formats cannot enforce: each hop should only be able to reduce permissions, never expand them. With bearer tokens, there is no mechanism to prevent a sub-agent from reusing a delegated credential at full scope.

This is where [AAuth](https://www.aauth.dev/) enters. Dick Hardt, who authored the OAuth 2.0 RFC, has been developing a specification at aauth.dev that treats agents as first-class identities. AAuth brings together authentication and authorization built on OAuth RFCs, with message signing and discovery, to provide a foundation for agent identity and access management. Every HTTP request must be signed by the agent's key pair, and delegation must be made explicit and verifiable rather than inferred from logs.

The core shift is cryptographic. A stolen token without the corresponding private key cannot be replayed. Delegation chains become explicit and auditable.

AAuth is currently an exploratory specification, not a ratified standard. The [playground at playground.aauth.dev](https://playground.aauth.dev/) lets you call `whoami.aauth.dev` to see agent identity claims in practice. It is worth tracking because it works from first principles rather than extending a protocol designed for browsers: what would authentication look like if agents were the starting point?

Token formats like [Biscuits](https://www.biscuitsec.org/) and [Macaroons](https://research.google/pubs/macaroons-cookies-with-contextual-caveats-for-decentralized-authorization-in-the-cloud/) approach the scope attenuation problem differently. These allow the agent receiving a token to cryptographically restrict it before passing it downstream, and those restrictions cannot be removed by any party that does not hold the original minting key. No round-trip to an authorization server is needed to narrow permissions. The restriction is embedded in the token itself.

## WIMSE and the IETF's framework

The IETF has been developing workload identity standards under the [WIMSE](https://datatracker.ietf.org/wg/wimse/about/) (Workload Identity in Multi-System Environments) working group. In March 2026, [draft-klrc-aiagent-auth-00](https://www.ietf.org/archive/id/draft-klrc-aiagent-auth-00.html) was published, composing WIMSE, SPIFFE, and OAuth 2.0 into a 26-page framework called AIMS (Agent Identity Management System).

The draft adopts the WIMSE identifier as the primary agent identifier, a URI that uniquely identifies a workload within a trust domain. Authorization decisions and audit logs pivot on this ID, which must remain stable for the lifetime of the workload identity. [SPIFFE](https://spiffe.io/) (Secure Production Identity Framework for Everyone) is the operationally mature implementation, handling automatic credential rotation and binding ephemeral key material with each credential.

The draft is solid on authentication. The WIMSE identifiers bind agent identity to the execution environment through hardware-rooted attestation. The authorization layer, however, stops at the token boundary. The Security Considerations section of the -00 revision contains two words: "TODO Security." Authentication is getting formalized. Authorization across trust domains is still a product and engineering problem.

NIST launched two initiatives in February 2026: the NCCoE concept paper on AI agent identity and authorization, and the AI Agent Standards Initiative covering security controls and testing. Both center on WIMSE and SPIFFE combined with OAuth. The Colorado AI Act establishes a "reasonable care" standard for high-risk AI systems effective June 30, 2026, and widely adopted identity standards will likely qualify as evidence of that care in court.

## What practitioners are shipping today

[Auth0](https://auth0.com/blog/auth0-for-ai-agents-is-now-generally-available/) (part of Okta) reached general availability of Auth0 for AI Agents in November 2025. Using Client-Initiated Backchannel Authentication (CIBA), agents can pause execution, request user approval via email or Auth0 Guardian, and resume automatically once the user approves. The SDK detects when a tool call needs authentication, stores the token securely, and resumes without further developer intervention. Auth0 is also collaborating with Google Cloud on A2A authentication, which signals how incumbent identity vendors see this space.

The auth discussion so far has covered how agents prove their identity to services. The inverse problem also needs a standard answer: how does a service verify that the agent connecting to it is who it claims to be? The [Web Bot Auth IETF draft](https://datatracker.ietf.org/doc/draft-meunier-web-bot-auth-architecture/) tackles this from the server side. It lets bots sign their HTTP requests with a private key and publish their corresponding public keys at `/.well-known/http-message-signatures-directory`, allowing receiving sites to cryptographically verify inbound bot traffic rather than relying on user-agent strings that any client can spoof. It is the server-side complement to what AAuth proposes on the client side: a matched pair of signing and verification standards that give both ends of an agent interaction a way to establish cryptographic trust.

The hardcoded credential problem has not improved. [GitGuardian's State of Secrets Sprawl 2026](https://www.gitguardian.com/state-of-secrets-sprawl) report found 28.65 million hardcoded secrets added to public GitHub in 2025 alone, a 34% year-over-year increase. Agents generate logs and replicate workflows automatically, and the exposure surface is larger than with traditional integrations.

The [Apideck Unified MCP server](https://www.apideck.com/mcp-server) offers a concrete example of how this plays out in production. The server at `mcp.apideck.dev/mcp` exposes 229 tools across Accounting, HRIS, CRM, and more. Auth against the MCP server itself happens via three request headers: `x-apideck-api-key`, `x-apideck-app-id`, and `x-apideck-consumer-id`. The consumer ID connects an agent to a specific user's pre-authorized integrations. Before the agent ever runs, the end user has authorized their connectors through [Vault](https://www.apideck.com/products/vault), Apideck's credential management layer. When the agent calls a tool, Vault looks up the correct credentials in the background and injects the right token before making the downstream API call. The agent never holds OAuth tokens for third-party services directly.

The design solves a specific sequencing problem. Consent happens once at connection setup rather than mid-task. Vault handles token refresh automatically. The MCP server annotates tools with permission levels (read, write, destructive), so a read-only agent cannot even discover delete operations in the tool list. That is the same principle AAuth formalizes at the protocol level: permissions should be bounded at each hop, not left to the agent to self-limit.

A production-grade agent auth stack today requires:

- OAuth 2.1 with PKCE for MCP tool access
- A2A with Agent Cards for cross-agent delegation
- SPIFFE-issued short-lived credentials for workload authentication
- Token attenuation (Biscuits or Macaroons) or AAuth-style signed requests for multi-hop chains where scope reduction matters

None of this is a single product. It is an architecture you compose from pieces that are still being standardized.

## Where this leaves builders

Authentication is converging around known primitives. Authorization across trust domains is not.

Knowing that an agent is who it claims to be is one problem. Knowing what it is actually allowed to do during a specific task, and producing proof of that afterward, is harder. [OWASP's MCP Top 10](https://genai.owasp.org/llm-top-10/) and A2A's signed Agent Cards address pieces of this, as does the WIMSE architecture. No single specification covers the full chain from identity through intent to audit trail.

The infrastructure gap extends beyond the auth layer itself. [Cloudflare scanned the 200,000 most visited domains](https://blog.cloudflare.com/agent-readiness/) in April 2026 and found that fewer than 4% of sites have declared AI usage preferences in their robots.txt, and emerging standards like MCP Server Cards and API Catalogs appeared on fewer than 15 sites in the entire dataset. Most of the internet is not yet set up to receive authenticated agent traffic, let alone verify it. [isitagentready.com](https://isitagentready.com/) scores any site across discoverability, bot access, and protocol capabilities, including whether OAuth server discovery is published correctly, and generates per-check prompts you can hand to an agent to fix what is missing.

![Is Agent Ready - Cloudflare](//images.ctfassets.net/d6o5ai4eeewt/5w6sD3jOJUvhX2nmV50o1i/95efce71e782d5f14d921426e9ce174f/unnamed__2_.png)

For anyone building integrations that agents will traverse, the relevant question is not whether your API supports OAuth. It is whether your auth layer can handle delegated credentials and produce a verifiable trail of which agent did what and on whose behalf. Most existing OAuth implementations were not designed to answer that. The work to make them do so is happening now, and the teams that engage with it early will be ahead of the ones waiting for a finished spec.

OAuth 2.0 was designed for clients known at build time. As AI agents make runtime decisions, delegate to sub-agents, and traverse trust boundaries, the cracks are showing. A practical breakdown of MCP OAuth 2.1, A2A, AAuth, WIMSE, and what a production-grade agent auth architecture looks like today.

Agent Auth: Why OAuth Wasn't Built for This

Stripe processed over $1 trillion in payments in 2023. For most vertical SaaS teams building their first embedded payments flow, Stripe Connect is the obvious starting point. It handles KYC, 1099 tax forms, and enough of the compliance surface that most SaaS engineers never have to think about it. You can ship a working payout flow in a weekend.

That speed is real. For early-stage products it usually makes sense. The problem shows up later, when the payout rail starts to interact with the rest of your product and your vendors' businesses.

The more useful question is which point on the payments ownership curve a platform actually sits at, and when it makes sense to graduate to the next.

## The Four Levels of Payments Ownership

Embedded payments looks like a single decision from the outside. From the inside it splits into four distinct models, each with different economics, compliance burden, and chargeback exposure.

The first is the referral or ISO model. The platform refers merchants to a processor, takes a small share of the spread, and carries no liability. Stripe Connect Standard sits here for many early-stage platforms. Onboarding is fast, the processor owns the merchant relationship, and the platform's take rate is thin.

The second is Payments-as-a-Service, sometimes called PayFac-as-a-Service. The platform looks like a [payment facilitator](https://whop.com/blog/what-is-a-payfac/) to its merchants, but the underlying license, sponsor bank, and core compliance work sit with the provider. This is where Stripe Connect Custom (now Embedded Components), Adyen for Platforms, Finix, Payrix, Tilled, [Embed](https://www.embed.co/), and Rainforest operate. Margins are materially higher than referral. The platform takes on more compliance work and more chargeback exposure than at level one.

The third is registered Payment Facilitator. The platform holds its own PayFac registration with the card networks, runs its own sponsor bank relationship, and operates its own underwriting. Toast is the canonical vertical SaaS example at this level. Margins are highest. So is the compliance lift: KYB at scale, AML, OFAC screening, SAR/CTR filings, reserve management, and direct chargeback liability.

The fourth is acquirer or processor. Almost no software company sits here. It exists for completeness.

Most vertical SaaS platforms graduate from level one to level two when payment volume hits a certain inflection. The question is whether the next step on the ownership curve produces enough margin to cover the operational work it adds.

## Why Stripe Connect Is the Default Starting Point for Vertical SaaS Payments

Stripe Connect launched over a decade ago specifically to handle marketplace and platform payouts. It covers merchant onboarding, identity verification, tax reporting, and cross-border payments in a single integration. For a team that needs to ship fast and doesn't want to think about payment compliance, that breadth is genuinely useful.

The developer experience is also hard to argue with. Stripe's documentation is thorough, the SDKs are mature, and there's a large community of engineers who've already solved common integration problems. When you're building your first version, that head start matters.

Connect itself is not one product. Connect Standard, Express, and Custom (Embedded Components) sit at different points on the ownership curve. Standard is closest to a referral relationship. Custom can support a near-PayFac experience with material take rate via `application_fee_amount` on direct charges. Teams that say "we use Connect" often mean very different things, and the economics differ accordingly.

Cross-border is genuinely Stripe's strongest moat. Connect supports payouts in 45+ countries with FX handling that purpose-built alternatives still struggle to match. For platforms with a global vendor base, that coverage is hard to walk away from.

But Stripe Connect was built for a wide range of use cases, not specifically for vertical SaaS platforms. That distinction becomes important at scale, and it shows up in three places: the economics, the accounting integration, and the underwriting model.

## Purpose-Built Embedded Payments Providers for SaaS Platforms

A separate category of providers has grown up specifically for vertical SaaS, and the difference in design philosophy is meaningful.

[Rainforest](https://www.rainforestpay.com) is one example. It operates as a Payments-as-a-Service provider: platforms own their customer relationships, data, and contracts, and earn a share of the payment margin rather than passing it entirely to the processor. Rainforest also builds vertical-specific underwriting models, which matters for industries like healthcare, home services, and logistics where merchants don't fit the standard risk profile and end up with low approval rates under mainstream processors. The company raised a $29 million Series B in September 2025 and counts healthcare, nonprofits, and home services as its fastest-growing segments.

The competitive set is wider than Rainforest. Adyen for Platforms is the enterprise default and powers payments for eBay, Uber, and Microsoft. Finix is the closest direct comp on developer-first PFaaS positioning. Payrix sits inside FIS and is deep in vertical SaaS. Tilled and Worldpay for Platforms round out the list. Each operates broadly at level two of the ownership curve, with different geographic coverage, pricing, and underwriting depth. The right choice depends on the vendor profile.

Embedded banking is an adjacent category. Unit and Column extend further into business accounts, cards, and lending alongside payout rails. They are not direct alternatives to Stripe Connect for processing, but they are often the next expansion line for a platform that has already shipped payments.

The full landscape is wider still. The Open Banking Tracker tracks [96 embedded payments providers](https://www.openbankingtracker.com/embedded-finance/category/payments) across both processing and banking infrastructure.

## The Revenue Case for Switching Off Stripe Connect

This is the part most vertical SaaS teams underestimate, and the framing matters.

Stripe Connect does support a platform margin via `application_fee_amount`. The cap on that margin is what differs from a PFaaS or registered PayFac model. Platforms on Connect Standard typically capture a thin share of the spread. Platforms that move to level two of the ownership curve capture meaningfully more, both because the fee structure is different and because they participate in interchange-plus economics directly.

A [2022 Bain & Company and Bain Capital report](https://www.bain.com/about/media-center/press-releases/2022/embedded-finance-transaction-value-to-more-than-double-to-%247-trillion-in-us-by-2026-but-financial-institutions-must-move-quickly-to-keep-upbain--company-and-bain-capital-report/) forecast total embedded finance transactions in the US to exceed $7 trillion by 2026, with payments as the largest category. UBS puts SMBs at 25-30% of US payment volume but over 70% of net revenues. That's the market vertical SaaS platforms sit closest to.

The conventional wisdom is that take rates are compressing toward zero. Rainforest's 2026 Embedded Payments Benchmark, [presented at Vertex](https://www.youtube.com/watch?v=Qmq-jkjR3Tg), reports a different pattern: nearly half of vertical SaaS platforms in the survey report take rates above 90 basis points. Platforms processing under $50M run median take rates of 0.46-0.60%; cross $250M in volume and the median doubles to 0.91-1.05%. This is vendor-published data from a sample of platforms that opted into the survey, so the numbers should be read directionally rather than as a universal benchmark. Even so, the ladder is consistent with what other PFaaS providers report, and it matches the broader pattern that payments economics inflect with scale.

<iframe width="720" height="405" src="https://www.youtube.com/embed/Qmq-jkjR3Tg" frameborder="0" allowfullscreen></iframe>

There's also a retention argument. Platforms that embed payments well see higher retention because the payment experience is tightly integrated with the core product. A vendor who processes invoices, tracks jobs, and gets paid all inside the same tool is less likely to churn than one who toggles between your software and a generic payment interface. The same benchmark found that payments peaks at 35% of total platform revenue at 3-4 years after launch, making it one of the largest revenue lines in the business by that point.

## Take Rate and Attach Rate: The Two Numbers That Define the Business Case

Two metrics determine whether embedded payments becomes a real revenue line or stays a feature: take rate and attach rate.

Take rate is the percentage of payment volume the platform keeps. The actual mechanic behind a 70-100 bp take rate is interchange-plus pricing on the merchant side, level 2 and level 3 data on B2B card volume, surcharging where legal, and merchant mix. The headline rate compresses or expands based on how those levers are set. At $100M in annualized payment volume, 70 basis points is $700K in annual revenue. At $500M it's $3.5M.

Attach rate is the percentage of a platform's active customers who actually adopt the embedded payments product. A strong take rate with a low attach rate doesn't move the needle. Platforms that reach strong attach rates typically get there by making payment collection the natural next step inside an existing workflow (job completion, invoice approval, order fulfillment) rather than a separate module the vendor has to discover and sign up for. Field service platforms that tie payment collection directly to job closeout consistently outperform those that treat payments as a standalone product.

The two numbers compound. There's a third variable the benchmark data surfaces: ownership. Platforms with a C-suite payments leader post almost double the take rates of those with no dedicated leader. Take rate, attach, and revenue share don't drift upward on their own.

52% of vertical software companies in the study still have no embedded fintech beyond payments at all. For platforms that have already shipped payments and are looking for the next revenue line, that gap represents the clearest expansion opportunity in the market right now.

For a fuller picture of how embedded payments fits the broader embedded finance landscape, Apideck's [State of Embedded Finance 2026 report](https://www.apideck.com/embedded-finance-report) covers take rates, attach rates, and build vs. buy signals across 15 embedded finance categories and 200+ providers.

## Which Verticals Feel This Most

Field service and home services platforms are the clearest case. Contractors and tradespeople are running businesses where the payout cycle is tightly connected to job completion and invoicing. Getting paid through the same platform where they manage their jobs, then having that payout flow automatically into their accounting software via ledger sync, is a core workflow.

Healthcare SaaS is another high-signal area. HSA/FSA payments, patient billing, and provider payouts all involve compliance and reconciliation complexity that generic payment processors handle poorly. Rainforest has cited an HSA/FSA authorization-rate lift from below 30% to 94% through vertical-specific underwriting, though most decline issues in this category come from MCC coding and IIAS compliance rather than underwriting alone, so the magnitude of any specific lift depends heavily on the starting baseline.

Legal SaaS is a third. [Clio](https://www.clio.com), which builds practice management software for law firms, launched Clio Payments in 2022. It now processes billions of dollars annually and was a significant driver of the company doubling ARR from $100M to over $200M between 2022 and 2024. In a [SaaStr interview](https://www.saastr.com/scaling-to-3b-how-clio-built-a-vertical-saas-powerhouse-with-ai-and-innovation-with-clios-ceo/), CEO Jack Newton said that in hindsight, Clio should have invested in payments earlier and more aggressively. Legal payments carry their own compliance complexity, specifically trust accounting rules that require payments to be withdrawn from a separate operating account. Generic processors don't handle this. A purpose-built integration does. At the Vertex conference in April 2026, leaders from Clio and Toast covered what they learned the hard way building embedded fintech into their platforms.

Staffing, nonprofit management, and local government SaaS round out the picture. Any vertical where the end user is a small operator, payment flows are tied to operational workflows, and reconciliation happens inside accounting software is a candidate for a purpose-built approach.

## The Payout Reconciliation Problem Most Vertical SaaS Teams Miss

The moment a payout hits a vendor's books, reconciliation starts. Someone has to match the payout to an invoice, confirm the amount is correct, and make sure it lands in the right account in whatever accounting software the vendor runs.

Stripe's data model is not built for this. It exposes transaction records, but those records don't map cleanly to what accounting software expects. You end up building a sync layer that translates Stripe events into general ledger entries (what the industry calls ledger sync), and that layer becomes a maintenance burden and a source of bugs every time either Stripe or the accounting platform changes its API.

Most teams scope the payout rail. Almost none scope the ledger sync. The fix requires treating the accounting integration as a first-class problem, not an afterthought. A [unified accounting API](https://www.apideck.com/accounting-api) handles the translation into each platform's data model automatically, so vendors don't have to manually reconcile payouts at month end. The data flows into their accounting software matched to the right accounts, without anyone touching it.

For a vertical SaaS product serving vendors who are also running a business, that's the difference between a tool that creates work and one that removes it.

## How to Pick Your Payout Stack

Start with geography. Stripe Connect supports payouts in 45+ countries with mature FX handling. Most PFaaS alternatives have narrower coverage. If your vendor base is concentrated in the US, that gap matters less. If you serve global vendors, it can be the deciding factor.

Then look at chargeback and compliance liability. Connect Standard keeps both with Stripe. Moving to a PFaaS or to registered PayFac shifts liability onto the platform: chargeback reserves, dispute operations, KYB at scale, AML, OFAC screening, and reserve management all become operational work the platform owns. The margin gain is real, the operational lift is also real, and platforms that move too early end up running compliance functions they did not budget for.

Then look at your vertical's risk profile. If your merchants are in industries that mainstream processors treat as high-risk, a purpose-built provider with vertical-specific underwriting will deliver meaningfully better approval rates. That directly affects payment adoption inside your platform, which affects the revenue case.

Then look at the buyer experience. Stripe Link, network tokenization, and Radar set a high bar on the buyer side. Some PFaaS alternatives match it. Others do not. For platforms whose vendors are processing high transaction volumes, this can move conversion several points.

Finally, consider the option you may not have priced in: renegotiating inside Stripe. For platforms above a certain volume threshold, Stripe will negotiate a platform pricing arrangement that shares margin. Many companies that "switch off Connect" actually just move to a custom Stripe deal. Worth pricing both before assuming a migration is the only path to better economics.

The payout rail is one decision. The ledger sync is a separate one that most teams make too late. If your vendors run on QuickBooks, Xero, Sage, or any other platform, a [unified accounting API](https://www.apideck.com/accounting-api) lets you connect the payout output to their books without building per-platform sync logic. Scope both before you ship.

Stripe Connect gets vertical SaaS teams to a working embedded payments flow fast. The problems show up later: economics, reconciliation, and underwriting. When purpose-built alternatives make more sense, and how to pick your payout stack.

Vertical SaaS Payments: Why Stripe Connect Isn't Always the Answer

There are three fundamentally different things a company might mean when it says it offers "API integration services." A systems integrator like Accenture. A dev shop in Warsaw. A unified API platform. These are not interchangeable. Picking the wrong one costs you months and tens of thousands of dollars.

## What is an API integration service?

An API integration service connects software systems through their APIs, managing the data flow, authentication, and error handling between them. The term covers three distinct categories: professional services firms that implement integrations as projects, custom development shops that build to spec, and unified API platforms that provide ongoing integration infrastructure. You may see it described as third-party API integration services when the connected systems are external platforms your software needs to interoperate with. Each category has a different pricing model, a different maintenance structure, and a different ceiling.

## The three categories

**Systems integrators and consulting firms**

Accenture, Deloitte, and Capgemini sell API integration as part of broader professional services engagements. They bring methodology, certified practitioners on platforms like MuleSoft or Azure Integration Services, and project governance structures. The engagement model is time-and-materials or fixed-fee, typically starting in the $100K-$500K range for a meaningful project.

This makes sense when you are a large enterprise connecting an on-premise ERP to a cloud supply chain system. It does not make sense when you are a SaaS company trying to offer 30 accounting integrations to customers. The unit economics are wrong. A Deloitte MuleSoft engagement is designed for internal IT transformation, not for the kind of multi-tenant, customer-facing integration infrastructure that product builders need.

**Custom API integration services**

A tier below the big SIs, you have companies like Apriorit, Asper Brothers, Simform, and Infomaze. They build custom API integrations to spec, usually for a fixed project price. Rates range from $40/hour (India, Eastern Europe) to $150+/hour for US-based shops.

These firms are good for one-off, specific integrations where you have no standardized connector: a legacy system with a SOAP API that no unified platform covers, or a proprietary enterprise system used by one large customer. Where they fall apart is scale. If you need 20 integrations, you pay to build 20 integrations. Maintenance is on you or requires a retainer. When a provider changes their API, you either have an incident or you are back in a statement of work.

**Unified API platforms**

The third category is software rather than services. A [unified API platform](https://apideck.com/blog/api-aggregator) lets you build to one API and get normalized access to a category of software: accounting, CRM, HRIS, and so on. You write the integration logic once; the platform handles connector maintenance, auth, schema normalization, and error monitoring.

The main players here are Apideck, [Merge](https://apideck.com/blog/top-merge-api-alternatives), Finch, and [Codat](https://apideck.com/blog/codat-alternatives). The pricing model is recurring SaaS rather than billed hours. You are buying infrastructure, not a project.

## Named options by category

If you are actively evaluating, here is a starting map:

**Systems integrators:** Accenture (MuleSoft-certified, global, enterprise-grade), Deloitte (SAP and Salesforce integrations, large-scale transformations), EPAM (API strategy and implementation for mid-to-large enterprise).

**Custom API integration services:** Apriorit (security-first API development, 20+ years, Eastern Europe rates), Simform (India-based, MuleSoft and Azure, broad industry coverage), Asper Brothers (Poland-based, startup focus, tool-agnostic, smaller projects).

**Unified API platforms:** Apideck (200+ connectors, accounting and CRM focus, passthrough architecture, no data storage), Merge (HRIS, ATS, CRM, ticketing, broader category coverage), Finch (employment and HRIS-specific, payroll-heavy use cases), Codat (accounting and commerce, financial data focus, white-glove support).

The right category depends on what you are building, not which company has the best marketing.

## How to decide

The decision comes down to two questions. Is this integration customer-facing or internal? And do you need one integration or many?

For internal integrations (connecting your own tools), you are usually better served by a workflow automation tool like Zapier, Workato, or Make for lighter use cases, or a full [enterprise iPaaS](https://apideck.com/blog/top-embedded-ipaas-solutions) like MuleSoft or Boomi for complex, high-volume internal data flows. Custom dev shops are occasionally the right call for a one-time internal system migration involving a legacy or proprietary system.

For customer-facing integrations, the math changes. You are building infrastructure that your customers will use in production. It needs to be maintained, monitored, and kept current as upstream APIs change. A consulting firm cannot help you with this at product scale. A dev shop in Warsaw will build you the QuickBooks integration, but when Intuit rotates auth scopes (which happened in 2026, forcing a granular OAuth migration across all connected apps), you are the one handling it.

This is where unified API platforms make sense. The integrations your customers need are [accounting](https://apideck.com/blog/accounting-software-integration), CRM, and HRIS: categories that are well-defined and broadly covered. You build once, ship to customers, and the platform handles breaking changes upstream.

The one real limitation of unified APIs is field coverage. Normalized data models cover the common subset across providers. If your product depends on fields that exist only in QuickBooks Online but not in Xero, you will hit the ceiling. Most platforms offer escape hatches (passthrough requests, custom field mapping) but they vary in quality. Check that before you commit.

## Cost comparison

A single custom integration built by a mid-tier dev shop typically runs $15,000-$40,000 for the initial build, depending on complexity. Maintenance, incident response, and adaptation to API changes adds $3,000-$8,000 per integration per year.

At 20 integrations, you are looking at $300,000-$800,000 in initial build costs and $60,000-$160,000 in annual maintenance. These numbers do not include internal engineering time for code review, security review, and production support.

A unified API platform at mid-market pricing runs $1,000-$5,000 per month, covering an entire category of integrations. Even at the high end, that is $60,000 per year for infrastructure that scales to hundreds of connections without proportional cost growth.

The break-even is usually around four to six integrations. Beyond that, the platform wins on economics alone.

| Approach | Build cost per integration | Annual maintenance | At 20 integrations |
|---|---|---|---|
| Custom dev shop | $15,000–$40,000 | $3,000–$8,000 | $300K–$800K build + $60K–$160K/yr |
| Systems integrator | $100K–$500K (project) | Managed retainer | Not designed for this model |
| Unified API platform | None (build once to the platform) | Included | $12K–$60K/yr |

If your team is evaluating Apideck specifically, the 30-day free trial covers all 200+ connectors with no per-call pricing. You can test your actual integration use case before any commercial conversation.

## What consulting services miss

The Accenture-style engagement model treats API integration as a project with a start and an end. But customer-facing integrations do not end. [Xero moved Journals to a paid tier in March 2026](https://apideck.com/blog/xero-scopes). Intuit forced a granular OAuth migration the same year. These events happen continuously, on the upstream provider's schedule, not yours.

Consulting firms that recognize this problem have shifted toward managed service retainers, but those retainers are expensive and slow. A change request through a consulting engagement is not faster than a platform that handles the change automatically.

Custom dev shops have the same problem at smaller scale. You own what they build. Their obligation ends when the project closes.

## Where Apideck fits

Apideck is a unified API platform with 200+ connectors across accounting, CRM, HRIS, and commerce. It is designed for companies building customer-facing integrations: [Vertical SaaS](https://apideck.com/blog/embedded-finance-vertical-saas), [embedded finance](https://apideck.com/blog/what-is-embedded-finance), any product where customers need to connect their own tools to yours.

The architecture is passthrough with no data storage on Apideck's side, which simplifies compliance for products handling financial data or payroll. Vault handles OAuth flows and credential management. An embeddable integration marketplace lets your customers manage their own connections without leaving your app.

BILL and Airbnb use Apideck for production accounting integrations. The free trial is 30 days, covers all connectors, and requires no API-call budget.

## Choosing correctly

If you are a product team shipping integrations to customers and you need coverage across a standard software category, start with a unified API platform. The infrastructure investment is lower, the maintenance burden is off your plate, and you ship faster.

If you have a single complex integration with a proprietary or legacy system that no platform covers, a custom dev shop may be the right call. Define who owns maintenance before you sign. Price the ongoing retainer before the initial build.

If you are an enterprise IT team connecting internal systems at scale, a systems integrator with a platform like MuleSoft makes sense. The costs are real, but so is the scope.

The term "API integration services" does not tell you which of these you are buying. The category of your integrations, the number you need, and who will maintain them in production do.

A guide to the three types of API integration services: systems integrators, custom dev shops, and unified API platforms. With cost comparisons and a decision framework for SaaS and embedded finance teams.

API Integration Services: What They Are and When to Use Them

Spiris is one of Sweden's largest cloud accounting platforms for small and medium-sized businesses. If you are building software for the Swedish market, you will almost certainly encounter it. But before writing a single line of integration code, there is a naming problem worth understanding.

## Spiris, Visma eAccounting, Visma eEkonomi: What Each Name Means

In 2025, Visma Spcs rebranded to Spiris. In Sweden, the product previously called Visma eEkonomi became Bokföring & Fakturering (Bookkeeping & Invoicing in English). In all other markets, the same product still goes by eAccounting. The company was founded in 1984 and has several hundred thousand customers, making it one of Sweden's leading platforms for financial management.

Visma eAccounting runs under different names across markets: eAccounting in Norway and the Netherlands, Bokföring & Fakturering via Spiris in Sweden, and ePasseli in Finland. These are not different products. They share the same underlying API at `eaccountingapi.vismaonline.com`. If a customer tells you they use Visma eEkonomi, Visma Spcs, or Spiris, they are all pointing to the same integration target.

One distinction worth flagging: Visma Administration (also known as Visma SPCS Administration) is a separate, on-premise desktop accounting product that does not share this API. If a customer is running Visma Administration, that is a different integration entirely.

## Spiris API Endpoints: What You Can Read and Write

The Spiris API is REST-based and covers the core accounting data models you would expect from an SME accounting platform. The base URL for all requests is `https://eaccountingapi.vismaonline.com/v2/`. Through the API you can read and write customers and suppliers, sales and purchase invoices, journal entries, VAT codes, articles and products, and fiscal period data.

To fetch a list of customers:

```bash
curl "https://eaccountingapi.vismaonline.com/v2/customers" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

A successful response returns a `Data` array alongside pagination metadata:

```json
{
  "Data": [
    {
      "Id": "3e8f2a1b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
      "Name": "Acme AB",
      "VatNumber": "SE556677889001",
      "EmailAddress": "billing@acme.se",
      "IsPrivatePerson": false
    }
  ],
  "Meta": {
    "TotalNumberOfResults": 143,
    "CurrentPage": 1
  }
}
```

Before writing invoices or journal entries, you need to resolve the VAT codes available in the tenant's account. Each tenant may have a different set depending on their market and configuration:

```bash
curl "https://eaccountingapi.vismaonline.com/v2/vat-codes" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

For a Swedish company, the response will include the three Moms rates:

```json
{
  "Data": [
    { "Id": "MP1", "Name": "Moms 25%", "VatPercent": 25.0 },
    { "Id": "MP2", "Name": "Moms 12%", "VatPercent": 12.0 },
    { "Id": "MP3", "Name": "Moms 6%",  "VatPercent": 6.0  }
  ]
}
```

These `Id` values (`MP1`, `MP2`, `MP3`) are what you reference in invoice rows. Dutch and Norwegian tenants will return different VAT code IDs, so never hardcode them.

## Creating a Sales Invoice

Creating a sales invoice requires a `CustomerId` (the GUID from the customer record), a valid `VatPercent` that matches a code in the tenant's account, and a date in ISO 8601 format. A minimal invoice creation request looks like this:

```bash
curl -X POST "https://eaccountingapi.vismaonline.com/v2/customerinvoices" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "CustomerId": "3e8f2a1b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
    "InvoiceDate": "2026-04-23",
    "DueDate": "2026-05-23",
    "YourReference": "PO-1234",
    "Rows": [
      {
        "Text": "Software license Q2 2026",
        "Quantity": 1,
        "UnitPrice": 1200.00,
        "VatPercent": 25
      }
    ]
  }'
```

For Swedish invoices involving ROT or RUT deductions, the invoice row requires three additional fields: `TypeOfVatFreeReduction` (`ROT` or `RUT`), `HousingPropertyDesignation` (the property reference), and `ReducedInvoicedAmount` (the deduction amount). Missing any of these on a ROT/RUT invoice will cause a validation error.

To read journal entries for a specific date range:

```bash
curl "https://eaccountingapi.vismaonline.com/v2/journal/entries?fromDate=2026-01-01&toDate=2026-03-31" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## The Spiris Payroll API

The Spiris developer portal also exposes a Payroll API alongside the accounting one, with its own dedicated API reference at developer.vismaonline.com. Both APIs share the same OAuth identity server at `identity.vismaonline.com`, which means the same access token covers both as long as the payroll-specific scopes are included in the authorization request your customer approves.

For products that need to read salary data, payroll runs, or employee records alongside invoicing and accounting data, this matters: you can build a single connect flow that requests both accounting and payroll scopes, rather than asking your customers to authorize twice. The trade-off is that requesting a wider scope set upfront increases the permissions your app is asking for during onboarding, which is worth thinking about from a conversion perspective.

## Authentication and OAuth 2.0 Scopes

Applications connect to the Spiris/eAccounting API using OAuth 2.0. The flow is initiated by a user clicking a connect button in your application, and the result is a token your application uses to access protected resources on behalf of that user.

The authorization request directs your customer to the Visma identity server:

```
https://identity.vismaonline.com/connect/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &response_type=code
  &scope=ea:sales ea:purchase ea:accounting offline_access
  &state=RANDOM_STATE_VALUE
```

Once the user approves and you receive the authorization code, exchange it for tokens:

```bash
curl -X POST "https://identity.vismaonline.com/connect/token" \
  -H "Authorization: Basic BASE64_ENCODED_CLIENT_ID_AND_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=AUTH_CODE&redirect_uri=YOUR_REDIRECT_URI"
```

The response includes an access token (valid for 3600 seconds) and a refresh token:

```json
{
  "access_token": "eyJ...",
  "expires_in": 3600,
  "token_type": "Bearer",
  "refresh_token": "abc123..."
}
```

The `BASE64_ENCODED_CLIENT_ID_AND_SECRET` in the Authorization header is `base64(client_id:client_secret)`. Store the refresh token per tenant. When the access token expires, exchange the refresh token for a new one:

```bash
curl -X POST "https://identity.vismaonline.com/connect/token" \
  -H "Authorization: Basic BASE64_ENCODED_CLIENT_ID_AND_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=STORED_REFRESH_TOKEN"
```

The per-resource scope model is where most teams get stuck. Every resource area has its own scope: `ea:sales` for sales invoices, `ea:purchase` for purchase invoices, `ea:accounting` for journal entries and accounts. Missing a scope in the authorization request produces authorization errors on those endpoints rather than empty results, and the only fix is to have your customer re-authorize. Include `offline_access` to receive a refresh token at all.

From the end-user's perspective, the connect flow ends at a scope approval screen on `identity.vismaonline.com`. That screen lists every scope your application has requested. Scopes that look overly broad create drop-off, so request only what your integration actually needs.

## Pagination and Rate Limits

Collection endpoints return 50 results per page by default. For any customer with more than 50 records on an endpoint, requests without explicit pagination will silently ignore everything after the first page. To paginate correctly, pass `page` and `limit` as query parameters:

```bash
curl "https://eaccountingapi.vismaonline.com/v2/customerinvoices?page=2&limit=100" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

The `Meta` object in the response tells you the total record count so you can calculate how many pages to fetch:

```json
{
  "Meta": {
    "TotalNumberOfResults": 312,
    "CurrentPage": 2
  }
}
```

With 312 invoices and a limit of 100, that is four requests (pages 1 through 4) to retrieve all records. Build this loop into every collection sync from the start rather than adding it later when a customer complains about missing data.

The rate limit is 600 requests per minute per client and endpoint. When you exceed it, the API returns:

```json
{
  "ErrorCode": 4010,
  "DeveloperErrorMessage": "API calls quota exceeded! maximum admitted 600 per Minute. Try again in 55 seconds."
}
```

Batch reads where possible. Fetching 100 records per page instead of 50 halves the number of requests for a full sync.

## Sweden-Specific Requirements: BAS Accounts, Moms VAT, and ROT/RUT

This is where the Swedish implementation diverges from eAccounting in Norway and the Netherlands, and where assumptions built on other markets will fail.

Swedish companies use the BAS chart of accounts (BAS-kontoplanen). Account numbers follow BAS conventions and differ structurally from Dutch or Norwegian account setups. Before writing any journal entries, retrieve the tenant's chart of accounts to confirm the account numbers you need exist:

```bash
curl "https://eaccountingapi.vismaonline.com/v2/accounts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

Swedish VAT is called Moms and has three rates: 25%, 12%, and 6%, each mapping to specific VatCodes in the API, with reporting obligations to Skatteverket. Always fetch VAT codes dynamically rather than hardcoding them, since code IDs vary across tenants and markets.

ROT and RUT deductions require additional fields on invoice rows. The invoice creation example above shows the base structure. For a ROT invoice on a construction job, the row would also include:

```json
{
  "Text": "Roof repair labour",
  "Quantity": 8,
  "UnitPrice": 650.00,
  "VatPercent": 25,
  "TypeOfVatFreeReduction": "ROT",
  "HousingPropertyDesignation": "STOCKHOLM VASASTADEN 1:23",
  "ReducedInvoicedAmount": 2600.00
}
```

These fields are Sweden-only. The Norwegian and Dutch eAccounting API will reject invoice rows that include them.

## Getting Started with the Spiris Partner Programme

To make authorized requests, you register as a partner on the Visma Developer Portal at developer.vismaonline.com. Registration gives you a client ID, client secret, redirect URI registration, and access to a sandbox environment that includes a test company. Spending time in the sandbox creating invoices and suppliers before writing production code pays off. It gives you a concrete picture of what your customers' data actually looks like before you design your data mapping.

Registering as a partner does more than unlock API access. Once your integration is reviewed and approved, it can be listed in the Spiris partner marketplace, which is visible to Spiris customers browsing for integrations from inside the platform. For software companies targeting the Swedish SME market, this is a meaningful distribution channel: your product appears in front of users who are actively looking for tools that connect to their accounting system. It is worth factoring into your go-to-market plan alongside the technical work.

## What Building a Spiris Integration Actually Costs

Building a direct Spiris integration means managing per-resource OAuth scopes, handling 60-minute token expiry with silent refresh across every connected tenant, writing pagination for every collection endpoint, resolving tenant-specific account and VAT code references before any write operation, and handling Swedish invoice fields for ROT/RUT. That is before error handling, retry logic, and ongoing maintenance as the API evolves.

For most companies building in the Nordic market, Spiris is also one of several accounting platforms you need. Adding eAccounting for Norwegian customers or ePasseli for Finnish ones means repeating most of this across separate integrations.

Apideck's unified accounting API covers the broader Visma eAccounting family and other Nordic and European accounting platforms through a single integration. Normalized data models, managed OAuth flows, and pagination handling come with each connector.

**Note: Apideck's Spiris connector is currently in development.** [Sign up for early access](https://app.apideck.com/signup) to be notified when it launches.

---

## FAQ: Spiris and Visma eAccounting API

**Is Spiris the same as Visma eAccounting?**
Yes. Spiris is the rebranded name for Visma Spcs, the company that develops and maintains the eAccounting product in Sweden. In Sweden the product is now called Bokföring & Fakturering. In Norway and the Netherlands it is still called eAccounting. All versions share the same API at `eaccountingapi.vismaonline.com`.

**What happened to Visma eEkonomi?**
Visma eEkonomi was the Swedish-market name for the product before the 2025 rebrand. It is now called Bokföring & Fakturering under the Spiris brand. The API is unchanged — no code updates are needed if you were already integrated.

**What is the difference between Spiris and Visma Administration?**
Visma Administration is a separate on-premise desktop accounting product. It does not use the same API as Spiris/eAccounting. If your customer uses Visma Administration, that requires a different integration approach.

**Does the Spiris API work for Norwegian and Dutch customers too?**
Yes. The same API endpoint covers eAccounting in Norway and the Netherlands. The authentication flow, rate limits, and pagination model are identical across markets. The main differences are country-specific data: VAT codes, chart of accounts structure, and invoice fields vary by market.

**Does Spiris have a Payroll API?**
Yes. The Payroll API is available through the same Visma Developer Portal and shares the same OAuth identity server as the accounting API. If your application needs payroll data alongside accounting data, you can request both scope sets in a single authorization flow.

**Where do I register to get API access to Spiris?**
At developer.vismaonline.com under the Spiris Partner Programme. You receive a client ID, client secret, redirect URI registration, and sandbox access on signup.

Spiris (formerly Visma eAccounting) API integration guide for developers. Covers OAuth 2.0 scopes, rate limits, pagination, ROT/RUT invoice handling, and BAS accounts in Sweden. Updated 2026.

Spiris (Visma eAccounting) API Integration Guide (2026)

Every SaaS company in your stack now has an MCP server. Stripe ships one. Notion ships one. QuickBooks ships one. GitHub ships one. If you checked the MCP registry this week, you'd find thousands of them. It's a gold rush.

This is almost exactly what happened with REST APIs a decade ago. Every SaaS rushed to ship an API, and developers celebrated. Then they tried to build a product that talked to fifteen of those APIs, and the celebration stopped. Every API had its own auth model, its own naming conventions, its own error codes. Building against fifteen of them meant writing fifteen integrations. [A unified API](https://www.apideck.com/blog/what-is-a-unified-api) was the answer to that problem: one endpoint, one auth standard, normalized data across providers in the same category.

The same fragmentation is now happening one layer up, at the MCP layer.

## What is an MCP server?

An MCP server is a lightweight program that exposes tools and data to AI models through the [Model Context Protocol](https://www.apideck.com/blog/a-primer-on-the-model-context-protocol), an open standard Anthropic released in November 2024. Where a traditional API serves a developer making deliberate HTTP calls, an MCP server serves an AI agent that is discovering and calling capabilities autonomously.

The protocol defines how an agent finds out what tools are available, how to call them, and what parameters they accept — all through a standard JSON-RPC interface. No custom connector. No bespoke integration code. The agent just asks what the server can do, and the server tells it.

The protocol spread fast. OpenAI adopted it across its Agents SDK in March 2025. Google DeepMind confirmed support the following month. By December 2025, Anthropic had donated MCP to the Agentic AI Foundation under the Linux Foundation, with OpenAI, Block, AWS, and Google as supporting members. The SDK is now pulling 97 million monthly downloads across Python and TypeScript. MCP won the protocol war before most people realized there was one.

## The fragmentation problem at the MCP layer

When you build an AI agent that needs to work with accounting data, you have a choice. You can connect it to the QuickBooks MCP server. Or the Xero MCP server. Or the FreshBooks one. Each of those servers exposes a similar concept (invoices, customers, payments) under different tool names, different schemas, and different authentication flows.

`accounting-quickbooks::get_invoices` returns a different shape than `xero-mcp::list_invoices`. Both return invoices. Your agent has to understand both, declare both as tools, and handle both schemas. Now multiply that by 10 accounting systems your customers might use. You've rebuilt the N×M integration problem that unified APIs were designed to kill, except now it lives inside your AI agent's context window.

This matters practically. Every tool declaration your agent loads consumes tokens. If you connect to 10 separate MCP servers exposing similar capabilities, you're burning context budget on redundant declarations before your agent has done anything useful. [MCP tool definitions can burn 55,000+ tokens](https://www.apideck.com/blog/mcp-server-eating-context-window-cli-alternative) before an agent processes a single user message. For complex agentic workflows, that overhead compounds quickly.

## What a unified MCP server is

A unified MCP server does for AI agents what a unified API does for developers: it aggregates multiple providers in the same category behind a single, normalized interface.

Your agent declares `accounting::list_invoices` once. The unified MCP server routes that call to QuickBooks, Xero, FreshBooks, Sage, or whichever system your customer has connected. The tool signature stays the same. The response schema stays the same. Your agent doesn't know or care which accounting system is on the other side.

This is what Apideck built. We generate our [accounting MCP server](https://www.apideck.com/mcp-server) directly from our OpenAPI spec, which means every endpoint in our unified accounting API is automatically available as an MCP tool. That's 229 tools today, covering invoices, customers, payments, journals, accounts, and more, across 30+ accounting systems. When a new connector goes live in the API layer, the MCP server picks it up automatically.

The underlying architecture matters here. A unified MCP server isn't a proxy that translates between incompatible schemas at runtime. The normalization happens at the data model layer, before the MCP layer exists. Apideck's accounting data model defines what a Customer object looks like regardless of whether the source is QuickBooks or Oracle NetSuite. The MCP server exposes that already-normalized data as callable tools.

## Who needs a unified MCP server

If you're building an AI agent that touches financial data, you're going to hit this problem. The customers using your product don't all use the same accounting system, the same ERP, or the same payroll tool. An AI agent that only speaks QuickBooks can't serve a customer on Xero. An AI agent that speaks all of them through separate MCP servers is carrying unnecessary weight in every conversation.

[Vertical SaaS companies](https://www.apideck.com/industries/vertical-saas) are the clearest fit. You've built a product for a specific industry, your customers use a mix of tools, and you're now adding AI features on top. A unified MCP server means your AI layer works against a single interface regardless of what's in the customer's stack. The integration complexity shifts from your AI layer to your integration layer, which is where it belongs.

[Embedded finance companies](https://www.apideck.com/industries/fintech) land in the same place. If you're building a lending product, an expense management tool, or a treasury automation layer, your AI agents need to read from whatever accounting system your customer runs. Connecting to 20 separate MCP servers to cover your customer base is not a viable architecture.

## Teams building AI agents

There's a third audience growing fast: developers building AI agents as standalone products, not as features inside existing SaaS.

A finance agent that reconciles transactions and flags anomalies needs live accounting data. So does a spend analysis agent, an invoice processing agent, or an agent that monitors cash flow across multiple entities. These agents don't belong to a vertical SaaS product or a lending platform. They're the product.

For teams building these agents, the integration problem arrives on day one. The agent has to work with whatever accounting system the end customer uses. That means the developer either builds connectors to QuickBooks, Xero, Sage, and a dozen other platforms before writing a line of agent logic, or they plug into a unified MCP server that handles all of them behind one interface.

The second option does something else: it keeps system prompts clean. When the schema is consistent across providers, the prompt doesn't need to say "if the customer uses QuickBooks, the invoice object looks like X; if they use Xero, it looks like Y." One schema covers every provider the customer might use.

## The tradeoff worth understanding

There are now thousands of MCP servers in public registries. Most are point solutions: one server per product, maintained by that product's team. Quality is uneven and schemas differ. Update cadence is another variable. For an AI agent that needs to reason across multiple tools in the same category, that fragmentation is real overhead.

A unified MCP server gives you normalized tools and a predictable data model. The tradeoff is that you're working within a common schema, which means provider-specific features outside that schema require a direct connection. That makes sense for common workflows like reading invoices or syncing payment status, and less sense for workflows that require deep, provider-specific functionality.

The parallel to unified APIs is instructive. Developers who needed Stripe-specific features used the Stripe API directly. Developers who needed to work across multiple payment processors reached for a unified layer. [MCP will settle into the same pattern](https://www.apideck.com/blog/mcp-vs-api): unified for the common case, direct for the edge case.

For AI agents handling financial workflows across customers with mixed accounting stacks, the common case is almost always the right starting point.

## Frequently asked questions

**What is the difference between an MCP server and a unified MCP server?**
A standard MCP server connects an AI agent to one specific tool or provider. A unified MCP server connects an AI agent to multiple providers in the same category through one normalized interface. The agent calls the same tool regardless of which underlying provider the customer uses.

**What is MCP used for in accounting?**
In accounting, an MCP server lets an AI agent call tools like `list_invoices`, `create_payment`, or `get_customer` directly against a live accounting system. A unified accounting MCP server means those same calls work across QuickBooks, Xero, Sage, NetSuite, and 30+ other systems without schema changes.

**Is a unified MCP server the same as a unified API?**
They solve the same category of problem at different layers. A [unified API](https://www.apideck.com/blog/what-is-a-unified-api) normalizes provider integrations for developers writing code. A unified MCP server normalizes them for AI agents discovering and calling tools. Apideck's unified MCP server is generated directly from the unified API's OpenAPI spec, so the same normalization applies to both.

A unified MCP server aggregates multiple providers in the same category behind one normalized AI interface. Learn what MCP servers are, why fragmentation is a problem, and how Apideck solves it.

What is a Unified MCP Server?

### NetSuite Customization and ERP Extensions: SuiteScript, Business Central AL, SAP BTP, Acumatica C#, and Sage Intacct Platform Services.

Every ERP vendor has its own answer to the same question: how should third-party developers add functionality without breaking upgrades? The answers vary significantly in tooling and language, but the underlying tension is consistent. Custom code that runs inside the ERP core couples tightly to the ERP's release cycle. Custom code that runs outside connects through APIs and is more stable over time.

This post covers the four platforms where this tradeoff plays out most frequently for Banks, Fintechs and vertical SaaS teams.

## NetSuite

NetSuite's extension framework is SuiteCloud. The primary development language is SuiteScript 2.1, which is JavaScript-based. Extensions run inside NetSuite's infrastructure under strict resource limits: script execution time is capped and memory ceilings affect batch processing. A SuiteApp that passes sandbox testing can fail in production under real transaction volume.

SuiteScript provides several script types for different contexts. User Event scripts fire on record load, validate, and save. Client Scripts run in the browser and respond to field changes. Suitelets are full server-side pages hosted on NetSuite's domain, accessible via URL and iFrameable into other views. Portlets render as panels on the NetSuite dashboard.

A concrete example: a revenue operations ISV might build a Suitelet that shows a customer's payment history alongside a real-time credit limit recommendation from an external risk model. The Suitelet fetches transaction data via `nlapiSearchRecord`, calls the external risk API, and renders an HTML table inside the NetSuite interface. Sales reps access it via a button injected into the Customer record through a Client Script. The whole thing deploys as a SuiteApp through SuiteCloud Development Framework (SDF) and can be listed on the SuiteApp Marketplace.

For API access, [NetSuite](https://www.apideck.com/connectors/netsuite) uses [Token-Based Authentication (TBA)](/blog/integrating-with-the-netsuite-rest-api) for machine-to-machine calls and OAuth 2.0 for user-facing apps. SuiteCloud 2026.1 (February 2026) brought REST web services to functional parity with SOAP, which had previously been required for certain advanced operations. For SuiteApps that expose NetSuite data to external systems, REST-first is now a complete option without the SOAP dependency.

## Microsoft Dynamics 365 Business Central

[Business Central](https://www.apideck.com/connectors/microsoft-dynamics-365-business-central)'s extension model runs on AL (Application Language), a proprietary language Microsoft introduced when it moved the platform to the cloud. AL is the only supported path for customizing BC logic. You write it in Visual Studio Code with the AL Language extension, publish apps to a sandbox or production tenant, and distribute through Microsoft's AppSource marketplace for cloud deployments.

AL uses an event-based pattern: the framework publishes events at key points in standard business processes, and your extension subscribes to them. Adding fields to a table requires a table extension object; modifying a page requires a page extension. Business logic lives in codeunits. Subscribing to `OnAfterPostSalesOrder` to trigger a third-party fulfillment workflow is a common pattern, and it's upgrade-safe because extensions can't modify base objects directly, only layer on top of them.

For UI extensions that go beyond field injection, BC offers control add-ins. A control add-in is declared in AL but renders as an iframe hosting JavaScript and HTML. It communicates back to AL via the `Microsoft.Dynamics.NAV.InvokeExtensibilityMethod` API. A concrete example: an ISV building a logistics product might embed a live shipment tracking map inside the Sales Order page using a control add-in, pulling carrier API data and rendering it as an interactive element alongside the native BC fields. The iframe boundary keeps the JavaScript isolated; the AL callback handles any state updates back to the record.

Microsoft ships BC updates monthly. One practical consequence of the event subscription model is that if Microsoft removes an event between releases, subscriber code fails silently until you test against the next sandbox. Testing each monthly release in a development tenant before it goes live is not optional for customer-facing BC extensions. For the full API authentication flows and endpoint patterns, see our [Business Central API integration guide](/blog/microsoft-dynamics-business-central-api-integration-guide-2025).

## Sage Intacct

[Sage Intacct](https://www.apideck.com/connectors/sage-intacct) splits its extensibility model into two distinct layers. External integrations use Web Services, which moved from its XML-only API to a REST API in general availability as of Intacct's 2025 Release 1 (February 2025). For extensions that live inside the Intacct interface, the tool is Platform Services.

Platform Services lets developers create custom objects (with their own fields and relationships) and build full applications with menus and workflows. Behavior can be injected via JavaScript using the AJAX SDK. A Platform application groups custom objects and navigation menus into a self-contained mini-app inside Intacct. The entire application definition exports as XML, making it portable across Intacct companies.

A practical example: a professional services firm might use Platform Services to build a project milestone tracker. The developer creates a custom object that links to Intacct's native Project and AP Bill objects. When a milestone is approved, a trigger fires an API call to create a vendor bill. The forms and approval workflow live entirely within Platform Services; the bill creation uses merge fields to pull milestone data into the standard AP Bill form.

The AJAX SDK has a notable constraint: Sage Intacct explicitly warns against manipulating the standard Intacct DOM (hiding fields with jQuery, for example). Any UI behavior built against undocumented internal elements breaks when Intacct updates its interface. The AJAX Gateway is the only supported path for page scripts that need to call Intacct's back end. This is a narrower surface than many developers expect going in.

Sage also announced in November 2025 that third-party AI agents can now be embedded in the Sage Copilot interface, with an MCP server built on top of the Intacct REST API. That opens a different category of extension that doesn't require Platform Services at all and may be the easier path for read-heavy use cases.

![Sage Embedded Platform Services](//images.ctfassets.net/d6o5ai4eeewt/2Or3K16JUteb8T9KfmmRgE/dc11664dc7261487b21ffb0364785476/Screenshot_2026-04-22_at_23.28.13.png)

## Acumatica

Acumatica's customization model gives developers more direct access to the ERP's internals than the other three platforms here. Customizations are written in C# and packaged into Customization Projects, which can be exported and deployed across environments. The Customization Project Editor in the Acumatica UI handles screen modifications alongside the C# code.

The pattern: Acumatica's data objects are declared as DAC (Data Access Class) classes in C#. Business logic lives in Graph classes. An extension subclasses the relevant DAC or Graph, adding or overriding fields and methods without touching the base code. To add an insurance expiration date to the Vendor screen, a developer creates a `VendorExtension : PXCacheExtension<Vendor>` class for the field, and a `VendorMaintExtension : PXGraphExtension<VendorMaint>` for validation logic. The Customization Project wraps both for deployment.

For UI, Acumatica shipped a finalized Modern UI in TypeScript and HTML as of 2025 R2 (released September 2025). Extensions to existing Acumatica screens now require creating matching `.ts` and `.html` files in the `extensions` folder under the screen directory. As of 2025 R2, screen personalizations can be included directly in Customization Projects, which lets ISVs guarantee consistent layouts across environments during deployment.

A concrete example from an ISV: a construction SaaS company might add a compliance status panel to the Subcontract screen, pulling insurance and license data from an external API. The Graph extension handles the data fetch on screen load, while the TypeScript file renders the panel in the Modern UI. The Customization Project packages both for deployment to client tenants.

One thing to plan for: as of late 2025, ISVs with multiple Customization Projects targeting the same screen have run into conflicts. Acumatica's export-to-development function overwrites files from the development folder, which affects teams managing several products for the same customer. This isn't a blocker, but it requires explicit project management.

## SAP

SAP sells two products under the same brand that have almost nothing in common from an extensibility standpoint: Business One (B1), aimed at SMBs, and S/4HANA, aimed at mid-market and enterprise. The toolchain, deployment model, and API surface differ enough that treating them as the same platform is a common mistake for ISVs trying to cover both.

**SAP Business One**

B1's extension model uses the SDK, which exposes two APIs for different contexts. The DI API (Data Interface API) is a COM-based interface that runs on the B1 client or application server, giving add-ons full access to business objects. The Service Layer is a REST API that runs on HANA-based B1 deployments (9.1 PL09 and later) and is the recommended path for web-based or multi-threaded integrations that don't require the full depth of the DI API. For new integrations, Service Layer is generally simpler; DI API remains necessary when you need objects the Service Layer doesn't yet expose.

For UI extensions inside the B1 web client specifically, SAP added a UI API extension framework using JavaScript, TypeScript, and SAPUI5. Development happens in VS Code with a dedicated plugin and a Chrome/Edge-based Web Client Inspector for debugging. A UI API extension targets a specific view in the web client (defined by a JSON layout file) and uses a JavaScript controller for logic. A concrete example: an ISV might add a custom panel to the Business Partner Detail view that surfaces a customer's credit insurance status from an external provider. The JSON file positions the new UI element; the controller fetches and displays the data when the panel loads.

B1 does not use SAP BTP in the same way S/4HANA does. BTP integration is possible but not the primary extensibility model for B1 partners. Most B1 ISV add-ons still ship as traditional SDK-based packages installed on the B1 server.

**SAP S/4HANA**

S/4HANA's extensibility model follows SAP's clean core framework, which separates on-stack from side-by-side extensions. On-stack extensions run within S/4HANA itself, written in ABAP Cloud using only publicly released APIs. Side-by-side extensions run on SAP BTP and communicate with S/4HANA through APIs and events.

SAP formalizes this in a four-level compliance model (A through D). Level A extensions use only released, stable APIs on both paths. Level C and D extensions access internal objects and carry explicit upgrade risk. For ISVs building multi-tenant SaaS on S/4HANA, SAP's August 2025 extensibility documentation positions BTP side-by-side as the preferred architecture: it keeps the extension deployment decoupled from the ERP core, so the ISV manages its own release cadence without waiting on SAP upgrade windows.

For UI work on S/4HANA, the options split by deployment model. Key-user extensibility lets non-developers add custom fields to standard Fiori apps without code. Developer extensibility goes further with SAPUI5 adaptation projects built in SAP Business Application Studio, which overlay changes onto existing Fiori apps without modifying their base code. New standalone apps can be built with SAPUI5/Fiori Elements and hosted either on-stack in the Fiori Launchpad or on BTP.

A concrete example for S/4HANA: a manufacturing ISV might build a quality inspection panel embedded alongside the standard Production Order screen. The panel pulls sensor data from an IoT system via a BTP integration, renders a Fiori-based status indicator in the Production Order screen, and writes inspection results back to S/4HANA through an OData service. The application runs on BTP Cloud Foundry, connects to S/4HANA through a communication arrangement, and is distributed to customers through the SAP Store.

The practical difference between B1 and S/4HANA for an ISV covering both: B1 extensions typically ship as on-premise or hosted SDK packages, while S/4HANA extensions for cloud deployments ship as BTP applications certified through the SAP Store. Different distribution model, different technical stack.

## What breaks

Each platform has its characteristic failure mode.

In SAP, the failure mode depends on which product you're targeting. For B1, the DI API's COM dependency limits add-ons to Windows and requires the B1 client to be running, which creates problems in web-only or headless integration scenarios. The Service Layer is cleaner but doesn't cover all DI API objects, so gaps force a context switch back to the older interface mid-project. For S/4HANA, the risk is API scope: if an extension needs access to an internal object not covered by a released API, it falls into Level C or D on the clean core model and carries explicit upgrade risk when SAP ships updates.

In Business Central, the risk is event volatility. Microsoft adds and deprecates AL events as the base application evolves across monthly releases. A subscriber function becomes a runtime error if the event it depends on is removed. This makes continuous testing against the next monthly release non-negotiable for any BC extension in active customer use.

In Sage Intacct, the constraint is scope. Platform Services handles custom objects well, but complex UI injection hits the sandbox limits quickly. Scripts that manipulate the standard DOM break on Intacct's quarterly releases without warning, since those changes are outside the supported API surface.

In Acumatica, the Modern UI transition introduced a new class of migration work. ISVs with ASPX-based screen customizations are rebuilding them in TypeScript for the Modern UI. The new extension file structure requires precision, and multi-project conflicts on shared screens require coordination that didn't exist in the older model.

In NetSuite, governor limits are the consistent friction point. The script execution time cap hits Suitelets that make external API calls with variable latency. Scheduled scripts queue behind other jobs in the account. These limits are fixed and don't scale with a customer's transaction volume.

## What "embedded" means at the API layer

The phrase "embedded app" has two meanings that frequently get conflated. In the ERP vendor context, an embedded app is one that runs within the ERP's infrastructure and is distributed through its marketplace. In the SaaS product context, an embedded app is a product experience that lives inside a customer's workflow without requiring them to leave your tool.

Both definitions are valid. They address different problems. The ERP vendor meaning matters when you're building for a single ERP and care about the vendor's distribution channel. The SaaS product meaning matters when you're building across ERPs and want your product to function consistently regardless of which ERP the customer runs.

SAP's August 2025 extensibility documentation describes side-by-side on BTP as the preferred path for ISV partners building multi-tenant SaaS, precisely because it decouples deployment and lets the ISV manage its own release cadence. That matches how most SaaS companies want to operate: own the infrastructure and release schedule, treating the ERP as a data source rather than a runtime environment.

Most extension projects eventually hit a point where the two definitions need to coexist. A vertical SaaS product might embed a lightweight UI extension inside NetSuite to surface its own data in context, while the bulk of data integration runs through a normalized API layer that also handles the customer's other accounting systems. The extension provides presence inside the ERP; the API layer provides breadth. Which of those two problems you need to solve first is the decision worth making explicitly before you pick a toolchain.

## Building for multiple ERPs

For internal IT teams configuring a single ERP instance, the per-platform toolchain is the only path. For SaaS companies whose product needs to work across these four ERPs, maintaining native extensions per platform becomes an engineering capacity problem. No two of these platforms share a development language or deployment model.

The practical alternative is to build your product's interface outside those frameworks and use APIs for data exchange. Your product handles its own workflows; the ERP handles ERP-native work. For operations that need normalized access to financial data (invoices, customers, and journal entries) across these platforms, a [unified accounting API](https://www.apideck.com/accounting-api) layer collapses the per-platform API work into a single schema.

Native embedded extensions still have a clear role. When your product genuinely needs to live inside the ERP's UI, building a native extension for that specific ERP is the right call. The decision is about scope: if "embedded" means your UI inside a single ERP, native extensions make sense. If "embedded" means your product functioning consistently regardless of which accounting system the customer uses, a [normalized API layer](https://www.apideck.com/erp-api) is cheaper to maintain long-term.

Most ISV teams end up with a hybrid: lightweight native extensions for presence inside one or two priority ERPs, and a [unified API integration](https://www.apideck.com/accounting-api) for data sync across the rest.

A developer guide to building extensions, embedded apps, and UI customizations in NetSuite (SuiteScript), Business Central (AL), SAP (BTP/B1 SDK), Acumatica (C#), and Sage Intacct (Platform Services).

How to Build ERP Extensions: A Developer Guide to NetSuite, SAP, Business Central, Acumatica, and Sage Intacct

Most accounting integrations start the same way. A developer opens the QuickBooks API docs, reads through the OAuth 2.0 flow, finds out there are seventeen different account types, realizes that Xero uses a completely different data model, and spends the next two weeks writing plumbing that will need to be rewritten every time a new accounting platform gets added to the roadmap.

Claude Code changes how this work gets done. Not because it writes boilerplate faster (though it does), but because the combination of agentic coding, MCP tool access, and unified APIs removes entire categories of the problem. This post walks through four ways to build [accounting integrations](https://apideck.com/accounting-api): calling platform APIs directly, connecting via the QuickBooks MCP server, connecting via the Apideck MCP server, and using Apideck's unified accounting API for production programmatic integrations.

## Direct API: QuickBooks as a starting point

The direct approach is the right choice when you are building against a single accounting platform and want full control over the data model. Claude Code handles the OAuth dance, the pagination logic, and the error handling without you having to think through each step.

Here is what a working Claude Code session looks like when you want to create an invoice in QuickBooks Online:

```bash
claude "Write a Node.js function that authenticates with QuickBooks Online using OAuth 2.0 and creates an invoice for a customer. Use the intuit-oauth and node-quickbooks packages. The invoice should accept customer ID, line items with amount and description, and a due date. Handle token refresh automatically."
```

Claude Code will produce something close to this:

```javascript
const OAuthClient = require('intuit-oauth');
const QuickBooks = require('node-quickbooks');

const oauthClient = new OAuthClient({
  clientId: process.env.QBO_CLIENT_ID,
  clientSecret: process.env.QBO_CLIENT_SECRET,
  environment: 'production',
  redirectUri: process.env.QBO_REDIRECT_URI,
});

async function createInvoice({ customerId, lineItems, dueDate, realmId, token }) {
  if (oauthClient.isAccessTokenValid() === false) {
    const authResponse = await oauthClient.refreshUsingToken(token.refresh_token);
    token = authResponse.getJson();
  }

  const qbo = new QuickBooks(
    process.env.QBO_CLIENT_ID,
    process.env.QBO_CLIENT_SECRET,
    token.access_token,
    false,
    realmId,
    true,
    false,
    null,
    '2.0',
    token.refresh_token
  );

  const invoice = {
    CustomerRef: { value: customerId },
    DueDate: dueDate,
    Line: lineItems.map((item, index) => ({
      Id: String(index + 1),
      LineNum: index + 1,
      Amount: item.amount,
      DetailType: 'SalesItemLineDetail',
      SalesItemLineDetail: {
        ItemRef: { value: '1', name: 'Services' },
        UnitPrice: item.amount,
        Qty: 1,
        TaxCodeRef: { value: 'NON' },
      },
      Description: item.description,
    })),
  };

  return new Promise((resolve, reject) => {
    qbo.createInvoice(invoice, (err, result) => {
      if (err) reject(err);
      else resolve(result);
    });
  });
}
```

This works. But now you need the same functionality for [Xero](/connectors/xero). Xero's invoice creation endpoint uses `Invoices` (plural), the line item structure is different, and the authentication token exchange follows a different PKCE flow. Claude Code can write that version too, but now you have two codepaths to maintain and two different webhook parsers for the same business event.

That maintenance cost compounds. If you add Sage, FreshBooks, or NetSuite, you are not just adding connectors. You are adding three separate mental models for what an "invoice" or a "bill" means, and the divergence grows with every platform.

## Via QuickBooks' own MCP server

If your integration only needs to cover [QuickBooks Online](/connectors/quickbooks), Intuit's own MCP server is the most direct path. They published `intuit/quickbooks-online-mcp-server` on GitHub, which covers 143 tools across 29 entity types with full CRUD operations, plus 11 financial reports including Balance Sheet, P&L, and Cash Flow.

Clone and build it first:

```bash
git clone https://github.com/intuit/quickbooks-online-mcp-server.git
cd quickbooks-online-mcp-server
npm install && npm run build
```

Then register it in Claude Code via `.claude.json`:

```json
{
  "mcpServers": {
    "quickbooks": {
      "command": "node",
      "args": ["path/to/quickbooks-online-mcp-server/dist/index.js"],
      "env": {
        "QUICKBOOKS_CLIENT_ID": "your_client_id",
        "QUICKBOOKS_CLIENT_SECRET": "your_client_secret",
        "QUICKBOOKS_REFRESH_TOKEN": "your_refresh_token",
        "QUICKBOOKS_REALM_ID": "your_realm_id",
        "QUICKBOOKS_ENVIRONMENT": "sandbox"
      }
    }
  }
}
```

**A note on auth.** The `QUICKBOOKS_REFRESH_TOKEN` value is not something the MCP server generates for you. You get it by completing the OAuth 2.0 authorization flow once, either through Intuit's developer portal or your own callback endpoint. QBO access tokens expire after one hour; the server handles rotation automatically from there. What you are responsible for is storing the latest refresh token after each rotation, since QBO invalidates the previous one on every exchange. For personal dev tooling, the `.env` approach above is fine. For a product where each of your customers connects their own QBO account, you need a backend that captures per-user refresh tokens, stores them, and injects the right one at session time rather than using a shared env var.

Once registered, Claude Code has live access to your QBO company data:

```bash
claude "Using the QuickBooks MCP, pull all open invoices, identify customers with more than $10,000 outstanding, and generate a collections priority report in markdown."
```

Or inside a development session:

```bash
claude "Read the chart of accounts from the QuickBooks MCP and scaffold a TypeScript module that maps each account to our internal ledger category enum. Write tests for the mapping logic."
```

The tradeoff is that this server runs as a local stdio process, tied to a single QBO company per session. For a product where users connect different accounting platforms, you need a different approach.

## Via Apideck MCP server: multi-platform agentic access

The QuickBooks MCP server covers one platform per process. If your agent needs to work across whatever accounting system a given user has connected — QuickBooks for one customer, Xero for another, Sage for a third — you need a different MCP layer.

Apideck's [Unified MCP server](https://www.apideck.com/mcp-server) runs over HTTP transport and routes each tool call to the correct platform based on the consumer ID you pass in the headers. Register it in Claude Code:

```bash
claude mcp add apideck --transport http https://mcp.apideck.dev/mcp \
  --header "x-apideck-api-key: YOUR_API_KEY" \
  --header "x-apideck-app-id: YOUR_APP_ID" \
  --header "x-apideck-consumer-id: YOUR_CONSUMER_ID"
```

Or configure it directly in `.claude.json`:

```json
{
  "mcpServers": {
    "apideck": {
      "url": "https://mcp.apideck.dev/mcp",
      "headers": {
        "x-apideck-api-key": "YOUR_API_KEY",
        "x-apideck-app-id": "YOUR_APP_ID",
        "x-apideck-consumer-id": "YOUR_CONSUMER_ID"
      }
    }
  }
}
```

**Connecting users via Vault**

The `x-apideck-consumer-id` header only works if the user has already authorized their accounting platform. That authorization happens through Vault, Apideck's hosted connection UI. You generate a Vault session link server-side and redirect the user to it. They pick their accounting platform, complete the OAuth flow, and Vault handles storing the tokens. Your code never touches their credentials.

Generating a session link takes one API call:

```javascript
import { Apideck } from '@apideck/unify'

async function createVaultSession(consumerId) {
  const apideck = new Apideck({
    apiKey: process.env.APIDECK_API_KEY,
    appId: process.env.APIDECK_APP_ID,
    consumerId,
  })

  const { data } = await apideck.vault.sessions.create({
    session: {
      unified_apis: ['accounting'],
      redirect_uri: 'https://yourapp.com/dashboard',
      theme: {
        vault_name: 'Your App',
        primary_color: '#your-brand-color',
      },
    },
  })

  return data.session_uri  // redirect the user to this URL
}
```

The response includes a `session_uri` which you forward to the user. Once they complete the flow, that consumer ID is live and ready to use in the MCP headers. If you prefer to embed the connection experience inside your app rather than redirecting, `@apideck/vault-js` opens it as a modal with a single method call.

From there, the same Claude Code prompts work regardless of which platform the user has connected:

```bash
claude "Using the Apideck MCP, pull the last 60 days of transactions for this customer, categorize any uncategorized expenses against our chart of accounts, and flag any amounts over $5,000 for review."
```

This is also the right setup for testing across multiple platforms before committing to a production REST integration. Switch the consumer ID, run the same prompt against a QBO sandbox and a Xero sandbox, and verify the normalized response looks consistent before writing any application code.

## Via Apideck unified API: production deterministic integrations

The cleanest mental model for choosing between MCP and REST: use MCP when the agent decides what to call and when; use the REST API when your own application code is making those decisions. An AI bookkeeper that reads invoices and flags anomalies belongs on MCP. A scheduled sync job that runs every hour belongs on the REST API.

The [unified accounting API](/blog/what-is-a-unified-api) is the default for companies adding accounting integrations as a product feature. You write the integration once against Apideck's normalized schema, and your users can connect QuickBooks, Xero, Sage, NetSuite, FreshBooks, or any of the 26 supported platforms without you touching the integration layer.

Creating an invoice across any connected accounting platform looks like this:

```javascript
const Apideck = require('@apideck/node');

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

async function createInvoice({ lineItems, customerId, dueDate }) {
  const response = await apideck.accounting.invoicesAdd({
    invoice: {
      type: 'accounts_receivable',
      customer: { id: customerId },
      due_date: dueDate,
      line_items: lineItems.map(item => ({
        description: item.description,
        unit_price: item.amount,
        quantity: 1,
        total_amount: item.amount,
      })),
      currency: 'USD',
    },
  });

  return response.data;
}
```

The same function works whether the end user has connected QuickBooks, Xero, or Sage Business Cloud. Apideck normalizes the data model on the way in and maps the response back to the same schema on the way out.

Claude Code accelerates this further. Instead of reading through the Apideck API reference and writing the integration from scratch, you can give Claude Code a task:

```bash
claude "Using the Apideck Node SDK, build a sync module that pulls chart of accounts from the connected accounting platform, maps each account to our internal category taxonomy stored in accounts-taxonomy.json, and writes the mapping to Postgres. Handle pagination. Log any accounts that don't match a category."
```

Claude Code reads `accounts-taxonomy.json`, inspects the SDK types, writes the sync logic, and generates the Postgres schema. You can combine the Apideck MCP and the REST API in the same session: use the MCP server to pull live sample data during development, then use Claude Code to build the production REST integration against that data.

```bash
claude "Using the Apideck MCP, pull a sample of 20 invoices from the test QBO connection. Then write a TypeScript function that replicates that invoice creation via the Apideck REST API. Test against the sandbox environment."
```

## Which approach fits which problem

| Approach | Best for | Limitation |
|---|---|---|
| Direct API | Single-platform builds, platform-specific fields, white-labeled products with a fixed accounting system | One codebase per platform; maintenance cost grows with every new connector added |
| QuickBooks MCP server | Agentic workflows scoped to QBO: AI agents that read and write QBO data on behalf of users, plus dev-time exploration and testing | Tied to a single QBO company per process; no multi-platform support |
| Apideck MCP server | Agentic workflows that need to reach across multiple accounting platforms; AI agents where the platform is determined at runtime by the connected account | Not the right layer for deterministic programmatic integrations where your application controls the logic |
| Apideck unified API | Programmatic integrations where your application drives the logic: syncing, webhooks, scheduled jobs, multi-tenant products shipping [accounting features](/integrations) to end users at scale | Normalized schema means some platform-specific fields are not exposed |

Claude Code makes all four paths faster. For most product teams, the practical setup is: Apideck MCP for exploration and agent-driven workflows, Apideck REST API for production programmatic integrations, and Claude Code doing the implementation across both.

Learn how to build accounting integrations with Claude Code using the QuickBooks MCP server, Apideck MCP server, and Apideck unified API. Includes working code examples for OAuth, invoice creation, and multi-platform support.

How to Build Accounting Integrations with Claude Code

If you're building a B2B SaaS product that needs to pull data from multiple Shopify stores (orders, products, customers, inventory), you need a public OAuth app. This is the only path Shopify supports for third-party integrations at scale.

Since January 1, 2026, Shopify no longer allows creating legacy custom apps through the Shopify Admin. All new apps must be created via the Shopify Dev Dashboard or Partner Dashboard. Existing custom apps continue to work, but if you're starting fresh or building an integration product, public OAuth is now the standard.

This guide walks through the complete setup process: from registering your app to handling the OAuth flow and getting your first access token.

## Custom apps vs. public apps

Before jumping into setup, a quick clarification on terminology that trips up many developers.

**Custom apps** are built for a single Shopify store. The merchant creates them directly in their admin panel (or, since 2026, via the Dev Dashboard). The store owner generates an access token and hands it to you. Simple, but it doesn't scale if you're building a product that connects to hundreds of stores. Teams without in-house Shopify expertise often hand this build off to [Shopify application development](https://digitalsuits.co/shopify/shopify-app-development/) specialists.

**Public apps** use OAuth 2.0 and can be installed on any Shopify store. The merchant authorizes your app, Shopify redirects them back to your server with an authorization code, and you exchange that code for an access token. This is what platforms like [Apideck](https://www.apideck.com/integrations/shopify) use to power ecommerce integrations.

![How to Create a Shopify Public OAuth App 1](//images.ctfassets.net/d6o5ai4eeewt/4AlKzV27bV5Iisy55twiAX/0d136e065d77df60671270dd61ef6db6/shopify-app-types.png)

If your product needs to connect to multiple merchants' stores, public OAuth is the only viable approach.

## What you'll need

Before starting, make sure you have:

1. A Shopify Partner account (free to create at partners.shopify.com)
2. A development store for testing (you can create one from your Partner Dashboard)
3. A server or endpoint that can receive OAuth callbacks
4. Basic familiarity with OAuth 2.0 flows

## Step 1: Create your app in the Partner Dashboard

Log in to your Shopify Partner account and navigate to the Apps section.

Click "Create app" and select "Create app manually" (not the Remix template, unless you want a full embedded app scaffold).

Enter your app details:

- **App name**: Something descriptive. Avoid using "Shopify" in the name (Shopify will reject it during review).
- **App URL**: The URL where your app lives. For a server-side integration, this is typically your callback handler.
- **Allowed redirection URL(s)**: The exact URL where Shopify will redirect after OAuth authorization. This must match exactly what you send in the OAuth request.

Click "Create app." You'll land on your app's configuration page.

## Step 2: Configure API scopes

Your app needs permission to access specific data types. Shopify calls these "access scopes."

In your app settings, navigate to the "Configuration" tab and find the API access scopes section. Select only the scopes your integration actually needs. Common ones include:

- `read_products` and `write_products` for catalog data
- `read_orders` for order information
- `read_customers` for customer records
- `read_inventory` for stock levels

Requesting too many scopes will make merchants suspicious during the authorization flow. Only ask for what you need.

One scope worth noting: `read_all_orders`. By default, Shopify only gives you access to orders from the last 60 days. If your integration needs historical order data, you must request access to this scope separately in the Partner Dashboard, and Shopify may take up to seven business days to review and approve it.

## Step 3: Set up GDPR webhooks

Shopify requires all public apps to handle GDPR compliance webhooks. These fire when a customer requests their data or asks for deletion.

In your app settings, scroll to the "GDPR mandatory webhooks" section and enter endpoints for:

- **Customer data request**: Returns data you hold about a specific customer
- **Customer data erasure**: Deletes customer data from your systems
- **Shop data erasure**: Deletes all data related to a shop that uninstalls your app

These endpoints must be functional before Shopify will approve your app for the App Store. Even if you're building an unlisted app, you still need to implement them.

## Step 4: Retrieve your API credentials

After saving your configuration, go to the "API credentials" tab. You'll find:

- **Client ID** (also called API key): Used in OAuth requests to identify your app
- **Client secret** (also called API secret key): Used server-side to exchange authorization codes for access tokens

Store these securely. The client secret should never be exposed in client-side code or version control.

## Step 5: Build the OAuth flow

The OAuth 2.0 authorization code flow works like this:

![How to Create a Shopify Public OAuth App 2](//images.ctfassets.net/d6o5ai4eeewt/3m1TpOzT7OGqQ8Lp2wAx9T/605ecb6fd6b74acc8b19f5721661edba/shopify-oauth-flow.png)

**1. Redirect the merchant to Shopify's authorization URL**

When a merchant wants to connect their store, send them to:

```
https://{shop}.myshopify.com/admin/oauth/authorize?client_id={api_key}&scope={scopes}&redirect_uri={redirect_uri}&state={nonce}
```

Replace:
- `{shop}` with the merchant's store name (e.g., `my-store`)
- `{api_key}` with your Client ID
- `{scopes}` with a comma-separated list of scopes (e.g., `read_products,read_orders`)
- `{redirect_uri}` with your callback URL (must match what you configured in Step 1)
- `{nonce}` with a random string you generate and store (for security validation)

**2. Merchant authorizes your app**

Shopify shows the merchant a consent screen listing the permissions you're requesting. If they approve, Shopify redirects them to your callback URL with a `code` parameter.

**3. Exchange the code for an access token**

Your server receives the callback with the authorization code. Make a POST request to exchange it:

```
POST https://{shop}.myshopify.com/admin/oauth/access_token
Content-Type: application/json

{
  "client_id": "{api_key}",
  "client_secret": "{api_secret}",
  "code": "{authorization_code}"
}
```

Shopify responds with:

```json
{
  "access_token": "shpat_xxxxxxxxxxxxxxxxxxxxx",
  "scope": "read_products,read_orders"
}
```

Store this access token securely. You'll use it in the `X-Shopify-Access-Token` header for all API requests to that merchant's store.

**4. Verify the response scopes**

The response includes the actual scopes granted. Compare these against what you requested. Merchants can sometimes modify scope requests during authorization (rare, but possible). If critical scopes are missing, your integration won't function correctly.

## Step 6: Test with a development store

Before submitting to the App Store, test your OAuth flow end-to-end using a development store.

From your Partner Dashboard, create a new development store. Install your app on it by visiting the authorization URL you constructed in Step 5. Complete the flow and verify you receive a valid access token.

Make a test API call to confirm everything works:

```
GET https://{shop}.myshopify.com/admin/api/2025-10/shop.json
X-Shopify-Access-Token: {access_token}
```

If you get back shop details, your OAuth implementation is working.

## Step 7: Choose your distribution method

Shopify offers two distribution options for public apps:

**Listed (Shopify App Store)**: Your app appears in the public App Store. Merchants can discover and install it. Requires Shopify's review and approval.

**Unlisted**: Your app has a public installation URL, but doesn't appear in App Store search results. Still requires review, but merchants can only install via direct link.

For B2B integrations where you're working with specific customers (not general discovery), unlisted distribution usually makes more sense. You control who gets access.

In your app settings, go to "Distribution" and select your preferred method. If choosing App Store listing, you'll need to complete additional listing information (description, screenshots, support URLs) before submitting for review.

## Step 8: Submit for review

Shopify reviews all public apps before they can be installed on production stores (development stores work without approval).

The review process can take up to two weeks. Common rejection reasons include:

- Missing or non-functional GDPR webhook endpoints
- Requesting unnecessary API scopes
- App name containing "Shopify"
- Broken OAuth flow or installation process

Make sure your app works completely before submitting. Shopify's reviewers test the full installation and authorization flow.

## Token types and expiration

Shopify supports two token types:

**Offline tokens** (default): Don't expire. Valid until the merchant uninstalls your app or revokes access. Use these for server-side integrations that need to sync data without user interaction.

**Online tokens**: Expire and are tied to a specific user session. Useful for apps that need to respect individual staff permissions within a store.

For most B2B integration use cases, offline tokens are what you want. They're the default when you don't specify `grant_options[]` in your authorization URL.

## The 2026 deprecation and what it means for you

The January 2026 change affects how apps are created, not how they authenticate. If you already have a custom app with a working access token, it continues to function. But you cannot create new legacy custom apps from the Shopify Admin anymore.

For new integrations built after January 2026:

- **Single-store integrations**: Create apps via the Dev Dashboard, then install on the target store. The OAuth flow generates tokens.
- **Multi-store integrations**: Build a public app as described in this guide.

Both approaches now use OAuth. The distinction is distribution: custom apps (via Dev Dashboard) install on one specific store; public apps can be installed on any store.

Apideck's [Shopify connector](https://www.apideck.com/integrations/shopify) supports both authentication models, handling the OAuth flow and token management so you don't have to build it from scratch.

## Common mistakes to avoid

**Hardcoding the shop URL**: The shop parameter should come from the merchant, not be hardcoded. Different merchants have different store URLs.

**Exposing your client secret**: This belongs on your server only. Never put it in JavaScript, mobile apps, or anywhere client-side.

**Forgetting HMAC validation**: Shopify signs requests with an HMAC. Validate this on every callback to prevent malicious requests.

**Ignoring rate limits**: Shopify has API rate limits (currently 2 requests/second for REST, varies for GraphQL). Build retry logic into your integration.

**Skipping the state parameter**: The nonce/state parameter protects against CSRF attacks. Generate a unique value, store it in the session, and verify it matches when the callback arrives.

## Scaling to multiple ecommerce platforms

Shopify is just one platform. If your customers also sell on WooCommerce, BigCommerce, Square, or other platforms, you'll need separate integrations for each.

Building and maintaining direct integrations with multiple ecommerce APIs is a significant engineering investment. Each platform has different authentication methods, data models, rate limits, and API quirks. For a deeper look at what's involved, see our overview of [top ecommerce APIs](https://www.apideck.com/blog/top-15-ecommerce-apis-to-integrate-with) and the differences between them.

A [unified API](https://www.apideck.com/ecommerce-api) approach can simplify this. Instead of building separate connectors for [Shopify](https://www.apideck.com/integrations/shopify), [WooCommerce](https://www.apideck.com/integrations/woocommerce), [BigCommerce](https://www.apideck.com/integrations/bigcommerce), and others, you integrate once against a normalized API layer that handles the platform-specific differences behind the scenes.

Whatever approach you choose, the OAuth fundamentals covered in this guide apply across most modern SaaS platforms. Understanding this flow will serve you well beyond Shopify.

[Start your 30-day free trial](https://www.apideck.com/signup) and connect to 200+ platforms via a single API.

Step-by-step guide to building a Shopify public OAuth app. Learn OAuth setup, API scopes, access tokens, and how to connect multiple Shopify stores for your SaaS product.

How to Create a Shopify Public OAuth App

How Apideck auto-generated a 229-tool MCP server from an OpenAPI spec using Speakeasy, deployed on Vercel with dynamic tool discovery at 1,300 tokens. A walkthrough of the stack, the hosting tradeoffs, and the hard-won lessons from shipping serverless analytics.

How We Built an MCP Server with 229 Tools (Without Writing a Single Tool Definition)

Stripe provides API keys that let you integrate payment processing, billing, and financial data into your applications. This guide walks through finding and creating API keys in the Stripe Dashboard.

For a unified approach to accounting integrations, check out the [Apideck Stripe connector](https://www.apideck.com/integrations/stripe), which lets you pull Stripe data alongside 30+ other accounting platforms through a single API.

## What is Stripe?

Stripe is a payment processing platform that enables businesses to accept online payments and manage recurring billing. Through its API, you can access financial data including customers, invoices, payments, subscriptions, and transaction history.

## Prerequisites

Before you start, make sure you have:

- A [Stripe account](https://dashboard.stripe.com/register)
- Admin or developer access to the Stripe Dashboard

## Finding Your API Keys

Stripe provides two types of API keys: publishable keys (for client-side code) and secret keys (for server-side code). Each type has both test and live versions.

1. Log into the [Stripe Dashboard](https://dashboard.stripe.com/).
2. Click **Developers** in the left sidebar.
3. Select **API keys** from the menu.

Your publishable key (`pk_live_` or `pk_test_`) and secret key (`sk_live_` or `sk_test_`) are displayed here. In test mode, you can reveal the secret key as many times as needed. In live mode, you can only reveal a secret key once, so copy and store it immediately.

## Creating a Restricted API Key

For better security, you can create restricted keys that limit access to specific resources. This is recommended when integrating with third-party services.

1. In the API keys page, click **Create restricted key**.
2. Give the key a descriptive name.
3. Set permissions for each resource type. For read-only integrations, select **Read** for the resources you need access to.
4. Click **Create key**.

Common permissions for accounting integrations include read access to: Customers, Charges, PaymentIntents, Invoices, Subscriptions, and Products.

## Test Mode vs Live Mode

Stripe maintains separate environments for testing and production:

- **Test mode** uses keys starting with `pk_test_` and `sk_test_`. No real money is processed.
- **Live mode** uses keys starting with `pk_live_` and `sk_live_`. Real transactions occur.

Toggle between modes using the **Test mode** switch in the Dashboard. Make sure you're using the correct keys for your environment.

## Common Mistakes

**Exposing your secret key**: Never include your secret key in client-side code, commit it to version control, or share it publicly. Treat it like a password.

**Using test keys in production**: If your integration isn't processing real payments, verify you're using live mode keys, not test keys.

**Overly permissive keys**: Use restricted keys with minimal permissions rather than your main secret key. This limits potential damage if a key is compromised.

**Forgetting to rotate keys**: If you suspect a key has been exposed, roll it immediately from the API keys page.

## Rate Limits

Stripe's API enforces rate limits to ensure platform stability. The default limit for most endpoints is 25 requests per second, though Stripe may increase this for accounts with higher usage. Some endpoints have stricter limits (the Search API and Files API are limited to 20 operations per second). Test mode has lower limits than live mode. If you exceed these limits, Stripe returns a `429 Too Many Requests` response.

For high-volume integrations, implement exponential backoff and cache frequently accessed data.

## Connecting Stripe via Apideck

Apideck's [unified Accounting API](https://www.apideck.com/accounting-api) lets you connect to [Stripe](https://www.apideck.com/integrations/stripe) alongside platforms like [QuickBooks](https://www.apideck.com/blog/how-to-get-your-quickbooks-api-key) and [Sage](https://www.apideck.com/integrations/sage-intacct) through a single integration.

Note that Apideck's Stripe connector uses OAuth rather than standard API keys. You'll need to create a Stripe App first to get your Client ID, Client Secret, and Channel Link ID. See our [How to Create a Stripe App](https://www.apideck.com/blog/how-to-create-a-stripe-app) guide for the full walkthrough.

### Configuring the Connector

With your Stripe App credentials ready, open the Apideck dashboard and navigate to **Configuration > Accounting > Stripe**.

![How to Get Your Stripe API Key 1](//images.ctfassets.net/d6o5ai4eeewt/5ML5OXJKhKrQrHeYYUSnGl/8f36e3b1f4838e68b7279753bdca119a/964_1x_shots_so.png)

Enter your Client ID and Client Secret, then scroll down to configure scopes and add your Channel Link ID.

![How to Get Your Stripe API Key 2](//images.ctfassets.net/d6o5ai4eeewt/YtnoKh7urpjwDUAcxIJtn/68f2aaa56ef6fde3aebe3bb803592413/358_1x_shots_so.png)

### What Your Users See

When your users connect their Stripe account through Vault, they'll be prompted for their Stripe Account ID (found under Settings > Account details in Stripe, starts with `acct_`).

![How to Get Your Stripe API Key 3](//images.ctfassets.net/d6o5ai4eeewt/50HD22csaVTGmjx1PtHFMm/91dbcf21079f16892b859fdfd2f3cc38/853_1x_shots_so.png)

After authorization, Stripe data flows through Apideck's unified API alongside your other accounting integrations.

Ready to connect to Stripe and 30+ other accounting platforms through a single API? [Get started for free](https://www.apideck.com/signup).

Learn how to find and create your Stripe API keys step by step. Understand test vs live keys, security best practices, and how to integrate Stripe data into your application.

How to Get Your Stripe API Key

Stripe handles payments for millions of businesses, from startups to enterprises. If you're building an integration that syncs financial data from Stripe, you'll need to create a Stripe App to obtain OAuth credentials. This guide walks through creating a Stripe App and retrieving the credentials required to connect Stripe to other platforms.

For a unified approach to accounting integrations, check out the [Apideck Stripe connector](https://www.apideck.com/integrations/stripe), which lets you pull Stripe data alongside 30+ other accounting platforms through a single API.

## What is Stripe?

Stripe is a payment processing platform that enables businesses to accept online payments and manage recurring billing. Beyond payment processing, Stripe exposes financial data through its API, including transactions and customer records. For accounting integrations, this data is typically accessed via Stripe Apps using OAuth rather than raw API keys.

## Prerequisites

Before you start, make sure you have:

- A [Stripe account](https://dashboard.stripe.com/register)
- An Apideck account
- [Node.js](https://nodejs.org/) installed and up to date
- [Stripe CLI](https://stripe.com/docs/stripe-cli) version 1.12.4 or newer

## Creating a Stripe App

Apideck's Stripe connector uses the Stripe Apps platform for OAuth authentication. For the complete walkthrough, see [Apideck's OAuth Credentials Guide](https://developers.apideck.com/connectors/stripe/docs/application_owner+oauth_credentials). Here's a summary of the key steps:

1. Install the [Stripe CLI](https://stripe.com/docs/stripe-cli) if you haven't already.
2. Run `stripe login` to authenticate with your Stripe account.
3. Verify your CLI version is 1.12.4 or newer with `stripe version`.
4. Install the Stripe Apps plugin: `stripe plugin install apps`
5. Verify the apps plugin version (should be 1.5.12 or later): `stripe apps -v`
6. Create a new app: `stripe apps create apideck-integration`
7. Follow the prompts for your app ID and display name.
8. Navigate to your app directory: `cd apideck-integration`
9. Upload your app: `stripe apps upload`

Once uploaded, you can access your app's OAuth credentials in the Stripe Dashboard under **Developers > Created apps**.

## Getting Your Client ID and Client Secret

After uploading your Stripe App:

1. In the Stripe Dashboard, go to **Developers > Created apps**.
2. Click your app to open its details page.
3. Open the **External test/live** tab.
4. Your **Client ID** is displayed here (starts with `ca_`).
5. Generate a **Client Secret** if you haven't already. Store this securely as it won't be shown again.

## Setting Up the Redirect URI

OAuth requires a redirect URI where users return after authorizing the connection. For Stripe Apps, you configure this in your app manifest file (`stripe-app.json`):

```json
{
  "allowed_redirect_uris": [
    "https://unify.apideck.com/vault/callback"
  ]
}
```

You can find a complete working example in the [apideck-samples/stripe-app](https://github.com/apideck-samples/stripe-app/blob/main/stripe-app.json) public repo.

After updating your manifest, run `stripe apps upload` to apply the changes. Without the correct redirect URI, the OAuth flow will fail with an invalid redirect error.

## Finding Your Channel Link ID

Apideck's Stripe connector requires a Channel Link ID, which identifies your app's OAuth install link.

1. In the Stripe Dashboard, go to **Developers > Created apps**.
2. Click your app to open its details page.
3. Open the **External test/live** tab.
4. Locate the OAuth install link in the Test OAuth section.
5. The Channel Link ID is part of this URL, formatted as `chnlink_xxxxx`.

Copy this value for use in the Apideck connector configuration.

## About Stripe Account IDs

When users connect their Stripe accounts through your integration, they may need to provide their Stripe Account ID. This is different from the OAuth credentials you just created. The Account ID:

- Starts with `acct_`
- Is found in the Stripe Dashboard under **Settings > Account details**
- Identifies the specific Stripe account being connected

This ID is used by your integration to access bank account information and other account-specific data.

## Common Mistakes

**Wrong redirect URI**: The most frequent OAuth error. Double-check that the redirect URI in your Stripe App matches exactly what your integration expects. Trailing slashes matter.

**Mixing test and live credentials**: Stripe maintains separate credentials for test mode and live mode. If your integration isn't seeing real data, verify you're using live credentials, not test ones.

**Missing permissions**: If your integration can't access certain data, check whether you've enabled the required permissions in your app manifest. The `stripe_apps` scope is used for OAuth authentication, but actual data access depends on the permissions you've defined.

**Client Secret exposure**: Never commit your Client Secret to version control or expose it in client-side code. Treat it like a password.

## Rate Limits

Stripe's API uses rate limiting to ensure stability. The default rate limit is 100 operations per second in live mode and 25 operations per second in sandbox mode. Some endpoints have stricter limits. If you hit rate limits, Stripe returns a `429 Too Many Requests` response. The `Stripe-Rate-Limited-Reason` header indicates which limit was exceeded.

For high-volume integrations, consider implementing exponential backoff and caching frequently accessed data.

## Connecting Stripe via Apideck

Apideck's [unified Accounting API](https://www.apideck.com/accounting-api) lets you connect to [Stripe](https://www.apideck.com/integrations/stripe) alongside platforms like [QuickBooks](https://www.apideck.com/blog/how-to-get-your-quickbooks-api-key) and [Xero](https://www.apideck.com/blog/how-to-get-xero-api-key) through a single integration. Once you have your Stripe App credentials, configuring the connector takes a few minutes.

### Admin Configuration

1. Log into your Apideck account and navigate to the **Configuration** page.
2. Under **Unified APIs**, select **Accounting**.
3. Find the Stripe connector and click to expand its settings.

![How to Get Your Stripe API Key 1](//images.ctfassets.net/d6o5ai4eeewt/5ML5OXJKhKrQrHeYYUSnGl/8f36e3b1f4838e68b7279753bdca119a/964_1x_shots_so.png)

4. Enter your **Client ID** and **Client Secret** from your Stripe App.
5. Scroll down to the **Scopes** section and enable `stripe_apps` for full access to account data.
6. In the **OAuth Configuration** section, enter your **Channel Link ID** (format: `chnlink_xxxxx`).

![How to Get Your Stripe API Key 2](//images.ctfassets.net/d6o5ai4eeewt/YtnoKh7urpjwDUAcxIJtn/68f2aaa56ef6fde3aebe3bb803592413/358_1x_shots_so.png)

7. Click **Save settings**.

### User Connection Flow

Once admin configuration is complete, your users can connect their Stripe accounts through Apideck Vault:

1. When a user initiates the connection, they'll see the Stripe authorization modal.
2. The user enters their **Stripe Account ID** (found in their Stripe Dashboard under Settings > Account details).
3. They click **Authorize** to complete the OAuth flow.

![How to Get Your Stripe API Key 3](//images.ctfassets.net/d6o5ai4eeewt/50HD22csaVTGmjx1PtHFMm/91dbcf21079f16892b859fdfd2f3cc38/853_1x_shots_so.png)

After authorization, you can pull financial data from Stripe through Apideck's unified Accounting API.

Ready to connect to Stripe and 30+ other accounting platforms through a single API? [Get started for free](https://www.apideck.com/signup).

Create a Stripe App step by step to generate OAuth credentials, connect Stripe to your integration, and sync financial data securely. Learn how to set up your app, retrieve Client ID and Secret, configure redirect URIs, and integrate Stripe with Apideck’s unified Accounting API.


How to Create a Stripe App

MoneyBird has roughly 2 million customers, the majority of them Dutch SMBs using it as their primary accounting system. If you're building a platform that handles money for European businesses — payments, subscriptions, travel bookings, vertical SaaS — you will eventually get asked for MoneyBird sync. This guide covers everything you need to build that integration, including the parts of the API that behave differently from what you'd expect coming from other accounting platforms.

## Two things that differ from most REST APIs before you write a single line

MoneyBird's API has two structural choices that aren't standard and will catch you off guard if you skip straight to the endpoint reference.

First: the response format is part of the URL path, not a header. You don't use `Accept: application/json`. You append `.json` (or `.xml`) to every endpoint:

```
GET https://moneybird.com/api/v2/{administration_id}/contacts.json
```

This means generic API clients that rely on standard content negotiation need extra handling. If you're getting 404s on an endpoint you know exists, a missing format suffix is the first thing to check.

Second: filtering uses dedicated `/filter` sub-endpoints with a `key:value` query syntax, not conventional query string parameters. This matters for any sync job that needs to pull a subset of records.

## Authentication

MoneyBird supports two authentication models.

The first is a personal API token. You generate one from `moneybird.com/user/applications/new`, and you pass it as a Bearer token on every request:

```
Authorization: Bearer {your_token}
```

Personal tokens are fast to set up and fine for internal tools and scripts that access a single MoneyBird account. The hard limit: if you're building a product where your customers connect their own MoneyBird accounts, personal tokens don't work. Each customer would have to generate a token manually and paste it into your app.

The second path is OAuth 2.0. You register your application once at `moneybird.com/user/applications/new`, receive a Client ID and Client Secret, and implement the authorization code flow. The authorize endpoint is `https://moneybird.com/oauth/authorize` and the token endpoint is `https://moneybird.com/oauth/token`. MoneyBird access tokens don't expire by default, but a user can revoke them at any time through their account settings. Build revocation handling from day one — a revoked token returns 401 and your integration needs to detect that and prompt the user to reconnect, not silently fail.

Available OAuth scopes include `sales_invoices`, `purchase_invoices`, `contacts`, `financial_mutations`, `time_entries`, `documents`, and `administration`. Request only what your application needs.

## Getting your administration ID

Every API call requires an administration ID in the path. You retrieve it by calling the administrations endpoint after auth:

```python
import requests
import os

access_token = os.environ["MONEYBIRD_TOKEN"]
headers = {"Authorization": f"Bearer {access_token}"}

response = requests.get(
    "https://moneybird.com/api/v2/administrations.json",
    headers=headers
)
response.raise_for_status()

administrations = response.json()
administration_id = administrations[0]["id"]
print(f"Administration ID: {administration_id}")
```

One user can have multiple administrations (separate legal entities, for example). If your product supports multi-administration scenarios, store each `id` separately — you can't assume there's only one.

## Core endpoints

Sales invoices live at `/{administration_id}/sales_invoices.json`. Each invoice object includes `invoice_id`, `contact_id`, `state` (draft, open, late, paid, uncollectible), `total_price_incl_tax`, `due_date`, and line items under `details`.

Contacts are at `/{administration_id}/contacts.json`. You'll need a valid contact ID before creating invoices programmatically, so contacts are usually the first resource you sync.

Purchase invoices sit at `/{administration_id}/documents/purchase_invoices.json`. Note the `documents/` prefix in the path — it's different from the sales invoice path and the asymmetry catches people.

Financial mutations live at `/{administration_id}/financial_mutations.json` and represent bank transaction-level data. The official changelog explicitly warns against fetching individual mutations in a tight loop because the rate limit hits fast. Use the synchronization API for bulk pulls (covered below).

Ledger accounts are at `/{administration_id}/ledger_accounts.json`. Since July 2024, creating ledger accounts without an RGS taxonomy item code (`rgs_code`) is blocked. If your integration creates ledger accounts, you need to include a valid RGS code or the request will fail.

## Pagination

MoneyBird uses `page` and `per_page` query parameters. The maximum page size is 100 records. What the documentation buries: MoneyBird does not return total record counts. There's no `total` or `count` field in the response body.

Instead, MoneyBird uses HTTP Link headers to signal whether more pages exist:

```
Link: <https://moneybird.com/api/v2/123/sales_invoices.json?page=2>; rel="next"
```

When there's no `rel="next"` in the Link header, you're on the last page. Here's a complete Python function that handles pagination correctly, rate limit responses, and the missing total count:

```python
import requests
import time
import os

def fetch_all_sales_invoices(administration_id: str, access_token: str) -> list:
    headers = {"Authorization": f"Bearer {access_token}"}
    base_url = f"https://moneybird.com/api/v2/{administration_id}/sales_invoices.json"
    
    invoices = []
    page = 1

    while True:
        response = requests.get(
            base_url,
            headers=headers,
            params={"page": page, "per_page": 100}
        )

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 30))
            print(f"Rate limited. Waiting {retry_after} seconds.")
            time.sleep(retry_after)
            continue

        response.raise_for_status()
        batch = response.json()
        invoices.extend(batch)

        # Check Link header for next page
        link_header = response.headers.get("Link", "")
        if 'rel="next"' not in link_header:
            break

        page += 1

    return invoices


if __name__ == "__main__":
    token = os.environ["MONEYBIRD_TOKEN"]
    admin_id = os.environ["MONEYBIRD_ADMINISTRATION_ID"]
    
    all_invoices = fetch_all_sales_invoices(admin_id, token)
    print(f"Total invoices fetched: {len(all_invoices)}")
```

This matters for anything where you need to know how many total records exist — progress indicators, sync job sizing, confirming a full sync completed. You have to traverse all pages first. Build your sync jobs with that assumption baked in.

## Filtering

To filter sales invoices by state, you don't append `?state=open`. You POST to a dedicated filter endpoint:

```
POST /{administration_id}/sales_invoices/filter.json
Content-Type: application/json

{
  "filter": "state:open"
}
```

Multiple conditions combine with commas:

```json
{
  "filter": "state:open,contact_id:143273868766741508"
}
```

The filter endpoint respects the same pagination behavior as the list endpoint — check the Link header, don't assume a single response covers everything. The supported filter keys per resource are documented on each endpoint's reference page. Combinations that seem logical but aren't listed will either silently return unfiltered results or fail validation.

## Rate limits

The API allows 150 requests per 5 minutes. Exceeding that returns a `429 Too Many Requests` response with a `Retry-After` header. The Python example above handles this correctly with a sleep-and-retry pattern.

At 150 requests per 5 minutes, the limit is workable for background sync jobs if you batch reads efficiently. It becomes a problem with chatty patterns: fetching individual records in a loop, resolving contacts one at a time inside an invoice iteration, or polling for changes on a short interval. The synchronization API solves most of these cases.

## Synchronization API

For bulk reads on resources like financial mutations or products, MoneyBird exposes a two-step synchronization flow.

Step one: fetch the synchronization list to get all record IDs and version numbers without pulling full record data:

```
GET /{administration_id}/sales_invoices/synchronization.json
```

This returns a flat array of `{id, version}` objects for every record. It's fast and cheap against the rate limit.

Step two: compare those versions against your local cache, then POST only the IDs that have changed to the bulk fetch endpoint:

```
POST /{administration_id}/sales_invoices/synchronization.json
Content-Type: application/json

{
  "ids": ["143273868766741508", "143274315994891267"]
}
```

This returns full record detail only for the IDs you requested. On a recurring sync job, this pattern can reduce your API calls by 90% or more compared to paginating through all records on every run.

## Webhooks

MoneyBird supports webhooks for real-time event notifications. Register an endpoint with a POST to `/{administration_id}/webhooks.json` with your target URL and the event types you want to receive.

Your endpoint must respond with HTTP 200. If it doesn't, MoneyBird retries delivery 10 times with gradually increasing intervals between attempts. The webhook payload includes the event type, administration ID, and the full entity object that changed.

Use HTTPS. The official documentation explicitly recommends against plain HTTP because invoice and contact payloads pass through unencrypted otherwise.

One useful feature for debugging: the webhooks API stores the last HTTP status code and response body from each delivery attempt. You can retrieve this via a GET to your webhook object — useful when you need to diagnose delivery failures without digging through server logs.

## External sales invoices: linking contacts at creation

A PATCH to an external sales invoice with only `contact_id` in the payload can behave unexpectedly — it can affect more invoices than intended. This is a known MoneyBird API edge case that surfaces when processing documents in volume.

The fix is to assign `contact_id` at creation time, not after the fact. Instead of uploading the PDF first and then PATCHing the contact, restructure the flow:

1. Check or create the contact (most integrations already do this).

2. Create the external sales invoice with `contact_id` included in the creation payload:

```
POST https://moneybird.com/api/v2/{admin_id}/external_sales_invoices.json

{
  "external_sales_invoice": {
    "contact_id": "{contact_id}",
    "reference": "INV-001",
    "date": "2025-01-15"
  }
}
```

3. Attach the PDF to the invoice after creation:

```
POST https://moneybird.com/api/v2/{admin_id}/external_sales_invoices/{invoice_id}/attachments
```

The invoice is linked to the contact from the moment it's created. The risky PATCH is removed from the flow entirely.

## Documentation drift

One real operational issue that costs teams time: some fields appear as deprecated in the changelog but still show up in the API reference. In several cases, PATCH and POST behavior doesn't match what the docs describe. Budget time for empirical testing beyond reading the reference.

A specific one to watch in 2026: the `detail_id` field on time entry objects is being removed after July 31, 2025. If your integration uses time entries and maps against `detail_id`, you need to migrate to `sales_invoice_id`, which was added to the PATCH and POST endpoints in the same release.

## Build vs. buy

Building directly against MoneyBird makes sense when it's your only target accounting system. If your customers also use Xero, QuickBooks, Exact Online, or FreeAgent, you'll repeat most of this work for each one. Different auth flows, different entity models, different pagination behavior, different filter syntax, different webhook structures. Every new accounting connector is a meaningful engineering and maintenance commitment.

[Apideck's accounting API](https://apideck.com/accounting) normalizes MoneyBird alongside QuickBooks, Xero, Exact Online, and 25+ other systems behind a single schema. One integration, one OAuth flow, standardized objects for invoices, contacts, ledger accounts, and payments. MoneyBird's pagination quirks and filter syntax stay abstracted. If you're at a vertical SaaS company or a platform moving money on behalf of European businesses, running the build-versus-buy numbers before writing your eighth accounting connector is worth the hour.

A practical guide to integrating with the MoneyBird API: OAuth vs personal tokens, pagination, filtering, rate limits, webhooks, and the synchronization API — with working Python examples.

How to Integrate with the MoneyBird API in 2026

Yuki is a cloud boekhouden platform built for SMEs and accounting practices in the Netherlands, Belgium, and Spain. If you're building a product that needs to push invoices, sync contacts, or pull financial data for a Yuki user's administration, you're going to work with a SOAP API. That's worth knowing upfront: Yuki does not have a REST interface. Every call goes through SOAP over HTTPS, which means envelope XML, namespaces, and a session-based auth flow rather than a bearer token.

Setting up a Yuki koppeling involves two parts: getting the right credentials from inside the Yuki portal, and structuring your SOAP requests correctly. This post covers both, along with the available webservices, the rate limits you need to plan around, and what to watch for when building for multiple customers.

## Authentication: two credentials, one session

Yuki's API uses a two-step authentication model. You first call `Authenticate(accessKey)` with a WebserviceAccessKey, which returns a session ID. That session ID is then passed along with an Administration ID on every subsequent call.

The WebserviceAccessKey is generated inside the Yuki portal under the Web services settings for the domain or administration. Only users with Portal Administrator or Management roles can generate one. If you're building a product where your customers connect their own Yuki accounts, each customer needs to provide their own key. Yuki's API does not support a centralized OAuth flow where your application requests delegated access on behalf of users.

There's also a second auth method, `AuthenticateByUserName(userName, password)`, which accepts Yuki credentials directly, but the access key route is preferable. Keys can be rotated without changing credentials, and they scope permissions to specific webservices rather than granting full account access.

Here's a minimal PHP example using the Sales webservice:

```php
$webservice_url = 'https://api.yukiworks.nl/ws/Sales.asmx?WSDL';
$key = 'YOUR_WEBSERVICEACCESSKEY';
$admin_id = 'YOUR_ADMINISTRATIONID';

$soap = new SoapClient($webservice_url);
$res = $soap->Authenticate(['accessKey' => $key]);
$sess_id = $res->AuthenticateResult;

$res = $soap->ProcessSalesInvoices([
    'sessionID'        => $sess_id,
    'administrationId' => $admin_id,
    'xmlDoc'           => $invoiceXml
]);
```

Python developers using `zeep` follow the same pattern. `zeep` parses the WSDL automatically and maps each method to a Python callable:

```python
from zeep import Client

wsdl = 'https://api.yukiworks.nl/ws/Sales.asmx?WSDL'
key = 'YOUR_WEBSERVICEACCESSKEY'
admin_id = 'YOUR_ADMINISTRATIONID'

client = Client(wsdl)
sess_id = client.service.Authenticate(accessKey=key).AuthenticateResult

result = client.service.ProcessSalesInvoices(
    sessionID=sess_id,
    administrationId=admin_id,
    xmlDoc=invoice_xml
)
```

In Node.js, the `soap` package works the same way. Methods return arrays where the first element is the response object:

```javascript
const soap = require('soap');

const wsdl = 'https://api.yukiworks.nl/ws/Sales.asmx?WSDL';
const key = 'YOUR_WEBSERVICEACCESSKEY';
const adminId = 'YOUR_ADMINISTRATIONID';

(async () => {
  const client = await soap.createClientAsync(wsdl);
  const [authResult] = await client.AuthenticateAsync({ accessKey: key });
  const sessId = authResult.AuthenticateResult;

  const [result] = await client.ProcessSalesInvoicesAsync({
    sessionID: sessId,
    administrationId: adminId,
    xmlDoc: invoiceXml
  });
})();
```

Across all three languages, the session ID field name (`AuthenticateResult`) and the need to pass a namespaced XML string as `xmlDoc` stay the same. The WSDL URL is the universal entry point.

## The available webservices

Each Yuki webservice covers a distinct data domain, accessed at separate ASMX endpoints under `https://api.yukiworks.nl/ws/`.

The Accounting webservice (`Accounting.asmx`) handles financial data exports and general journal creation. The `ProcessJournal` method takes an XML document describing journal entries against GL accounts, which is the primary route for pushing bank transactions, write-offs, or custom entries from an external system. The AccountingInfo webservice (`AccountingInfo.asmx`) lets you read GL account schemes and retrieve transaction details.

The Sales webservice (`Sales.asmx`) creates sales invoices via `ProcessSalesInvoices`. The XML payload includes fields for invoice lines, customer references, tax codes, and payment terms. Linking invoices to projects requires the Medium bundle or higher on the customer's Yuki account.

The Contact webservice handles search, create, and update operations for customers and suppliers. The Archive webservice lets you push documents with financial metadata and pull documents back out. The Upload webservice is for attaching source documents (PDFs, images) to records. Pettycash handles cash report imports, and the Project webservice creates and updates project records.

One webservice that sits outside the standard API key flow: the Purchase webservice. To get access, you need to send a formal request to `support@yuki.nl`, after which Yuki issues a Client ID and Secret used alongside the regular API key. There is no self-service activation path for this one.

## What the XML payloads look like

The `xmlDoc` parameter in every Yuki write operation expects namespaced XML. The namespace must match the target webservice exactly — a missing or mismatched namespace declaration produces a silent failure with no useful error message.

For `ProcessSalesInvoices`, the envelope looks like this:

```xml
<?xml version="1.0" encoding="utf-8"?>
<SalesInvoices xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns="urn:xmlns:http://www.theyukicompany.com:salesinvoices"
               xsi:schemaLocation="urn:xmlns:http://www.theyukicompany.com:salesinvoices salesinvoices.xsd">
  <SalesInvoice>
    <Reference>INV-2026-001</Reference>
    <Subject>Software License Q1 2026</Subject>
    <Date>2026-04-01</Date>
    <DueDate>2026-05-01</DueDate>
    <Contact>
      <Code>CUST001</Code>
    </Contact>
    <InvoiceLines>
      <InvoiceLine>
        <Description>Annual license fee</Description>
        <Quantity>1</Quantity>
        <UnitPrice>1200.00</UnitPrice>
        <VATPercentage>21</VATPercentage>
        <VATCode>21</VATCode>
      </InvoiceLine>
    </InvoiceLines>
  </SalesInvoice>
</SalesInvoices>
```

For `ProcessJournal` through the Accounting webservice, the journal namespace is different:

```xml
<?xml version="1.0" encoding="utf-8"?>
<Journal xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="urn:xmlns:http://www.theyukicompany.com:journal"
         xsi:schemaLocation="urn:xmlns:http://www.theyukicompany.com:journal journal.xsd">
  <Administration>
    <Code>YOUR_ADMINISTRATIONID</Code>
  </Administration>
  <Entries>
    <Entry>
      <Date>2026-04-01</Date>
      <Description>Customer payment received</Description>
      <Rows>
        <Row>
          <GLAccountCode>1000</GLAccountCode>
          <Description>Bank</Description>
          <Debit>1452.00</Debit>
        </Row>
        <Row>
          <GLAccountCode>1300</GLAccountCode>
          <Description>Accounts receivable</Description>
          <Credit>1452.00</Credit>
        </Row>
      </Rows>
    </Entry>
  </Entries>
</Journal>
```

Each journal entry must balance: total debits must equal total credits. The `GLAccountCode` values correspond to the customer's chart of accounts, which you can fetch via the `AccountingInfo.asmx` webservice before writing entries.

## Rate limits and batching

The default quota is 1,000 SOAP calls per day per Yuki domain. A portal administrator can raise that ceiling through two paid add-ons: "Yuki Webservice" extends it to 5,000 calls/day for €10.50/month, and "Yuki Webservice Extended" pushes to 10,000 calls/day for €105/month.

A thousand calls per day is tighter than it sounds if you're polling for updates or syncing large transaction histories. Design around batch operations from the start. `ProcessSalesInvoices` accepts multiple invoices in a single XML document, so there's no reason to make one call per invoice. The same applies to journal entries and contact records.

If you're building a multi-tenant product where each customer has their own Yuki administration, the 1,000-call limit applies per domain, not per API key. One heavily active customer won't consume another's quota, but you still need per-administration rate tracking if you want to avoid hitting the ceiling for any individual customer.

## Working with SOAP in practice

SOAP has a reputation for being painful, and Yuki's implementation has a few rough edges worth knowing about.

TLS 1.2 or higher is required. Yuki enforced this in April 2019 and will reject connections on older versions.

The namespaces in the XML payloads need to match exactly. The sales invoice XML uses `urn:xmlns:http://www.theyukicompany.com:salesinvoices`, and the journal XML uses `urn:xmlns:http://www.theyukicompany.com:journal`. Mismatched or missing namespace declarations are a common source of silent failures that can be difficult to diagnose.

Modern SOAP clients (PHP's `SoapClient`, Python's `zeep`, Node's `soap` package) can parse the WSDL endpoint and generate the correct envelope structure automatically. Pointing your client at the `?WSDL` URL for the relevant service is the fastest way to get started without hand-writing envelopes.

## If you're building for multiple accounting systems

Yuki is the dominant cloud boekhouden platform in the Netherlands and Belgium, but if you're trying to cover the broader European accounting software market, each platform runs its own authentication model, data schemas, and rate limits. Connecting to them one at a time compounds fast, and European accounting is a fragmented market by design.

One option is to build the Yuki integration through [Apideck's Accounting API](https://www.apideck.com/accounting-api), which maps Yuki's data model to a standardized interface shared across 200+ connectors. Your code sends and receives normalized objects (invoices, contacts, journal entries, ledger accounts), and Apideck handles the SOAP translation, session management, and per-user credential storage on the Yuki side. You can see how the [Yuki connector](https://www.apideck.com/integrations/yuki) is structured, or explore how similar integrations like [Exact Online](https://www.apideck.com/blog/how-to-integrate-with-the-exact-online-api) work through the same interface if you're covering multiple Benelux platforms.

Either way, the Yuki API is well-documented relative to what you'd expect from a regional accounting tool. The official documentation lives at Yuki's Postman collection, sample code for PHP and C# covers the most common operations, and the webservice structure is consistent once you understand the session model. The SOAP overhead is real, but manageable once you have the session flow and namespace handling sorted.

---

## FAQ

**How do I get a Yuki API key?**

In Yuki, go to Settings > Web services (or navigate via My Domain > Administration > Web services). Click the + button to generate a new WebserviceAccessKey. You'll also see the Administration ID here, which you'll need alongside the key for every API call. Only Portal Administrator or Management role users can generate keys.

**What is the Yuki API rate limit?**

By default, each Yuki domain is capped at 1,000 SOAP calls per day. Your accountant can activate the "Yuki Webservice" add-on to raise this to 5,000 calls/day (€10.50/month) or "Yuki Webservice Extended" for up to 10,000 calls/day (€105/month).

**Does Yuki have a REST API?**

No. Yuki's API is SOAP-only. All calls are made to ASMX endpoints over HTTPS, and every request requires a valid session ID obtained through the `Authenticate` method.

**What is a Yuki koppeling?**

A Yuki koppeling (Dutch for "Yuki connection" or "Yuki integration") is the term used in the Dutch market for connecting external software to a Yuki administration via the webservice API. Setting one up requires generating a WebserviceAccessKey and Administration ID from within the Yuki portal.

Learn how to integrate with the Yuki API using SOAP webservices. This guide covers authentication, the WebserviceAccessKey flow, all eight webservices, rate limits, batching, and what to watch for when building a Yuki koppeling for multiple customers.

How to Integrate with the Yuki API in 2026

Get your Zoho Books OAuth credentials set up and make your first authenticated API call. This guide covers app registration, client types, scopes, the authorization flow, token management, and the mistakes that cost developers time.

## What's Zoho Books?

[Zoho Books](https://www.apideck.com/integrations/zoho-books) is Zoho's cloud accounting platform, and it has found its audience in small and mid-sized businesses already inside the Zoho ecosystem. Companies using Zoho CRM, Zoho Projects, or Zoho Inventory that want their accounting in the same stack. It handles invoices, bills, expenses, purchase orders, bank feeds, and tax compliance across a range of countries.

The API is REST-based, returns JSON, and follows familiar patterns. Version 3 is the current release. Every request requires two things: a valid OAuth 2.0 access token and an `organization_id` parameter. Zoho Books supports multiple organizations under one account, and the API enforces strict separation between them. Before you can touch any other endpoint, you'll need the organization ID from `GET /organizations`.

> **Note:** Zoho Books doesn't use static API keys. Authentication is handled through OAuth 2.0, which means you'll be working with a Client ID, Client Secret, access tokens, and refresh tokens.

If you're planning to connect Zoho Books to your platform alongside other accounting tools, take a look at Apideck's guide on [how to integrate with the Zoho Books API](https://www.apideck.com/blog/how-to-integrate-with-the-zoho-books-api) for the fuller picture on data mapping and sync patterns. For a broader view of how accounting APIs compare, the [top accounting APIs guide](https://www.apideck.com/blog/top-15-accounting-apis-to-integrate-with) covers Zoho Books alongside the other major platforms.

## Prerequisites

- A Zoho Books account (any paid plan, or a free trial)
- A Zoho account login to access the Developer Console
- A redirect URI ready for your application (or use the Self Client option if you're building a server-side script without a public URL)

## Step 1: Go to the Zoho Developer Console

Open [https://api-console.zoho.com](https://api-console.zoho.com) and log in with your Zoho account credentials.

## Step 2: Create a New Client

Click **GET STARTED** (or **ADD CLIENT** if you've been here before). You'll be asked to choose a client type. The five options are:

- **Server-based Applications**: web apps running on a dedicated server with a redirect URI. This is the right choice for most SaaS integrations.
- **Client-based Applications**: browser-only apps (JavaScript, no web server).
- **Mobile Applications**: iOS/Android apps.
- **Non-browser Applications**: devices without browser support such as smart TVs and printers.
- **Self Client**: standalone server-side scripts or back-end jobs with no redirect URL. Good for testing, internal tooling, or one-off data syncs.

For a production integration, pick **Server-based Applications**. If you're just getting credentials to test an endpoint, **Self Client** is faster.

## Step 3: Fill in Your Application Details

Once you click **Create Now** for your chosen client type, fill in the following:

- **Client Name**: the name of your application. Zoho uses this on the consent screen your users see.
- **Homepage URL**: the full URL of your app's homepage (required for server-based apps).
- **Authorized Redirect URIs**: where Zoho sends the authorization code after the user approves access. Use `https://` in production. You can add multiple URIs.

Click **CREATE**.

## Step 4: Copy Your Client ID and Client Secret

After creation, your **Client ID** and **Client Secret** appear in the **Client Secret** tab. Copy both and store them securely.

- **Client ID**: public identifier for your app.
- **Client Secret**: keep this private. Don't put it in client-side code, public repos, or browser logs.

## Step 5: Choose Your Scopes

Scopes control what your app can read and write. Zoho Books uses a consistent naming pattern:

```
ZohoBooks.{module}.{permission}
```

Where permission is `CREATE`, `READ`, `UPDATE`, `DELETE`, or `ALL`.

Common modules and their scopes:

| Module | Example Scope |
|---|---|
| Invoices | `ZohoBooks.invoices.READ` |
| Contacts | `ZohoBooks.contacts.ALL` |
| Bills | `ZohoBooks.bills.CREATE` |
| Expenses | `ZohoBooks.expenses.READ` |
| Banking | `ZohoBooks.banking.READ` |
| Settings | `ZohoBooks.settings.READ` |
| Accountants | `ZohoBooks.accountants.READ` |

Request the minimum scopes your integration needs. Users see these on the consent screen, and a long list raises friction. `ZohoBooks.fullaccess.all` exists, but it's overkill for most integrations and looks alarming to end users.

## Step 6: Build the Authorization URL

For server-based apps, you'll redirect users to Zoho's authorization endpoint to get a grant token (authorization code). Construct a `GET` request to:

```
https://accounts.zoho.com/oauth/v2/auth
```

With these parameters:

| Parameter | Value |
|---|---|
| `client_id` | Your Client ID |
| `response_type` | `code` |
| `redirect_uri` | One of your registered redirect URIs |
| `scope` | Comma-separated scopes |
| `access_type` | `offline` (to receive a refresh token) |

A full example:

```
https://accounts.zoho.com/oauth/v2/auth?client_id=1000.YOUR_CLIENT_ID&response_type=code&redirect_uri=https://yourapp.com/callback&scope=ZohoBooks.invoices.CREATE,ZohoBooks.contacts.READ&access_type=offline
```

After the user approves, Zoho redirects to your callback URL with a `code` parameter. That's your authorization code.

> **Region note:** If your Zoho Books account is on the EU data center, use `accounts.zoho.eu` instead of `accounts.zoho.com`. Same for `zoho.in`, `zoho.com.au`, `zoho.jp`, `zoho.ca`, `zoho.com.cn`, `zoho.sa`, and other regional domains. The authorization URL must match the domain of your user's account.

## Step 7: Exchange the Code for Tokens

Hit Zoho's token endpoint with a `POST` request:

```
https://accounts.zoho.com/oauth/v2/token
```

Body parameters:

```
code=AUTHORIZATION_CODE
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET
redirect_uri=https://yourapp.com/callback
grant_type=authorization_code
```

A successful response:

```json
{
  "access_token": "1000.abc123...",
  "refresh_token": "1000.def456...",
  "api_domain": "https://www.zohoapis.com",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

Save both tokens. The `api_domain` field tells you which regional endpoint to use for subsequent API calls.

## Step 8: Make Your First API Call

Pass the access token in the `Authorization` header:

```
Authorization: Zoho-oauthtoken YOUR_ACCESS_TOKEN
```

Start by fetching your organization ID:

```bash
curl -X GET 'https://www.zohoapis.com/books/v3/organizations' \
  -H 'Authorization: Zoho-oauthtoken YOUR_ACCESS_TOKEN'
```

Grab the `organization_id` from the response. You'll need to append `?organization_id=YOUR_ORG_ID` to every subsequent request.

## Step 9: Handle Token Refresh

Access tokens expire after one hour. When a call returns a `401`, use your refresh token to get a new one:

```bash
curl -X POST 'https://accounts.zoho.com/oauth/v2/token' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET' \
  -d 'refresh_token=YOUR_REFRESH_TOKEN' \
  -d 'grant_type=refresh_token'
```

The response gives you a new access token. The refresh token stays the same in this flow. If you lose the refresh token, you'll need to restart the OAuth flow from the authorization URL step.

## Self Client: The Shortcut for Server-Side Scripts

If you picked **Self Client** in Step 2, the flow is different. You don't build an authorization URL or handle redirects. Instead:

1. On the **Client Secret** tab, copy your Client ID and Client Secret.
2. Switch to the **Generate Code** tab.
3. Enter your required scopes (comma-separated), pick a time duration for the grant token, add a description, and click **Create**.
4. Copy the generated grant token immediately. By default it expires after three minutes, though you can select a longer duration from the dropdown.
5. Exchange that code for tokens using the same token endpoint from Step 7.

Self Client works well for background jobs, internal tooling, and testing. It's not suitable for multi-user apps where each customer needs to authorize your app against their own Zoho Books organization.

## Common Mistakes

**Wrong regional domain.** Zoho Books is multi-datacenter. If a user's account is on `zoho.eu`, you need `accounts.zoho.eu` for auth and `www.zohoapis.eu` for API calls. You can identify the region from the `location` parameter returned in Zoho's redirect response after authorization.

**Grant token already used or expired.** Authorization codes are single-use. For server-based apps, the grant token expires after two minutes. For Self Client, the default is three minutes (though you can extend this when generating the token). If you try to exchange one that's been used or has expired, you'll get `invalid_code`. Generate a fresh code and exchange it right away.

**Missing organization_id.** Every API endpoint requires `?organization_id=YOUR_ORG_ID`. Leaving it out returns a 400 error. Call `GET /organizations` first and cache the value.

**Redirect URI mismatch.** The redirect URI in your authorization request must exactly match one registered in the Developer Console. A trailing slash difference, `http` vs `https`, or a subdomain variation will return an error.

**No refresh token.** If you called the authorization endpoint with `access_type=online` (or omitted it, since online is the default), you won't receive a refresh token. Once the access token expires, users have to re-authorize. For production integrations, always use `access_type=offline`. If you need a new refresh token after the first authorization, add `prompt=consent` to force the consent screen again.

## Rate Limits

Zoho Books has some of the tighter rate limits among major accounting APIs:

- **Per-minute:** 100 requests per minute per organization (error code 44 on breach)
- **Per-day:** varies by plan
  - Free: 1,000 requests/day
  - Standard: 2,000 requests/day
  - Professional: 5,000 requests/day
  - Premium, Elite, and Ultimate: 10,000 requests/day
- **Concurrent:** 5 concurrent calls for Free plans, 10 concurrent calls (soft limit) for paid plans (error code 1070 when exceeded)

The daily limit is shared across all integrations connected to the same organization. If your customer uses other Zoho-connected tools, they're drawing from the same pool. Build exponential backoff into your 429 handling.

## Connecting Through Apideck

If Zoho Books is one of several accounting platforms you need to support, building a separate direct integration for each one gets expensive quickly. Apideck's [Zoho Books connector](https://www.apideck.com/integrations/zoho-books) connects through a unified accounting API alongside QuickBooks, Xero, Sage, NetSuite, and 30+ other platforms. Authentication, token refresh, rate limit handling, and data normalization are managed at the platform level.

To configure the connector, open the Apideck dashboard, go to **Configuration > Connectors**, and select **Zoho Books** under the Accounting API. You'll see two credential options: use Apideck's shared credentials for quick testing, or enter your own Client ID and Client Secret from the steps above for production use.

![How to Get Your Zoho Books API Key 1](//images.ctfassets.net/d6o5ai4eeewt/5tNpoE44mVZqkwNkGkVaCJ/a50a5cd09266bfb6effd28aa7dd0f1b0/297_1x_shots_so.png)

Once you've entered your credentials and saved, click **Authorize** to kick off the OAuth flow. After your users connect their Zoho Books account, the Organization ID field populates automatically.

![How to Get Your Zoho Books API Key 2](//images.ctfassets.net/d6o5ai4eeewt/1Ux8uZ2YLmFAZo33aGRtg2/a1a9b07bbe76147b55f74a271f6010ce/657_1x_shots_so.png)

The scopes panel lets you control exactly which Zoho Books resources your connector can access. You can select individual scopes per module (contacts, invoices, bills, and so on) rather than granting full access. The Virtual Webhooks section beneath it shows which resources Apideck will poll for updates, with a default 24-hour sync cycle that you can adjust per resource.

![How to Get Your Zoho Books API Key 3](//images.ctfassets.net/d6o5ai4eeewt/30S3fNRfzhABSkFARxNAf7/6baa30db34bc54c65297013d02d2e312/596_1x_shots_so.png)

Ready to connect to Zoho Books and 30+ other accounting platforms through a single API? [Get started for free](https://www.apideck.com/signup).

Learn how to get your Zoho Books API key using OAuth 2.0. This step-by-step guide covers app registration, client setup, scopes, authorization flow, access and refresh tokens, and common mistakes developers should avoid when integrating.


How to Get Your Zoho Books API Key

AI tools can generate API calls and connector code in minutes. The problem is that production integrations are not API calls. They are authentication flows with OAuth variations across vendors, webhook handling, pagination logic, rate limiting, retry mechanisms, idempotency guarantees, schema transformations, version management, and the security posture that keeps all of it from becoming an attack surface. AI-generated code typically handles the happy path and fails at the edges. In accounting and ERP integrations, the edges are where the money is.

None of this means avoiding AI entirely. The more useful question is where AI genuinely moves the needle versus where it creates hidden costs that surface later. Both are real, and conflating them leads to bad decisions in either direction.

## The iceberg problem is worse than it looks

When a developer asks an AI to integrate QuickBooks, it generates something that works against the sandbox in about ten minutes. Stakeholders see this and conclude the integration is nearly done. In practice, that visible progress represents around 20% oThe complexity that used to live in explicit field mappings and error handling code now lives in prompts, context, and implicit assumptions.f the actual work.

The remaining 80% is invisible: handling token refresh failures when the user's QuickBooks session expires mid-sync, retrying on rate limit responses without hammering the API, managing the difference between a draft invoice and a posted one, dealing with line items that contain characters QuickBooks silently truncates. None of this appears in documentation. It shows up in production, usually at the worst moment.

A [2025 study](https://arxiv.org/abs/2501.01042) presented at the ACM International Conference on AI-powered Software found that none of the evaluated open-source models solved more than 40% of web API integration tasks. The failures were not random. They clustered around exactly these edge conditions: hallucinated endpoints, incorrect pagination handling, authentication flows that worked against documented behavior but failed under real vendor implementations.

The [Superglue Integration Benchmark](https://superglue.ai/benchmarks), which tested 21 enterprise systems across six AI models, found that 23% of integration attempts failed completely. Only six systems integrated 100% reliably across all platforms tested. The benchmark's conclusion: purpose-built integration platforms outperform general AI models by 30+ percentage points on real enterprise workflows.

The security implications compound the reliability problem. [Wallarm's 2026 API ThreatStats report](https://www.wallarm.com/reports/2026-wallarm-api-threatstats-report) found that APIs are now the single largest exploited vulnerability surface, with 97% of API vulnerabilities exploitable in a single request. AI vulnerabilities grew 398% year over year. When AI generates integration code that handles authentication loosely or passes untrusted input to downstream systems, it creates exactly the attack vectors this report documents.

![Top Pitfalls of Letting AI Build Your Integrations iceberg](//images.ctfassets.net/d6o5ai4eeewt/1rQ7zMIM3aCGo8NAJEh51P/59e2f406ae7d2422ca46399b10520acc/Gemini_Generated_Image_j9koncj9koncj9ko_-_Edited.png)

## AI doesn't hallucinate randomly. It hallucinates predictably.

This is underappreciated. AI models fail at integrations in consistent, specific ways that reflect their training data rather than random noise.

Enterprise APIs like NetSuite have massive API surfaces that are version-dependent and sparsely documented in public sources. AI-generated code for NetSuite consistently targets deprecated endpoints and uses authentication patterns from older API versions, because that is what the training data contains. The model is not guessing randomly; it is confidently using what it learned, which happens to be wrong.

The same pattern appears across accounting platforms. QuickBooks Online uses OAuth 2.0 with specific token refresh requirements that differ from generic OAuth 2.0 implementations. Sage Intacct uses session-based authentication. NetSuite supports multiple authentication methods with different scoping rules. AI generates a generic OAuth flow that satisfies the documented standard but fails under vendor-specific requirements. These are not bugs in the AI; they are the predictable output of training on documentation rather than on the vendor support tickets and community forum posts where the real behavior is described.

In March 2026, Andrew Ng's team at DeepLearning.AI released [Context Hub](https://github.com/andrewyng/context-hub), an open-source CLI tool designed to give coding agents access to curated, versioned API documentation. The tool addresses what Ng calls "agent drift," where models rely on static training data and hallucinate parameters that no longer exist. It is useful. It also makes the core problem explicit: reliable integration code requires grounding in current, vendor-specific documentation that someone has to maintain. AI cannot create that grounding layer. It can only use one that already exists.

## The data transformation problem is harder than it appears

When AI maps fields between systems, it makes reasonable-sounding assumptions that are often wrong in ways that pass type checks.

Consider a vertical SaaS company syncing invoices across [QuickBooks](https://www.apideck.com/integrations/quickbooks), [NetSuite](https://www.apideck.com/integrations/netsuite), [Xero](https://www.apideck.com/integrations/xero), and [Sage](https://www.apideck.com/integrations/sage-intacct). Invoice lifecycle states vary across all four: some use "draft" and "finalized," others use "pending," "approved," and "posted." Tax handling diverges based on regional requirements. Currency conversions follow different rounding rules. Line item structures use incompatible schemas. A field named "status" in one system does not map to "status" in another, and AI does not know this unless explicitly told.

An invoice posted twice is a reconciliation nightmare. A payment applied to the wrong customer creates downstream cascades in reporting and collections. A sync that silently drops records under rate limiting leaves data gaps that surface weeks later during audits. These are not abstract technical problems. They are the specific failure modes of data transformation code that looked correct but carried wrong semantic meaning. This is the same challenge that makes [ERP API integration](https://www.apideck.com/blog/erp-api-integration) one of the most underestimated engineering efforts in B2B software.

## AI hides complexity instead of solving it

This is the most important point and it rarely gets said clearly: AI-assisted integration development relocates complexity rather than eliminating it. This trade-off is especially important in [enterprise software development](https://dreamix.eu/services/enterprise-software-development-services/), where architectural decisions must remain explicit, maintainable, and fully auditable to ensure long-term reliability and compliance. The complexity that used to live in explicit field mappings and error handling code now lives in prompts, context, and implicit assumptions. Using a [prompt generator](https://quillbot.com/ai-writing-tools/ai-prompt-generator) to write clearer, more structured prompts can at least make some of that hidden complexity more explicit and easier to review.

Explicit configuration is inspectable. When an integration fails, you look at the field mapping rules and find the problem. When an AI inferred the mapping, debugging means reverse-engineering what the model decided and why it decided differently for certain records. The integration works 99% of the time, and the 1% failure compounds into data quality issues that take weeks to trace.

For accounting and ERP integrations, where data accuracy has financial and regulatory implications, this is a serious problem. When an auditor reviews a data sync pipeline during a SOC 2 examination, they don't ask "does it work." They ask: show me the access control policy for the credentials this pipeline uses. Show me the rotation schedule. Show me the logs that prove only authorized services accessed customer financial data in the last 90 days. Show me the change management record for the last time this field mapping was modified, who approved it, when, and what was the business justification.

When your field mappings are explicit configuration in version control, every one of those questions has a traceable answer. When an AI inferred the mapping at runtime, the answer is "the model decided." That is not a control. That is a finding.

The limitations of AI-generated integrations are becoming clear even to companies building AI-first products. In March 2026, Perplexity's cofounder and CTO [announced](https://x.com/morganlinton/status/2031795683897077965) that they're moving away from MCP integrations entirely, shifting back to traditional APIs and CLIs. David Zhang, whose team at Duet built full MCP support including OAuth and dynamic client registration, [documented why they deleted the feature](https://x.com/dzhng/status/2029518820872945889): context bloat.

Every MCP tool definition burns tokens before the agent does anything useful. Connect ten services with five tools each and you've consumed thousands of tokens on tool schemas alone. The alternative Zhang describes, agents that write their own integration code on demand, sounds elegant until you consider what that code actually does: the same authentication flows, retry logic, and schema transformations this article has been discussing. The agent might write the integration, but someone still has to maintain the infrastructure it runs on, handle the vendor-specific edge cases, and deal with API deprecations. Self-evolving software is a compelling vision. It is not a substitute for professionally maintained integration infrastructure.

## AI gives the illusion that you can build anything

The ten-minute QuickBooks demo creates a dangerous confidence. If AI can generate working API calls in minutes, the reasoning goes, then the [build-versus-buy calculus](https://www.apideck.com/blog/build-vs-buy-accounting-integrations) has fundamentally changed. Why pay for integration infrastructure when you can just generate it?

This logic fails because it conflates the visible and invisible parts of the iceberg. AI makes the visible part faster. It does not touch the invisible part. The authentication edge cases, the rate limiting, the schema drift, the vendor-specific quirks, the security posture, the monitoring, the maintenance across API version changes: none of this gets easier because AI wrote the initial code. In some ways it gets harder, because the AI-generated codebase carries architectural decisions that are difficult to understand or modify when the original reasoning is not documented anywhere.

The illusion is especially dangerous for teams that have not built integrations before. They see the demo, assume the hard part is done, and commit to timelines based on the 20% they can see. The remaining 80% surfaces during implementation, but by then the project is already staffed and the deadline is set. The result is either a rushed integration that breaks in production or a delayed launch that costs more than buying infrastructure would have.

## The maintenance math is not what it looks like

The commonly cited argument for AI-assisted integration development is that it reduces initial development time significantly, changing the build-versus-buy calculation. This analysis is missing most of the cost.

QuickBooks releases major API versions annually with deprecation windows. NetSuite's API evolves with each product release. Xero introduces breaking changes with limited notice. For each integration, an engineering team needs to monitor for changes, test against new versions, update code, and deploy before deprecation deadlines affect customers. A company supporting ten accounting integrations, eight CRM integrations, and six HR integrations is tracking 24 separate APIs, each evolving independently, with no relationship to the others.

AI may reduce initial development time. It does not reduce monitoring, testing, or migration work. For teams that discover this after building, the AI-generated codebase often carries an additional maintenance penalty: the original generation made architectural decisions that are difficult to understand or modify, because the reasoning behind them is not documented anywhere.

Integration platforms spread maintenance costs across their entire customer base. When QuickBooks releases a new API version, the platform handles the migration once. All customers benefit. The economics are most compelling for companies needing integrations across multiple categories, which is most B2B SaaS companies at scale.

## Where AI actually moves the needle

These limitations define boundaries, not a verdict. All of the above describes what AI cannot reliably do in production integration infrastructure. It is not an argument against using AI. It is an argument for understanding where AI reduces real costs versus where it creates hidden ones.

Onboarding to unfamiliar APIs is dramatically faster. The hardest part of starting a new integration is not writing the code. It is understanding the data model. What does "posted" mean in this system? How does this vendor handle multicurrency? What is the difference between a bill and a vendor credit? Historically this meant hours of documentation reading, forum digging, and sandbox experimentation before writing a single line. AI compresses this. A developer who has never touched Sage Intacct can get oriented on the object model, understand the auth flow, and identify the gotchas worth testing for in minutes rather than days. The output is not production-ready code. The value is the developer arriving at the keyboard already knowing what questions to ask.

Test coverage that would otherwise get skipped also improves. Integration test suites are typically thin because writing them is tedious. Generating realistic edge-case test data ([invoices](https://www.apideck.com/blog/quickbooks-invoice-api-integration) with special characters, zero-amount line items, multicurrency with unusual rounding, records at pagination boundaries) is exactly the kind of mechanical work AI handles well. Teams that use AI for test generation consistently end up with broader coverage than they would have written manually, which means they catch semantic errors before they reach production rather than after.

AI is also useful for documenting tribal knowledge. The undocumented behaviors that live in support tickets and community forums represent real institutional value. AI does not generate this knowledge, but it is useful for capturing and structuring it. The developer who has fought with NetSuite's concurrency limits for two years can describe the behavior conversationally and get back structured documentation the next developer can actually use. That knowledge transfer used to require pairing time.

Field mapping works best as a first draft, not a final answer. The data transformation failures described above happen when AI output is treated as production configuration. If teams treat AI-generated field mappings as a first draft that gets reviewed by someone who knows both systems, the dynamic changes. Starting from a mapping that is 70% correct and needs human review is faster than starting from a blank schema. The error mode is only dangerous when the review step is skipped.

![Top Pitfalls of Letting AI Build Your Integrations img](//images.ctfassets.net/d6o5ai4eeewt/4ZeilFzQaABCvNQfGtVEoI/39cc65fc4db72638ca3180661a8bff32/article_pitfalls_ai.png)

## A safer architecture

The practical answer is not to avoid AI, but to use it where it accelerates development without controlling production data flows.

Use AI during development, not at runtime. Field mappings, transformation rules, and business logic should exist as documented configuration that engineers can inspect and modify, not as AI inference. The hardest parts of integrations (authentication, error handling, retry logic, rate limiting, and maintenance) should run on reliable infrastructure, not on model output.

The architecture that actually works in practice splits the problem in two. A [unified API platform](https://www.apideck.com/unified-apis) handles the infrastructure: authentication, pagination, rate limiting, schema normalization across more than 200 connectors spanning CRM, accounting, HRIS, eCommerce, and the rest. Your engineering team and your AI tooling build against one stable interface instead of fighting each vendor's API individually. That is what Apideck does. AI handles the application logic on top. The integration infrastructure underneath is someone else's problem, professionally maintained.

## The real question for engineering leadership

The strategic question is not whether AI can generate integration code. It can. The question is whether that changes where engineering time should go.

Most B2B SaaS companies that have thought carefully about this reach the same conclusion: integrations are necessary but not differentiating. They are infrastructure, and infrastructure that your engineering team owns is infrastructure your engineering team maintains indefinitely. The opportunity cost is the product work that does not get built because the sprint was spent debugging a QuickBooks API deprecation that your integration platform would have handled automatically.

AI changes a lot about software development. It does not change the fundamental economics of integration maintenance, the necessity of vendor-specific expertise, or the value of having someone else own the problem. What it does change is the cost of the development work that sits on top of reliable infrastructure: orientation, test generation, documentation, first-draft mapping. These are real costs, and AI reduces them meaningfully.

The combination of reliable infrastructure and AI-assisted development is genuinely better than either alternative alone. The mistake is conflating the two and assuming that because AI helps with one, it can substitute for the other.

AI can speed up building integrations, but production ready integrations are far more complex. This article explores the hidden risks including authentication issues, data mapping errors, security gaps, and maintenance challenges. It shows where AI for building integrations adds value, where it creates blind spots, and how to build reliable, scalable integrations without compromising performance or compliance.


Top Pitfalls of Letting AI Build Your Integrations

Most people in fintech are sleeping on accounting right now. They're watching agentic payments, watching AI coding assistants, watching the LLM infrastructure wars. Meanwhile, one of the most fundable and least-competed categories in B2B software is quietly getting rebuilt layer by layer, and the window to build something meaningful in it is right now.

The framing you usually hear is that accounting software is getting AI features bolted on. A chatbot here, an auto-categorization toggle there. That is not what is happening. What is actually happening is that the entire accounting stack (the ledger, the close, FP&A, audit, tax, payments) is being rebuilt from the ground up by companies that treat AI as their architecture, not a feature on top of someone else's architecture. And the numbers backing this are not speculative anymore.

[Basis AI](https://www.getbasis.ai/) raised a $100M Series B at a $1.15 billion valuation. Stacks closed a $23M Series A from Lightspeed. Campfire pulled in $100M across back-to-back rounds. Digits has raised north of $100M from Benchmark and SoftBank. Datarails raised a $70M Series C and then declared, with a straight face, that traditional FP&A software is dead.

These are not feature bets. This is a platform shift.

## Why AI in Accounting Is Moving Faster Than Anyone Expected

The number of accountants in the US has fallen 15.9% since 2019. CPA exam candidates dropped 33% between 2016 and 2021. The profession has a structural talent shortfall that is not going to be solved by better recruiting. And on the demand side, businesses are not waiting: 64% now use ChatGPT for financial guidance before they even call their accountant, according to a [Ravical](https://ravical.com) survey of 500 UK businesses. More than half of those businesses then need someone to fix what the chatbot got wrong.

![Ravical AI Accounting for Advisory](//images.ctfassets.net/d6o5ai4eeewt/33dua3dEyj647lN744PPki/f64b051e0d08911a3c4ecee5dc755636/Screenshot_2026-04-05_at_19.02.25.png)

So you have a profession that is short-staffed, overwhelmed, and watching its clients try to replace it with a general-purpose LLM. That is the setup. And it is why capital is flooding into AI accounting software at a pace the industry has never seen. The AI in accounting market hit roughly $10 billion in 2026 and is growing at over 40% annually.

But market size tells you little. The product map is what matters.

## AI Bookkeeping: Rebuilding the Ledger Itself

The most aggressive bet in AI bookkeeping is [Digits](https://digits.com/), which is not building AI on top of a general ledger. It is rebuilding the ledger. Their Autonomous General Ledger is trained on over $825 billion in small business transactions and claims 97.8% categorization accuracy versus 79.1% for human outsourced bookkeepers. AI agents handle categorization, reconciliation, invoicing, and reporting from a single system. The bet is that if you build the ledger as an AI-native system from the start, you don't need a layer of automation on top. The ledger just knows what the transactions mean.

[Artifact AI](https://www.getartifact.com/), backed by a16z, takes the opposite approach. They sit on top of existing systems like QuickBooks and Xero, using a "financial events" abstraction layer to run end-to-end bookkeeping workflows, claiming 99% reconciliation accuracy. Their argument is that you don't need to replace the ledger to make it intelligent. You need to build the right reasoning layer on top of it.

Both bets are credible. The architectural question of whether to replace the ledger or make the existing one smarter is genuinely open, and which answer wins will matter enormously for everyone building integrations in this space.

Then there's [Ordinal](https://www.ordinal.sh/), a smaller bet and an interesting one. "Accounting that runs itself" for one-person businesses. Their architecture is deliberately minimal: the ledger is the sole source of truth, every business event is recorded as a standardized entry, and an AI that understands your full business context can explain any entry in plain language. If a bank transaction shows interest income from Swedbank, you ask the AI whether it counts as profit and it tells you exactly how it maps to your tax form. It's not impressive engineering at the same scale as Digits, but it points at something real: the next generation of accounting software will feel less like software and more like a CFO you can talk to.

## AI for Month-End Close: From a Week of Work to a Single Workflow

This is where the most acute operational pain lives in accounting, and where some of the sharpest AI products are emerging.

[Mimo](https://mimohq.com/accountant), rated 5.0 stars on the Xero app store, targets UK accounting firms with a product they describe as "turning a week of manual work into one streamlined workflow." Their Mimo Associate uses AI agents to prepare journals, flag anomalies, and keep books client-ready. One firm customer: "I get an email from Mimo saying a payment run needs to be approved. I click a button, log in, approve. It takes less than a minute instead of half an hour." In March 2026 they shipped Collect, Scan & Reconcile, built around what they say is the hardest part of month-end: getting documents from clients in the first place.

[Stacks](https://stacks.ai/), with its $23M Series A from Lightspeed, is going after larger companies. The diamond marketplace Nivoda cut their monthly close by eight days and automated 95% of reconciliations using Stacks. Epidemic Sound is another customer.

[Eagl](https://www.geteagl.com/), a Belgian startup based in Gent, built what is arguably the most precise AI accounting product in the close space: real-time financial controlling. Their agents don't wait until month-end to find problems. They catch them as they happen. In their live product you can see exactly the kind of errors that slip through in manual closes: an annual insurance premium of €89,450 booked entirely in December when it should be amortized monthly at €7,454.17; a €156,800 IT purchase miscategorized as maintenance instead of CAPEX; a €112,500 duplicate marketing invoice. Each finding comes with the specific account, the amount, the suggested correction journal entry, and a link back to the source document in the ERP. Live in 48 hours, integrates with NetSuite, Exact Online, and others. Customers include Channable, Aikido, and Bluecrux.

## AI for FP&A: The Category Is Being Declared Dead by Its Own Incumbents

Datarails CEO Didi Gurfinkel made headlines by declaring FP&A software dead and launching FinanceOS, a governed data layer connecting to 400+ sources that lets finance teams use whatever AI model they want to run analysis. His framing: "You don't see any programmer that actually types on their keyboard anymore. Almost 100% of their code is written by AI. I'm confident it will be exactly the same for finance people." He calls it vibe coding for finance.

The interesting thing about that statement is that he's the CEO of a leading FP&A software company saying it. He's not a challenger declaring an incumbent dead. He's the incumbent declaring himself dead and trying to get out ahead of it. Publicly burning your own category before someone else burns it for you is what you do when you genuinely believe the shift is structural and fast.

Intuit is moving the same direction inside QuickBooks: a virtual team of AI agents handling payments optimization, bookkeeping, sales tax, and financial reporting. They claim 12 hours saved per month and businesses getting paid five days faster. The agents read business context and act without configuration.

But not everyone in the controller's seat shares the same pace of optimism, and their reasoning is worth sitting with. [Melissa Montgomery](https://ramp.com/velocity/ai-cracked-the-easy-part-of-accounting-the-hard-part-is-next), VP Controller at Ramp, writing from the seat of a company doing over $1 billion in annualized revenue, puts the automatable share of accounting work at 5 to 10% of the team at a large company. Those are the people handling AP, travel and expenses, simple reconciliations, and basic GL work. The other 90 to 95% are doing work that does not follow a clean rules-based process: cash accounting with hundreds of transaction permutations, GAAP interpretation, revenue recognition, equity accounting. Two smart accountants can look at the exact same revenue recognition question or complex equity transaction and reach different conclusions. That judgment layer is not going away. The adoption numbers support this grounding. As of 2025, only 14% of North American companies were using AI to automate repetitive tasks like invoice matching and reconciliation, according to a Visa report. Two-thirds of AP teams told PYMNTS their manual work had actually increased from 2024 to 2025. The gap between what AI can do in demos and what companies have actually deployed is still wide.

## AI in Audit: The Most Conservative Layer Is Moving Fast

Audit was supposed to be the last part of accounting to change. The liability exposure, the regulatory requirements, the human signature on everything. All of it pointed toward a profession that would resist AI longest. That assumption is wrong.

[Tellen](https://www.tellen.ai/) built an AI agent workforce specifically for audit firms. Their agents read from the firm's system of record, automate evidence collection through portals like Suralink, run multi-layer attribute testing, and write completed workpapers back using the firm's own templates, with every AI decision logged with its full reasoning chain. One firm achieved 332% ROI and saved nearly 300 hours on a single engagement. Customers include Grant Thornton, Baker Tilly, CohnReznick, and Citrin Cooperman. The product deploys into the firm's own cloud (Azure, AWS, or GCP) so client data never leaves their environment. They use outcome-based pricing: they win when the firm wins.

[Trullion](https://trullion.com/) is taking a narrower path: automating lease accounting under ASC 842 and IFRS 16, plus revenue recognition. These are areas where the rules are complex, the manual work is substantial, and the audit trail requirements mean you need full traceability on every AI action.

## AI for Tax Preparation: The Return as a Byproduct

[Sweet](https://verysweet.co/) is doing for individual tax preparation what the above tools are doing for close and audit. Their AI agent turns messy client documents into review-ready 1040 returns. They claim to handle 99% of 99% of Federal 1040s: K-1s, Schedule C/E/D, adjustments, credits, cross-border reporting. The preparer shifts from data entry to review. CPA Robby Nelson: "We've based our entire expansion strategy of our firm on Sweet. Our firm's livelihoods depend on this." CPA Echo Zhong: "We used to chase documents, now we chase ROI."

## AI for B2B Payments and Treasury: The Downstream of Clean Books

Once you have a real-time AI-maintained ledger, the downstream use cases open up fast.

[Round Treasury](https://www.roundtreasury.com/) built an AI-native treasury command center for venture-backed startups: agents that monitor accounts, sweep cash, execute FX conversions, and reconcile everything back into Xero automatically. Balance made B2B payments agent-ready, launching an MCP server that lets AI agents interact directly with their payments, credit, and receivables APIs in real time. Mimo extended their close automation into Mimo Pay for AP and Mimo Flex for working capital, turning accounting firms into embedded finance providers because they now have real-time visibility into client cash positions.

The pattern here is important. Each of these AI payment and treasury products is only possible because there is a clean, real-time financial data layer underneath it. The payments are the downstream of the ledger. That sequencing (get the accounting right first, then automate the money movement) is the right order of operations, and the companies that understand it are building much more defensible products than the ones trying to do payments without fixing the books first.

## The Integration Problem Most AI Accounting Startups Underestimate

Here is what most teams building in this space get wrong: the moat is not the AI model. It never was. Every team building here has access to the same foundation models. The moat is the financial data layer: clean, governed, real-time, auditable. And the accounting integrations that feed it.

This is something we see directly at Apideck. The companies building AI-native accounting tools are not bottlenecked by their AI capabilities. They're bottlenecked by data access. They need to read from and write to the customer's actual accounting system: QuickBooks, Xero, Sage, NetSuite, FreshBooks. And those systems are fragmented, inconsistently structured, and painful to integrate one by one. The teams that treat integration as a first-class problem, building on a [unified accounting API](https://www.apideck.com/accounting-api) from the start rather than bolting it on later, are moving faster and spending their engineering hours on the actual differentiated product.

Xero publishing an official MCP server on GitHub is a signal of where this is heading: accounting data becoming natively programmable by AI agents. Every major ledger will follow. When that infrastructure matures, the question is not whether your AI can access the data. The question is whether your data model is clean enough to act on it reliably.

Round Treasury understood this early. They use [Apideck](https://www.apideck.com/blog/the-complete-guide-to-accounting-api-integrations-for-fintech) to connect to customers' accounting systems so they're not maintaining 30 separate ledger integrations. That's an extra engineering team's worth of leverage directed at the actual product.

## Where AI in Accounting Goes From Here

Karbon's State of AI report (Karbon is the practice management platform used by 3,000+ accounting firms) shows 98% of accounting professionals now use AI, saving an average of 21 hours per month per employee. Firms that invest in AI training see 71% more time savings than beginners. The gap between AI-native firms and everyone else is compounding, not closing.

PwC's Chief AI Officer described the accounting workforce shifting from a pyramid to an hourglass, with more concentration at junior and senior levels and compression in the middle. Ramp's Melissa Montgomery is already hiring with this in mind, evaluating junior candidates not on technical accounting mechanics but on whether they can develop into someone who can own a complex problem and make a judgment call. The skills that once defined accounting leadership are becoming requirements throughout the org. Routine bookkeeping faces an 85% automation risk. What remains at the junior level looks more like AI operations and exception handling than traditional accounting work.

The $100 billion "Office of the CFO" software market is being re-platformed. Legacy incumbents were built for a world where humans processed every transaction. The companies replacing them assume AI does the processing and humans do the judgment. Those are fundamentally different architectures, and you cannot get from one to the other by adding features.

For fintech founders, the opportunity is real and the timing is right. Pick a layer of this stack. Own it with an AI-native architecture. The incumbents are slow, the talent crisis is structural, and the capital market for this category is open. The entire accounting stack is being rebuilt from scratch, and most of the interesting positions in it are still available.

AI in accounting isn't about features bolted onto old software. The entire stack (ledger, close, FP&A, audit, tax, payments) is being rebuilt from scratch by a new wave of well-funded startups. Here's the full map.

AI in Accounting in 2026: The Entire Stack Is Being Rebuilt From Scratch

Toast made $5 billion from financial services last year. Its software subscriptions brought in $936 million. That ratio tells you everything about where [embedded finance](https://apideck.com/blog/what-is-embedded-finance) for vertical SaaS is headed.

The pattern repeats across industries. Shopify's merchant solutions, spanning embedded payments, lending, and banking, now account for 73% of total revenue. Mindbody generates more than half its revenue from embedded financial products. These are software companies by origin, but financial services companies by revenue.

Embedded finance for vertical SaaS has become the business model. Most vertical SaaS founders are now focused on how to build the fintech stack correctly, not whether to build it at all.

## The vertical SaaS fintech playbook: payments first, then everything else

Every vertical SaaS company that has pulled this off followed a nearly identical playbook. Embedded payments come first. Then [embedded lending](https://apideck.com/blog/embedded-lending-revenue-financing-banking-accounting-commerce-data). Then insurance, banking, payroll, and cards. The order matters because each layer depends on data from the one before it.

Toast started with card processing through its POS terminals. Once it had transaction data on 164,000 restaurant locations, it could underwrite working capital loans (Toast Capital, $5,000 to $300,000 per loan, repaid as a percentage of daily card sales). Payroll came next, then insurance, then the Toast Pay Card for instant wage access.

![Toast Capital](//images.ctfassets.net/d6o5ai4eeewt/3ZT2Ue8Dmc0dBQNcIZLZck/aa5a187c1ca2282c907050f94c67d5a4/Screenshot_2026-04-03_at_21.21.17.png)

Shopify followed the same arc. Shopify Payments now handles 68% of all GMV on the platform. That data feeds Shopify Capital, which originated $4.2 billion in merchant cash advances and loans in 2025 alone. Capital Flex, a revolving credit line launched in late 2025, signals the next step. Shopify Balance adds a spending card, faster payouts, and expense categorization directly inside the admin dashboard.

ServiceTitan processes tens of billions in gross transaction volume across its 9,500 contractor customers. In September 2025, it added BNPL through Affirm, letting homeowners finance large HVAC or plumbing jobs directly from the technician's tablet. Management estimates the company captures only 50% of its available take rate, meaning the fintech revenue line has room to double without adding a single new customer.

Procore took a different entry point in construction. It launched Procore Risk Advisors in March 2024, partnering with Allianz and Swiss Re to offer builders' risk and general liability policies. Procore Pay handles subcontractor payments with automated lien waiver management. Material Finance gives contractors extended payment terms for supplies.

The common thread: each financial product becomes possible because the platform already owns the workflow data that traditional banks would need months to collect.

## Embedded payments revenue and take rates: the real economics

[Andreessen Horowitz](https://a16z.com/fintech-scales-vertical-saas/) found that adding fintech features to vertical SaaS increases revenue per customer by 2x to 5x. The [Payrix 2023 Embedded Finance Survey](https://get.payrix.com/hubfs/State-of-Embedded-Finance-Report-2023.pdf) reported that over 40% of a platform's customers typically adopt embedded financial products, with revenue growing by an average of 40% per product launched.

Toast's numbers show how this compounds over time. Locations that stay on the platform for five years reach an average ARR of $16,000, a 6x increase from their initial spend. Net revenue retention sits at 109%. The bulk of that expansion comes from financial services, not software upsells.

The margin profile depends on how you implement payments. Using a managed payment facilitator like [Stripe Connect](https://apideck.com/blog/introduction-to-the-stripe-api) costs roughly 3% plus a per-transaction fee, leaving thin margins. Moving to a white-label PayFac model through providers like Finix or Payrix captures around 50 basis points per transaction. Full in-house PayFac status (what Toast built) yields 50 to 100 basis points but requires at least $50 million in annual volume and serious compliance infrastructure. As [Fractal Software's analysis](https://www.fractalsoftware.com/perspectives/the-vertical-saas-fintech-playbook) noted, a company processing $100 million per year through a managed PayFac leaves approximately $500,000 in margin on the table.

Retention tells an equally compelling story. [BCG and Adyen's 2025 research](https://www.bcg.com/publications/2025/moving-embedded-finance-from-promise-practice) found that embedded payment strategies help SaaS platforms retain customers at 2.5x the rate of traditional payment providers. [Visa's analysis](https://www.visa.co.uk/content/dam/VCOM/regional/ve/unitedkingdom/PDF/vca/uk-vca-verticalization-whitepaper.pdf) of five European markets showed that verticalized acquirers achieve 19 percentage points higher payment volume growth and 5% less merchant attrition compared to horizontal competitors.

## Embedded accounting: the missing layer in the fintech stack

Embedded payments, lending, and banking create value. But they also create a reconciliation problem.

A restaurant running Toast Payments, Toast Capital, and Toast Payroll has money flowing through multiple rails every day. Tips need to be distributed. Loan repayments deducted. Payroll taxes withheld. If none of that connects to the general ledger, the restaurant owner is back to exporting CSVs from three systems and manually keying entries into QuickBooks. The very financial products that were supposed to simplify their life have made bookkeeping harder.

Toast understood this early. Its xtraCHEF acquisition gave it AP automation with line-item invoice coding that syncs directly to QuickBooks general ledger accounts. Through integration with Restaurant365, daily sales journal entries and labor accrual entries are generated automatically. Toast claims payroll processing takes 30 minutes or less, with a third of users finishing in under 10 minutes. The entire financial loop is closed: sale captured, payment processed, tip distributed, payroll calculated, books updated.

This [accounting integration](https://apideck.com/blog/accounting-software-integration) layer is where the real lock-in happens. A platform that processes your payments is replaceable (switching costs are real but finite). A platform that processes your payments, underwrites your loans, runs your payroll, and maintains your general ledger is practically permanent.

The data backs this up. Platforms with embedded accounting report [38% higher ARPU and 20% higher customer lifetime value](https://www.openledger.com/openledger-hq/unlocking-38-higher-arpu-data-driven-revenue-gains-from-embedded-accounting-in-vertical-saas-open-ledger), according to Open Ledger's analysis. Roofstock achieved 3.5x higher retention among landlords using its Stessa Cash Management accounts (built on [Unit's](https://www.unit.co/vertical-saas) infrastructure), which included integrated bookkeeping. Baselane, a landlord management platform, cut customer acquisition costs by 50% after launching embedded finance with accounting built in.

From the other direction, Intuit has been adding financial products to QuickBooks: term loans up to $200,000 through WebBank, BNPL via an Affirm partnership embedded directly into QuickBooks invoices, and integrated payment acceptance. The [accounting incumbents are converging](https://apideck.com/blog/erp-banking) on the same model from the opposite direction.

## Embedded finance platforms and infrastructure providers

Five years ago, building an embedded finance stack for vertical SaaS required stitching together a dozen vendors and navigating bank sponsorship agreements that took 12 to 18 months to close. That friction has largely been removed.

[Unit](https://www.unit.co/vertical-saas) has enabled roughly 200 platforms to launch embedded banking, processing $40 billion in transactions annually for nearly 2 million end-customers. Unit explicitly offers QuickBooks integration so that platforms' customers can connect embedded accounts to their existing accounting software. Stripe powers payments, lending, treasury, and terminal hardware for platforms like Lightspeed and Jobber through a single integration. Parafin specializes in embedded capital, powering the lending products for platforms that lack the scale to build their own underwriting.

A newer wave of companies is tackling the [accounting piece](https://apideck.com/blog/12-best-practices-for-accounting-integrations-in-vertical-saas) directly. Tight offers journals, ledgers, revenue recognition, and reconciliation as embeddable API infrastructure. Open Ledger provides AI-powered embedded accounting with real-time transaction reconciliation. And Modern Treasury automates the full cycle from payment initiation through to reconciliation.

The critical gap in most embedded finance stacks is the connection between where [money moves](https://apideck.com/blog/money-movement-infrastructure-fintech-ledger-as-a-service) and where it gets recorded. Platforms that close this gap create a single financial operating system for their customers. Those that leave it open create a fragmented mess that increases support costs and churn.

## Embedded finance market size: $185 billion, mostly untapped

[BCG and Adyen](https://www.bcg.com/publications/2025/moving-embedded-finance-from-promise-practice) estimate the total addressable market for embedded finance at $185 billion across North America and Europe. Only about $32 billion of that has been captured. SaaS providers with integrated payments accounted for 36% of SME acquiring revenues in 2024, projected to reach 45% by 2028. Unit reports that more than half of businesses now run on vertical-specific software, a 60% increase in six years.

Regulatory pressure is increasing. The CFPB's open banking rule has its first compliance deadline in April 2026 for large data providers. States are tightening true-lender doctrines for bank-fintech partnerships. BNPL providers are being treated more like credit card issuers under a 2024 CFPB interpretive rule. These changes will likely favor platforms with strong compliance infrastructure and established banking relationships over smaller players attempting to bolt on financial products with minimal oversight.

The vertical SaaS companies that win over the next five years will be the ones that own the full embedded finance stack for their industry: payments in, lending when needed, payroll out, insurance covered, and every transaction automatically reconciled in the books. The software is the distribution channel. The money is the product.

For a deeper look at how platforms should approach the accounting layer specifically, see our guide to [accounting integrations in vertical SaaS](https://apideck.com/blog/12-best-practices-for-accounting-integrations-in-vertical-saas) and [using accounting APIs for lending decisions](https://apideck.com/blog/using-accounting-apis-for-smart-lending-decisions).

Vertical SaaS companies like Toast and Shopify now earn most of their revenue from embedded payments, lending, and banking. Real data on revenue, take rates, and the fintech stack that makes it work.

Embedded Finance for Vertical SaaS: How Payments Became the Real Product

The accounting concepts developers actually need when building API integrations. Chart of accounts, invoices, reconciliation, tax, and multi-currency with code examples.

Accounting for Developers: The 2026 Guide

A developer's guide to stablecoin APIs in 2026: Stripe, Circle, Fireblocks, Paxos, and the x402 agentic payment protocol. Covers API surface, custody models, gas fee abstraction, GENIUS Act compliance, and machine-to-machine payment flows.

Stablecoin APIs are the new payments infrastructure layer

[Shopify Capital](https://www.shopify.com/capital) originated $4.2 billion in merchant cash advances and loans in 2025, up from $3 billion in 2024. [Wayflyer](https://www.wayflyer.com/) has deployed over $5 billion to more than 5,000 small businesses. [Parafin](https://www.parafin.com/) has extended over $25 billion in offers across Amazon, DoorDash, Walmart, and dozens of vertical SaaS platforms. These numbers keep climbing because these companies figured out something traditional banks never did: the best way to underwrite an SMB is to watch it operate in real time, across every system where money moves.

The common thread is data. Not a single data source, but three layered together: banking transactions, accounting records, and commerce platform activity. Each source tells a different part of the story. Together they tell the whole thing.

## What banking, accounting, and commerce data reveal to lenders

Banking data shows cash reality. It tracks what comes in and what goes out, including overdraft patterns and loan repayments to other lenders. When Wayflyer onboards an ecommerce merchant, the first thing they request is access to bank account data via open banking aggregators. Their underwriting team uses that transaction history to assess business performance and creditworthiness. But as Wayflyer discovered when scaling across markets, raw open banking data is messy. Transaction descriptions are inconsistent. Categorization is unreliable. They partnered with Ntropy specifically to enrich and standardize bank transaction data so their ML models could actually interpret what merchants were spending money on. Spending at Amazon versus spending at a restaurant means two very different things to an underwriter.

Accounting data adds structure and context that bank statements alone can't provide. A profit and loss statement shows margins. A balance sheet shows liabilities. Accounts receivable data reveals whether customers pay on time or 90 days late. Accounts payable data shows whether a business is under pressure from creditors. This is why the lending industry has moved toward standardizing accounting data alongside banking and commerce sources through [unified APIs](https://www.apideck.com/use-cases/business-lending-loan-underwriting). Lenders who rely on bank statements alone miss critical signals. A business might show healthy bank balances while carrying mounting trade payables that signal distress. Or a business might look cash-poor while sitting on $500K in outstanding invoices from creditworthy customers.

Commerce data completes the picture. Platforms like Shopify and Amazon Seller Central know daily sales volumes, refund rates, customer acquisition trends, and seasonal patterns. Shopify Capital uses machine learning to analyze exactly these signals, including sales history, disputes, and customer engagement, to generate pre-approved offers for merchants without them even applying. The AI makes the first pass. A human reviews before funds move. Repayment happens automatically as a percentage of daily sales.

## How revenue financing platforms onboard merchants

Across nearly every revenue based financing platform that has scaled, the onboarding flow follows the same structure. The merchant connects their commerce platform, then their bank accounts via open banking or Plaid, then their accounting software. The more data sources a merchant connects, the faster the decision and the better the terms.

Paperstack, which picked up former Clearco customers, underwrites ecommerce loans based on ecommerce, accounting, and financial data. Their team reviews connected data and presents funding offers within 24 to 48 hours, with fees ranging from 4% to 12% depending on repayment history and risk profile. Uncapped follows a similar model in Europe, connecting to commerce, payment, accounting, and advertising platforms to build a composite view of business health.

[Swoop](https://swoopfunding.com/) takes a different approach as a funding marketplace rather than a direct lender. Operating across the UK, Ireland, US, Canada, Australia, and South Africa with over 200,000 clients and 1,000+ funding providers, Swoop matches businesses to the right financing option using data from their bank accounts and accounting systems. They use open banking for transaction data and connect to accounting platforms like Sage through [Apideck's unified Accounting API](https://www.apideck.com/accounting-api/payments). That Sage integration became a global co-marketing partnership, giving Swoop distribution into Sage's customer base across multiple markets. Swoop's COO Ciaran Burke has said that access to richer data from bank accounts and accounting platforms allows for better lending decisions and faster capital.

![Swoop Funding Integrations](//images.ctfassets.net/d6o5ai4eeewt/6HHiDrTliEDK4GWFg5A72a/2099ad77c00ea78f019e5ed0ca018b36/swoop-integrations.webp)

[Fundwell](https://www.fundwell.com/), which connects businesses with over 60 funding partners across more than 50 industries, has automated its document analysis and risk profiling to the point where underwriting workload dropped by 30 hours per week, supporting a 76.6% increase in onboarded customers. The pattern is the same everywhere: connect the data, automate the assessment, compress the time to funding.

The speed advantage is real. According to a comparison published by Luca AI, approval speed correlates directly with data integration depth. Platforms with direct API access to commerce, payment, and accounting systems approve in hours. Those requiring manual financial statement uploads take weeks. Traditional banks take 6 to 12 weeks minimum. Fifty-seven percent of all SME credit applications in the UK are either abandoned because the process is too hard or ultimately rejected, according to Plaid's analysis of the UK market.

## Embedded lending changes the integration model

The most interesting shift in SMB lending is happening inside platforms themselves. Instead of merchants going to a separate lender, the lending is embedded into the software they already use.

Parafin powers embedded capital programs for major marketplaces and vertical SaaS companies alike. Their underwriting engine runs on ML models trained on data from over 2 million small businesses. When a DoorDash restaurant gets a pre-approved capital offer inside the DoorDash app, Parafin is running the underwriting behind the scenes using the merchant's sales history on the platform. The merchant never fills out a loan application or submits a credit check. The financing appears inside the platform they already operate in. Parafin ranked 15th on the 2025 Inc. 5000 list, which gives you a sense of how fast this model is growing.

[Kanmon](https://kanmon.com) targets a similar opportunity but focuses specifically on vertical SaaS and marketplace platforms. Kanmon provides the embedded lending infrastructure (term loans, lines of credit, invoice financing, AP financing) so that platforms can offer capital to their SMB customers without becoming lenders themselves. Kanmon handles underwriting, compliance, and servicing behind the scenes. What's notable is that Kanmon explicitly states platforms don't need to offer embedded payments before offering embedded lending, though underwriting benefits from payment data when it's available. The company analyzes financial information and business history to tailor risk assessments per product type, with most customers funded within one to two days. You can find Kanmon alongside other embedded lending providers in the [Open Banking Tracker's embedded finance directory](https://www.openbankingtracker.com/embedded-finance).

[Stripe Capital](https://stripe.com/capital) works the same way for businesses processing payments through Stripe. Eligibility requires at least 90 days on the platform and $1,000 in average monthly sales. Transaction history and dispute rate determine the offer. Squarespace launched embedded lending powered by Stripe Capital in January 2025 and surpassed its entire annual goals within a single quarter, according to Corey Zettler, Director of Product for Financial Solutions at Squarespace.

Shopify takes it furthest. Capital flex, launched in November 2025, gives qualifying merchants continuous access to funds with a credit limit that adjusts based on real-time business metrics. There is no application and no fixed loan term. It is a rolling line of credit powered by the data Shopify already collects from running the merchant's entire commerce operation.

## What this means for vertical SaaS and embedded finance builders

The pattern here is clear, and it has direct implications for anyone building lending products, vertical SaaS platforms, or embedded finance features.

Single-source underwriting is dying. Banking data alone misses accounting context. Accounting data alone can be stale or manipulated. Commerce data alone lacks the full financial picture. The winning models combine all three through a single integration layer. When open banking data is paired with real-time accounting data, lenders can cross-reference actual financials with what was submitted in the application, catching fraud and improving accuracy simultaneously. This is why unified APIs that connect accounting, banking, and commerce data in a single integration have become critical infrastructure for lending platforms.

That makes the integration layer the real moat. The lenders winning in this market are not the ones with the most capital. They are the ones with the deepest integrations into the systems where business data lives. Shopify can underwrite better than any bank because it sees every transaction, every refund, every customer dispute. Parafin can extend offers across dozens of platforms because it built configurable underwriting infrastructure that can run inside a partner's environment without the partner even sharing raw merchant data with Parafin's servers.

[Float Financial](https://www.floatfinance.com/) in Canada shows where this is heading for vertical SaaS. Float started as a spend management platform with corporate cards and expense software. It now serves over 6,000 Canadian businesses, raised a $100 million debt facility from Silicon Valley Bank in January 2026, and launched Float Charge, a short-term working capital product. Float's visibility into real-time spending data and accounting integrations (NetSuite, Xero) positions it to underwrite working capital loans using data it already collects from running its customers' daily financial operations. Sacra's analysis notes that this positions Float for the $40 billion Canadian SMB lending market. That trajectory, from software platform to embedded lender, is one that any vertical SaaS company with transaction data could follow.

The opportunity for vertical SaaS companies follows directly from this. If your platform processes payments, manages inventory, or handles accounting for your customers, you are sitting on the data that lenders need. The embedded lending model, powered by infrastructure providers like Parafin or Kanmon, or built with [unified APIs for accounting data](https://www.apideck.com/use-cases/business-lending-loan-underwriting), turns that data into a revenue stream and a retention tool simultaneously.

The $901 million revenue based financing market from 2019 was projected to reach $42.3 billion by 2027. Looking at the origination volumes from Shopify, Wayflyer, and Parafin alone, that projection looks conservative. The platforms that control the data layer, connecting banking, accounting, and commerce in a single onboarding flow, are the ones writing the checks.

Revenue financing and embedded lending platforms use banking, accounting, and ecommerce data together to onboard and underwrite SMBs in hours, not weeks. Here's how.

Embedded Lending: How Revenue Financing Platforms Use Banking, Accounting, and Commerce Data

Plaid is the financial data infrastructure company that connects applications to bank accounts. If your product needs to pull transaction data or verify bank account ownership, Plaid is probably on your shortlist. Most fintech apps in the US and Canada rely on Plaid to handle the messy reality of connecting to [9,600+ financial institutions](https://www.openbankingtracker.com/api-aggregators/plaid) through a single API.

You're here because you need a Plaid API key to connect your app. Here's how to get your credentials and make your first request without reading their entire documentation.

## Prerequisites

Before you start, make sure you have:

- An email address for your Plaid account (business email preferred for production approval)
- A clear idea of which Plaid products you need (Transactions, Auth, Identity, Balance, etc.)
- Node.js, Python, Ruby, Go, or Java installed if you want to use one of Plaid's official client libraries

## Step 1: Create a Plaid account

Go to [https://dashboard.plaid.com/signup](https://dashboard.plaid.com/signup) and create an account. Plaid will ask for basic information about you and your company. Complete the signup process and acknowledge their terms of service. Plaid's own [quickstart guide](https://plaid.com/docs/quickstart/) walks through the full flow if you want the longer version.

Once you're in, you'll land on the Plaid Dashboard. This is where you manage API keys and production access.

## Step 2: Find your Plaid API keys

From the Dashboard, navigate to **Developers > Keys** (or go directly to [https://dashboard.plaid.com/developers/keys](https://dashboard.plaid.com/developers/keys)). This is where Plaid stores your API keys.

You'll see two credentials:

- **client_id**: A unique identifier for your application. This stays the same across all environments.
- **secret**: An environment-specific key. You'll get a separate secret for each Plaid environment.

![Plaid API keys dashboard](//images.ctfassets.net/d6o5ai4eeewt/3yExyqaeuKqKGhPY7gVd9v/dd457e40ca148544750d2ffcf8265a7b/Screenshot_2026-03-28_at_10.52.49.png)

Plaid uses two environments:

- **Sandbox** (sandbox.plaid.com): Free test environment with simulated bank data. No real financial institutions, no billing. This is where you build and test.
- **Production** (production.plaid.com): Real bank connections, real data, real billing. Requires approval from Plaid before you can access it.

Your Sandbox secret is available immediately after signup. Copy it now.

## Step 3: Understand how Plaid authentication works

Plaid's server-to-server authentication is straightforward. Every API request requires your `client_id` and `secret`, passed either as headers (`PLAID-CLIENT-ID` and `PLAID-SECRET`) or in the JSON request body. The full details are in Plaid's [API overview](https://plaid.com/docs/api/).

There's no OAuth token exchange for server-side API calls. You send your credentials with each request. The OAuth-style flow in Plaid (called Plaid Link) is the client-side component your end users interact with when connecting their bank accounts. That's a separate concern from getting your API keys.

## Step 4: Store your credentials securely

Add your `client_id` and `secret` to environment variables. Never hardcode them in your application code.

```bash
export PLAID_CLIENT_ID='your_client_id_here'
export PLAID_SECRET='your_sandbox_secret_here'
export PLAID_ENV='sandbox'
```

If you're using a `.env` file for local development, add it to your `.gitignore` immediately. Plaid secrets pushed to a public repository are a real risk, especially once you have production credentials.

## Step 5: Set up billing (when you're ready for production)

Sandbox usage is always free. When you're ready to go live, you'll need to request Production access through the Dashboard by selecting **Migrate to Production** and filling out the application.

Plaid offers three [pricing tiers](https://plaid.com/pricing/):

- **Pay as you go**: No minimum spend, standard per-use rates. Good for early-stage projects.
- **Growth**: Annual commitment with lower per-use costs. Includes a personal account manager.
- **Custom**: For high-volume usage above $2,000/month. Contact Plaid's sales team.

Your first 200 production API calls are free under Plaid's Limited Production access, so you can test with real bank connections before committing to a plan.

## Test your Plaid API key

Create a test Item in the Sandbox using Plaid's sandbox-only endpoint. This bypasses the Link UI flow and lets you verify your credentials directly:

```bash
curl -X POST https://sandbox.plaid.com/sandbox/public_token/create \
  -H "Content-Type: application/json" \
  -d '{"client_id": "YOUR_CLIENT_ID", "secret": "YOUR_SANDBOX_SECRET", "institution_id": "ins_109508", "initial_products": ["transactions"]}'
```

A successful response returns a `public_token`. You can then exchange it for an `access_token`:

```bash
curl -X POST https://sandbox.plaid.com/item/public_token/exchange \
  -H "Content-Type: application/json" \
  -d '{"client_id": "YOUR_CLIENT_ID", "secret": "YOUR_SANDBOX_SECRET", "public_token": "PUBLIC_TOKEN_FROM_PREVIOUS_STEP"}'
```

If you get back an `access_token` and `item_id`, your credentials are working correctly.

## Security best practices

- Store your `client_id` and `secret` in environment variables or a dedicated secrets manager (AWS Secrets Manager or similar).
- Use separate secrets for Sandbox and Production. Plaid generates different secrets per environment by default, so don't mix them up.
- Add `.env` to your `.gitignore` before your first commit. Not after.
- Never expose your `secret` in client-side code. All Plaid API calls (except Link initialization) should happen server-side.
- Monitor your Plaid Dashboard for unexpected activity, especially after granting team members access.

## Common gotchas

**Mixing up environment URLs and secrets.** Your Sandbox Plaid API key only works against `sandbox.plaid.com`. Your Production secret only works against `production.plaid.com`. If you're getting `INVALID_API_KEYS` errors, check that your environment URL and secret match.

**Confusing Plaid Link with API authentication.** Plaid Link is the client-side UI widget your end users interact with to connect their bank accounts. It produces a `public_token` that you exchange server-side for a permanent `access_token`. The `client_id` and `secret` are your server-to-server credentials, not something you pass to Link directly.

**Forgetting to request Production access.** Sandbox works immediately, but Production requires a separate application through the Dashboard. The approval process includes reviewing your use case, compliance requirements, and may take a few days. Plan for this lead time before your launch date.

**Not handling the access_token lifecycle.** Once you exchange a `public_token` for an `access_token`, that access token remains valid until you explicitly revoke it via `/item/remove`. There's no expiration, but you still need to handle error states (like when a user changes their bank password) through Plaid's webhook system.

**Assuming all institutions support all products.** Not every bank supports every Plaid product. If you request Auth for an institution that only supports Transactions, Link will fail. Check institution coverage before building your product selection logic.

## Building financial integrations beyond banking data

If you're building a fintech application that needs both bank account data and accounting platform connectivity, the two sides of the integration stack are different. Plaid handles the banking layer: account verification and transaction feeds. (For more on how banks and apps connect, see our [bank API integration](https://www.apideck.com/blog/bank-api-integration) guide.) The [accounting layer](https://www.apideck.com/blog/accounting-integration), connecting to platforms like QuickBooks and Xero for invoices and financial reporting, requires a separate integration approach.

Check out our other API key guides for platforms in the accounting and finance space, including [QuickBooks](https://www.apideck.com/blog/how-to-get-your-quickbooks-api-key) and [Xero](https://www.apideck.com/blog/how-to-get-your-xero-api-key).

Get your Plaid API keys and start pulling bank data in under 10 minutes with this step-by-step guide covering dashboard setup, environments, sandbox testing, and common authentication mistakes.

How to Get Your Plaid API Key

FreeAgent is one of the most popular accounting platforms in the United Kingdom. It serves freelancers and small businesses with invoicing, expense tracking, Self Assessment tax returns, payroll, and MTD-compatible VAT filing. NatWest Group acquired the company in 2018, and it remains a common integration target for software that touches UK financial data.

This guide covers what you need to know to integrate with the FreeAgent API, from authentication and available endpoints to rate limits, pagination, and the specific challenges that make this integration more involved than the documentation suggests. If you want to skip the complexity of building a direct integration, [Apideck's FreeAgent connector](https://www.apideck.com/integrations/freeagent) handles authentication, token refresh, and data normalization through a unified Accounting API.

## What FreeAgent covers

FreeAgent targets a specific segment of the UK market: self-employed professionals, freelancers, and small limited companies. The platform handles:

- Invoicing and estimates
- Expense claims and receipt capture
- Bank account connections and reconciliation
- Self Assessment tax return filing
- VAT returns with Making Tax Digital compliance
- Payroll for small teams
- Project and time tracking
- Multi-currency support

The platform's tight focus on UK tax requirements makes it essential for software serving British freelancers and small businesses. If your customers use FreeAgent, they expect their data to flow into your application without manual exports.

## API overview

FreeAgent offers two separate API products, and this distinction matters for how you architect your integration.

The **Company API** is for direct FreeAgent users: freelancers and small businesses managing their own accounting. This is the standard integration path for most applications.

The **Accountancy Practice API** is for accounting firms and bookkeepers who manage multiple client accounts through FreeAgent's Practice Dashboard. This requires a separate app registration, a different OAuth flow, and client-specific subdomains in request headers.

For a SaaS product that serves both direct business users and accounting firms, this means building and maintaining two distinct integration paths.

Both APIs are REST-based and support JSON and XML responses. The base URLs are:

- Production: `https://api.freeagent.com/v2`
- Sandbox: `https://api.sandbox.freeagent.com/v2`

The sandbox environment lets you test your integration without affecting live data. FreeAgent provides temporary sandbox accounts through their developer portal for this purpose.

## Authentication

FreeAgent uses OAuth 2.0 with the authorization code flow. To get started:

1. Create an account at the [FreeAgent Developer Dashboard](https://dev.freeagent.com/)
2. Register a new application to receive your OAuth Client ID and Client Secret
3. Specify which access level your application requires (more on this below)

The authorization endpoint is:

```
https://api.freeagent.com/v2/approve_app
```

The token endpoint is:

```
https://api.freeagent.com/v2/token_endpoint
```

A basic token exchange looks like this:

```bash
curl -X POST https://api.freeagent.com/v2/token_endpoint \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=YOUR_REDIRECT_URI"
```

Access tokens expire after one hour. Refresh tokens are long-lived (approximately 20 years according to the API response), so you can maintain persistent access without requiring users to re-authenticate.

### Access levels

FreeAgent uses a numeric access level system (0 through 8) that controls which resources your app can read or write. When you register your application, you need to specify the access level you require. Each API resource has a minimum required level, and requesting a higher level than necessary will likely slow down your app approval.

Review the documentation to determine the minimum access level that covers your use case. If you only need to read invoices and contacts, you don't need the same permissions as an app that manages payroll.

## Key endpoints

The Company API covers the core accounting resources you'd expect:

- `/v2/contacts` for customers and suppliers
- `/v2/invoices` for sales invoices
- `/v2/bills` for purchase invoices
- `/v2/expenses` for expense claims
- `/v2/bank_accounts` for connected bank accounts
- `/v2/bank_transactions` for bank transaction data
- `/v2/projects` for project management
- `/v2/tasks` for time tracking
- `/v2/users` for user accounts
- `/v2/company` for company settings
- `/v2/categories` for expense categories
- `/v2/tax_rates` for VAT rates
- `/v2/journal_entries` for manual journal entries
- `/v2/payroll_profiles` and `/v2/payslips` for payroll data

The API supports standard CRUD operations on most resources. Each endpoint is documented in the [FreeAgent API documentation](https://dev.freeagent.com/docs).

## Rate limits

FreeAgent enforces the following rate limits:

- 120 requests per minute per user
- 3,600 requests per hour per user
- 15 token refreshes per minute per user

These limits reset at the start of every hour or minute. For Accountancy Practice API users, rate limits apply per client subdomain rather than to the practice as a whole.

When you hit a rate limit, the API returns a 429 response with a `Retry-After` header indicating how long to wait:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 60
```

The 120 requests per minute limit is generous for most use cases. However, the 15 token refreshes per minute limit creates a specific bottleneck for multi-tenant applications. If you're running a SaaS product with many customers and you trigger concurrent token refreshes during a scheduled sync, you can exhaust this limit before pulling any actual data. You'll need to implement token refresh queuing or stagger sync schedules across your customer base.

FreeAgent provides a testing header `X-RateLimit-Test` that artificially lowers the sandbox rate limit to 5 requests per minute, letting you verify your backoff strategy before hitting production limits.

## Pagination

API requests that return multiple items are paginated with a default of 25 items per page and a maximum of 100 items per page.

```
GET https://api.freeagent.com/v2/invoices?page=2&per_page=50
```

Pagination metadata comes in headers rather than the response body:

- The `Link` header contains URLs for `prev`, `next`, `first`, and `last` pages
- The `X-Total-Count` header contains the total number of items

The 25-item default is lower than most accounting APIs. If you're syncing large datasets, you'll want to set `per_page=100` and implement proper pagination handling to avoid missing records.

## Working with contacts

Creating a contact requires minimal data:

```bash
curl -X POST https://api.freeagent.com/v2/contacts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "organisation_name": "Smith Consulting"
    }
  }'
```

A successful creation returns a 201 status with the created contact object, including the FreeAgent URL identifier you'll need for subsequent operations.

## Integration challenges

Beyond the two-API-product architecture and rate limits, several characteristics make FreeAgent integrations more complex than they initially appear.

**No webhooks.** The standard FreeAgent API doesn't support webhooks for real-time notifications. You'll need to poll for changes, which means designing an efficient sync strategy that respects rate limits while keeping data reasonably current. This is a meaningful limitation for applications that need near-real-time data.

**UK-specific data models.** FreeAgent's data structures reflect UK accounting conventions and tax requirements. VAT handling, Self Assessment categories, and MTD-specific fields may not map cleanly to more generic accounting schemas. If you're building a multi-country application, you'll need transformation logic specific to FreeAgent's UK-centric model.

**Documentation in context.** While the API documentation is available through the developer portal, some details only become clear through trial and error. Error messages are generally helpful, but the sandbox environment is essential for understanding how the API actually behaves before you deploy to production.

## Scaling beyond FreeAgent

FreeAgent covers the UK freelancer and small business market well, but most B2B applications need to integrate with multiple accounting platforms. Your UK customers use FreeAgent, your US customers use QuickBooks, your Dutch customers use SnelStart, and your Australian customers use Xero.

Building and maintaining direct integrations to each platform means handling different authentication flows, different data models, different rate limits, and different error handling for every connector. Each integration requires its own development time and ongoing maintenance as APIs change.

A [unified API](https://www.apideck.com/blog/what-is-a-unified-api) gives you one integration point and one data schema across all of them. Instead of managing FreeAgent's token refresh limits, QuickBooks' OAuth flow, and Xero's pagination separately, you write against a single normalized [Accounting API](https://www.apideck.com/accounting-api) and let the platform handle the connector-specific complexity.

With Apideck, listing invoices from FreeAgent looks like this:

```javascript
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: 'freeagent'
})
```

The same code structure works for [QuickBooks](https://www.apideck.com/blog/how-to-integrate-your-app-with-quickbooks-online), [Sage](https://www.apideck.com/blog/how-to-integrate-sage-business-cloud-accounting-api), [Xero](https://www.apideck.com/integrations/xero), and every other accounting connector in the platform.

[Create a free](https://www.apideck.com/signup) Apideck account to get started.

Learn how to integrate with the FreeAgent API using OAuth 2.0. This guide covers authentication, key endpoints, rate limits, pagination, and common integration challenges when building accounting integrations for UK-based businesses.

How to integrate with the FreeAgent API

Get your FreshBooks API credentials in under 10 minutes with this step-by-step guide covering OAuth setup, app registration, scopes, and the identity model quirks that trip developers up.

## What's FreshBooks?

[FreshBooks](https://www.apideck.com/integrations/freshbooks) is cloud-based accounting software built for freelancers and small businesses who want invoicing that doesn't make them hate their lives. It handles invoices, expenses, time tracking, and basic accounting. The interface is clean, the mobile app actually works, and it won't overwhelm you with features you'll never use.

You're here because you need to connect FreshBooks to your application, sync invoice data, or automate billing workflows. Here's how to get API access.

> **Note:** FreshBooks doesn't use traditional API keys. It uses OAuth 2.0 authentication with a Client ID and Client Secret. This guide walks you through creating an application and obtaining those credentials.

## Prerequisites

- FreshBooks account (trial or paid, doesn't matter)
- A redirect URI ready (even `http://localhost` works for testing)
- Basic understanding of OAuth flows, or at least a willingness to learn

## Step 1: Access the Developer Portal

Go to [https://my.freshbooks.com/#/developer](https://my.freshbooks.com/#/developer) and log in with your FreshBooks account.

If you don't see the developer section, make sure you're logged into an account with admin access. FreshBooks doesn't surface developer tools to every user by default.

## Step 2: Create a New Application

Click **Create New App** in the developer portal.

Fill in the required fields:

- **Application Name**: Something descriptive. "My Invoice Integration" beats "Test App 1" when you're staring at it six months from now.
- **Application Type**: Select based on your use case. Most integrations use "Web Application."
- **Redirect URI**: Where FreshBooks sends users after authorization. For testing, use `http://localhost:8000/callback` or similar. For production, this must be HTTPS.

The redirect URI needs to match exactly when you make authorization requests later. Trailing slashes matter. HTTP vs HTTPS matters. Get it right now or debug it forever.

## Step 3: Configure Scopes

Select the scopes your application needs. FreshBooks is granular here, which is good for security but means you need to think about what data you actually require.

Common scopes:

- `user:profile:read` - Required to get identity information
- `user:clients:read` and `user:clients:write` - Customer management
- `user:invoices:read` and `user:invoices:write` - Invoice access
- `user:expenses:read` - Expense tracking
- `user:payments:read` - Payment data

Request only what you need. Over-scoped apps make users nervous at the consent screen, and nervous users don't click "Allow."

## Step 4: Save and Get Your Credentials

Click **Save** to create your application.

Now click on your newly created app. Scroll to the bottom under **App Settings**. You'll see:

- **Client ID**: Your application's public identifier
- **Client Secret**: Your application's private key

Copy both immediately and store them securely. If you lose the Client Secret, you'll need to regenerate it, which invalidates any existing tokens.

## Step 5: Build Your Authorization URL

FreshBooks uses the standard OAuth 2.0 authorization code flow. Your authorization URL looks like this:

```
https://auth.freshbooks.com/oauth/authorize/?response_type=code&redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_CLIENT_ID
```

Replace the placeholders with your actual values. When a user visits this URL, they'll see the FreshBooks login page, then a consent screen showing what your app wants to access.

## Step 6: Exchange the Code for Tokens

After the user authorizes your app, FreshBooks redirects them to your redirect URI with a `code` parameter. Exchange this code for tokens:

```bash
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": "THE_AUTHORIZATION_CODE",
    "redirect_uri": "YOUR_REDIRECT_URI"
  }'
```

You'll get back:

- **access_token**: Use this in API requests. Expires in about 12 hours.
- **refresh_token**: Use this to get new access tokens without re-authorization.

Store both securely. The refresh token is your long-term credential.

## The Identity Model Quirk

Here's where FreshBooks gets weird. Before you can make most API calls, you need to understand the account and business ID structure.

After getting your tokens, call the identity endpoint:

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

This returns your user profile with `business_memberships`. Each membership contains an `account_id` and `business_id`. You'll need these for API calls, as most endpoints use the pattern:

```
https://api.freshbooks.com/accounting/account/{account_id}/...
```

A single FreshBooks user can belong to multiple businesses. Your integration needs to handle this or ask users which business they want to connect.

## Common Mistakes

**Wrong redirect URI**: It must match character-for-character. The error message won't tell you this clearly.

**Expired tokens**: Access tokens last about 12 hours. Implement token refresh or your integration dies every morning.

**Forgetting the account ID**: Every accounting endpoint needs it. Parse the identity response and store it alongside your tokens.

**HTTP redirect URIs in production**: FreshBooks requires HTTPS for production apps. HTTP only works for localhost during development.

**Scope creep**: Requesting every scope "just in case" tanks your authorization rate. Start minimal and add scopes when you actually need them.

## Refreshing Tokens

Access tokens expire. Use the refresh token to get new ones:

```bash
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",
    "redirect_uri": "YOUR_REDIRECT_URI"
  }'
```

You'll get a new access token and a new refresh token. Replace the old refresh token with the new one. The old one is now invalid.

## Testing Your Connection

Make a simple API call to verify everything works:

```bash
curl -X GET 'https://api.freshbooks.com/accounting/account/{account_id}/users/clients' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json'
```

If you get JSON back with client data (or an empty array if you have no clients), you're connected. If you get a 401, check your token. If you get a 403, check your scopes.

## Managing FreshBooks API Connectivity with Apideck's Vault

If you're building integrations with FreshBooks and other accounting platforms, managing OAuth flows for each one gets old fast. Apideck's [Vault](https://www.apideck.com/products/vault) handles the tedious parts:

- **Automatic token refresh**: No more 2 AM alerts because tokens expired.
- **Pre-built authorization UI**: Drop in a component and let users connect their accounts without building consent flows yourself.
- **Unified connection management**: Track connection states across FreshBooks, QuickBooks, Xero, and 25+ other platforms from one dashboard.

In the Apideck dashboard, go to Configuration and select the FreshBooks connector under Accounting. Choose "Use your client credentials" and enter the Client ID and Client Secret from your FreshBooks app. Note the redirect URI at the bottom: `https://unify.apideck.com/vault/callback`. Add this to your FreshBooks app's allowed redirect URIs.

![How to get your FreshBooks API Key 1](//images.ctfassets.net/d6o5ai4eeewt/aWEkgupxjzoLa1W4376Xc/a8c49963053f287a62923cf6bea957f3/552_1x_shots_so.png)

Scroll down to configure scopes. Select the permissions your integration needs. The scopes here must match what you configured in your FreshBooks app.

![How to get your FreshBooks API Key 2](//images.ctfassets.net/d6o5ai4eeewt/6hZvggp5r5RVr7NQM6yEuk/c19932cafec274cd816b95678c7c4229/982_1x_shots_so.png)

Click **Save settings**. Then click **Test Vault** in the top right to see the authorization flow your users will experience. The modal shows the connection status and an Authorize button. After authorization, users select which FreshBooks business to connect.

![How to get your FreshBooks API Key 3](//images.ctfassets.net/d6o5ai4eeewt/7lUXOradRznZsSjiOagM41/9ca3bab7fc23e686d7010dc5a5edc823/412_1x_shots_so.png)

Your users click Authorize, authenticate with FreshBooks, and you get a working connection without writing token management code.

For a deeper look at FreshBooks integration patterns, check out the [FreshBooks integration guide](https://www.apideck.com/blog/how-to-integrate-with-the-freshbooks-api). If you're comparing accounting APIs, the [QuickBooks API key guide](https://www.apideck.com/blog/how-to-get-your-quickbooks-api-key) and [Xero API key guide](https://www.apideck.com/blog/how-to-get-xero-api-key) cover similar ground for those platforms.

[Create a free](https://www.apideck.com/signup) Apideck account to get started.

Learn how to get your FreshBooks API credentials using OAuth 2.0. This step-by-step guide covers app setup, scopes, authorization flow, token exchange, and common pitfalls developers face when integrating with FreshBooks.

How to Get Your FreshBooks API Key

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](https://www.apideck.com/blog/guide-to-sap-4-hana-rest-and-soap-api).

## 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](https://help.sap.com/doc/056f69366b5345a386bb8149f1700c19/10.0/en-US/Service%20Layer%20API%20Reference.html) covering every entity and action, along with a detailed [Service Layer user manual](https://help.sap.com/doc/fc2f5477516c404c8bf9ad1315a17238/10.0/en-US/Working_with_SAP_Business_One_Service_Layer.pdf) 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)](https://help.sap.com/docs/INTEGRATION_FRAMEWORK_FOR_SAP_BUSINESS_ONE) 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](https://blogs.sap.com/2020/05/04/rest-api-for-sap-business-one-using-sap-b1-integration-framework-b1if/), 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:

```python
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](https://www.apideck.com/blog/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](https://www.apideck.com/blog/from-accounts-receivable-to-lending-automation-integration-use-cases-for-vertical-saas) 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](https://infisical.com/blog/what-is-certificate-manager) for external clients. This on-premise reality is one of the main reasons [ERP and accounting integrations](https://www.apideck.com/blog/accounting-erp-integration-banks-use-cases) 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.

A practical guide to integrating with the SAP Business One Service Layer API. Covers session-based authentication, OData v4 endpoints, querying, pagination, User-Defined Fields, error handling, and production deployment tips.

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

Every NetSuite instance is different. That is the first thing any integration team learns, usually the hard way. But the single biggest source of variation across NetSuite accounts has nothing to do with custom fields or SuiteScript extensions. It comes down to one question: is the account running OneWorld or not?

The answer changes the database schema your integration queries and the currency logic it has to handle. If you build a [NetSuite connector](https://www.apideck.com/connectors/netsuite) that only works against Standard accounts, it will break the moment a OneWorld customer connects. If you only test against OneWorld, you will throw fatal errors on Standard instances that lack subsidiary tables entirely.

This post covers what actually differs between the two editions, where the API diverges, and what it means if you are building or buying a NetSuite integration.

## How OneWorld and Standard editions differ at the schema level

NetSuite Standard runs a single legal entity. One set of books, one base currency. The subsidiary record does not exist. There is no subsidiary table to query, no subsidiary field on transactions, and no intercompany elimination logic.

NetSuite OneWorld adds multi-subsidiary support. Each subsidiary is a separate legal entity with its own base currency and tax schedules. The chart of accounts can be shared with the parent or customized per subsidiary. Subsidiaries are arranged in a parent-child hierarchy, and financial data rolls up through that hierarchy into consolidated reports.

Oracle prices OneWorld as a licensing upgrade on top of Standard, typically adding $10,000 to $30,000 per year depending on subsidiary count. Once enabled, the upgrade is permanent and cannot be reversed. Every edition of NetSuite (Light, Mid-Market, Enterprise) can be upgraded to OneWorld.

The practical difference for integration teams: OneWorld accounts have tables and fields that Standard accounts do not. And querying those missing tables on a Standard account does not return empty results. It throws a fatal error.

## How the NetSuite OneWorld subsidiary field affects API queries

On a OneWorld account, nearly every transactional and master data record gains a `subsidiary` field. Invoices, bills, journal entries, customers, vendors, items, and GL accounts all carry subsidiary references. Some records, like `customerSubsidiaryRelationship` and `vendorSubsidiaryRelationship`, only exist on OneWorld accounts. Oracle's own REST API documentation states: "You must either use NetSuite OneWorld or have the Subsidiaries hidden feature enabled before you can use this record through REST web services."

On a Standard account, none of these fields or records exist. A SuiteQL query that JOINs the subsidiary table will fail with a "Record not found" error. A [REST API](https://www.apideck.com/blog/integrating-with-the-netsuite-rest-api) call to the `subsidiary` endpoint returns nothing useful.

This creates a branching problem. For every resource you want to read from NetSuite (accounts, contacts, transactions, invoices, journal entries), you need at least two query variants: one that includes subsidiary JOINs and filters, and one that does not. Add multi-currency into the mix (which is a separate feature that may or may not be enabled, even on OneWorld accounts), and you need to JOIN the currency table conditionally too. For an [accounting integration](https://www.apideck.com/blog/accounting-integration) covering 15 or more resources, the Truto engineering team calculated this produces 60+ query variants that need to be managed at runtime.

## Runtime feature detection for NetSuite OneWorld vs Standard

You cannot ask a NetSuite customer "are you on OneWorld?" and hard-code the answer. Accounts get upgraded. Modules get enabled. The only reliable approach is to probe the account programmatically at connection time.

The detection pattern is straightforward in concept: attempt to query the subsidiary table, and if the query fails, the account is not running OneWorld. Then cache that result and use it to select the right query templates for every subsequent API call.

In practice this means your integration layer needs a query routing engine. Every SuiteQL query template exists in at least two forms (with and without subsidiary JOINs), and the correct form gets selected based on the feature flags detected during the initial connection probe. This is architectural work that has to happen before you write a single line of business logic. For a deeper look at the full scope of [NetSuite integration](https://www.apideck.com/blog/netsuite-integration-guide) complexity, including governance limits and concurrency constraints, see our separate guide.

The same pattern applies to multi-currency. If the account uses multiple currencies, the `currency` table is available and transactions carry currency fields with exchange rate data. If not, querying that table fails. You need to detect and branch for this independently of the OneWorld check, because Standard accounts can enable multi-currency without upgrading to OneWorld.

## Multi-currency handling across NetSuite editions

Standard NetSuite with multi-currency enabled supports transactions in foreign currencies against a single base currency. The system converts and posts to the GL in the base currency using the exchange rate at the transaction date.

OneWorld takes this further. Each subsidiary has its own base currency. A US subsidiary posts in USD, a UK subsidiary in GBP, a Japanese subsidiary in JPY. Transactions record in their original currency and convert to the subsidiary's base currency for GL posting. Consolidated reporting then translates subsidiary financials into the parent's reporting currency using separate consolidated exchange rate tables.

For API consumers, this means the same invoice can have three currency amounts that matter: the transaction currency (what the customer was billed in), the subsidiary base currency (what hits the local GL), and the consolidated currency (what appears on the parent's P&L). Your integration needs to know which one it is reading and which one it needs. The `transactionLine` records in SuiteQL carry fields like `fxamount` (foreign currency amount) and `amount` (base currency amount), and which "base" that refers to depends on the subsidiary context of the transaction.

If you are pulling a trial balance or balance sheet through the API, OneWorld accounts require you to specify a subsidiary context for the report. A consolidated trial balance rolls up child subsidiary data through the hierarchy with currency translation at each level. Getting this wrong does not produce an error. It produces wrong numbers, which is worse.

NetSuite also handles [tracking dimensions](https://www.apideck.com/blog/tracking-dimensions-in-accounting-integrations) (departments, locations, classes) differently across editions. On OneWorld accounts, departments and locations are scoped to specific subsidiaries, which means your integration needs to validate that a given dimension ID is valid for the subsidiary context of the transaction you are creating.

## NetSuite SOAP deprecation and the REST API migration timeline

NetSuite does not have one API. It has at least three: [SuiteTalk SOAP](https://www.apideck.com/blog/guide-to-integrating-with-the-netsuite-soap-api) (being deprecated), SuiteTalk REST, and SuiteQL (accessed through the REST query endpoint). Each has different strengths and gaps.

SuiteQL is the most capable for read-heavy workloads. It supports JOINs, aggregations, and server-side filtering through SQL-like syntax. The REST Record API is better for individual CRUD operations. And for some operations (generating transaction PDFs, accessing dynamic form metadata), you still need custom SuiteScript RESTlets deployed into the customer's account.

Oracle is actively winding down SOAP. The 2025.2 release is the last planned SOAP endpoint. Starting with 2026.1, no new SOAP endpoints ship by default. By 2028.2, SOAP will be fully removed. Any integration still running on SOAP at that point will stop working. If you have not started your migration, our [NetSuite API key guide](https://www.apideck.com/blog/how-to-get-your-netsuite-api-key) covers the authentication setup for both REST and OAuth 2.0.

The SOAP deprecation interacts with the OneWorld complexity in a specific way: many older integrations handled subsidiary context through SOAP's search and record operations, where the subsidiary field was just another XML element to include or exclude. Migrating those integrations to REST and SuiteQL means rebuilding the query logic from scratch, and the OneWorld branching has to be redesigned at the same time. You cannot simply swap XML payloads for JSON payloads and call it done.

REST also has known gaps. The subsidiary record itself is read-only through REST (GET only, no POST/PATCH/DELETE). Legacy tax engine features are not exposed through REST at all, which matters because each OneWorld subsidiary can have different tax configurations. SuiteTax is the path forward, but not every NetSuite customer has migrated to it.

## What this means for unified API platforms and ERP integrations

If you are a SaaS company building a [NetSuite integration](https://www.apideck.com/integrations/netsuite) in-house, you need to handle all of this yourself. That means runtime feature detection and conditional query routing, plus currency normalization and subsidiary-aware data scoping on top. Add ongoing maintenance as Oracle evolves the API surface, and the effort compounds quickly. This is one of the reasons [ERP API integration](https://www.apideck.com/blog/erp-api-integration) is consistently cited as the most engineering-intensive category of SaaS connectivity.

If you are using a unified API platform like Apideck, the platform should be handling these differences for you. The value proposition is that you call a single `GET /accounting/invoices` endpoint and get a normalized response regardless of whether the underlying NetSuite account is Standard or OneWorld, single-currency or multi-currency, using SuiteTax or the legacy tax engine.

The quality of a unified API's NetSuite connector comes down to how well it handles this matrix. A connector that only works against Standard accounts, or only against OneWorld accounts, is not production-ready. The feature detection, query branching, and currency normalization have to work across the full range of NetSuite configurations that exist in the wild.

For Apideck specifically, our [NetSuite Accounting API connector](https://www.apideck.com/integrations/netsuite) handles OneWorld and Standard accounts through automated feature detection at connection time. The SuiteQL queries adapt based on the detected configuration, and the response schema stays consistent regardless of the underlying edition. Subsidiary data surfaces as a standard field when present and is omitted cleanly when it is not.

## Practical checklist for NetSuite API integration teams

If you are building or maintaining a NetSuite integration, here is what the OneWorld vs Standard split requires:

Detect OneWorld and multi-currency status at connection time by probing for table availability. Cache those flags and use them for query routing throughout the integration lifecycle.

Maintain parallel SuiteQL query templates for every resource: one with subsidiary JOINs and one without. Do the same for currency JOINs where relevant.

Scope data reads by subsidiary when working with OneWorld accounts. Pulling all data across all subsidiaries without filtering will return a superset that may not match what the customer expects for a given legal entity.

Handle currency fields explicitly. Know the difference between transaction currency, subsidiary base currency, and consolidated reporting currency. Map each to the correct field in your normalized schema.

Test against both editions. If your test environment only has OneWorld enabled, you are missing half the failure modes. Spin up a Standard test account and run your full test suite against it.

Plan for the SOAP sunset. If any part of your NetSuite integration still uses SOAP, the 2028.2 removal deadline is fixed. Build new integrations on REST and SuiteQL with OAuth 2.0 authentication.

Track REST API gaps. Some OneWorld-specific features (subsidiary record writes, legacy tax fields) are not available through REST. Know where you need SuiteScript RESTlets to fill the gaps, and plan for Oracle to close those gaps over time as REST reaches parity.

NetSuite is one of the [most widely deployed ERPs](https://www.apideck.com/blog/legacy-and-established-erp-platforms) in the world, and the OneWorld vs Standard split is one of its most consequential integration variables. Getting this right is the difference between an integration that works for your first three customers and one that works for your next three hundred.

## Frequently asked questions

**How do I detect whether a NetSuite account is running OneWorld or Standard via the API?**

Probe the subsidiary table at connection time using a SuiteQL query like `SELECT id FROM subsidiary LIMIT 1`. If the query returns results, the account is running OneWorld. If it throws a "Record not found" error, the account is Standard. Cache this result and use it to select the correct query templates for all subsequent API calls.

**Does the NetSuite REST API behave differently on OneWorld vs Standard accounts?**

Yes. On OneWorld accounts, records like invoices, customers, and vendors carry a `subsidiary` field, and records like `customerSubsidiaryRelationship` become available. On Standard accounts, these fields and records do not exist. The subsidiary REST record itself is read-only (GET only). Your integration needs conditional logic to include or exclude subsidiary-related fields depending on the edition.

**Can a Standard NetSuite account use multi-currency without upgrading to OneWorld?**

Yes. Multi-currency is a separate feature that can be enabled on Standard accounts. When enabled, transactions can be created in foreign currencies and converted to the single base currency at the exchange rate on the transaction date. OneWorld adds the ability for each subsidiary to have its own base currency, which introduces additional currency translation layers for consolidated reporting.

**What happens to my NetSuite SOAP integration when Oracle removes SOAP in 2028?**

The 2025.2 SOAP endpoint is the last planned release. Starting with 2026.1, no new SOAP endpoints ship. By 2028.2, all SOAP endpoints will be removed and existing SOAP integrations will stop working. Oracle recommends migrating to REST web services with OAuth 2.0 authentication. For OneWorld accounts, this migration also requires rebuilding subsidiary-aware query logic in SuiteQL.

NetSuite OneWorld adds subsidiary tables, multi-currency fields, and schema differences that break integrations built for Standard. Here is what API and integration teams need to handle.

NetSuite OneWorld vs Standard: What Changes When You Hit the API

Zoho Books is a cloud-based accounting platform popular with small and mid-sized businesses, particularly those already embedded in the Zoho ecosystem. If your product serves finance teams, you'll eventually get a request to pull invoice data from Zoho Books or push expense records into it.

This guide covers the technical work involved: authentication, key endpoints, rate limits, data mapping, and the common pitfalls that trip up first-time integrators. If you want to skip the direct integration work, [Apideck's Zoho Books connector](https://www.apideck.com/integrations/zoho-books) handles the plumbing through a unified accounting API.

## What the Zoho Books API offers

The Zoho Books API is a REST API that returns JSON responses. Version 3 is the current release and covers the full range of accounting operations: contacts, invoices, expenses, bills, bank transactions, purchase orders, and sales orders.

Every API request requires two things: an OAuth 2.0 access token and an `organization_id` parameter. Zoho Books supports multiple organizations under a single account, and the API enforces strict separation between them. You'll need to retrieve the organization ID first (via GET /organizations) before calling any other endpoint.

Base URL: `https://www.zohoapis.com/books/v3/`

One complication: Zoho operates regional data centers with distinct API domains: .com, .eu, .in, .com.au, .jp, .ca, .sa (Saudi Arabia), and .uk. The API domain must match where the user's Zoho Books account is hosted. A customer on zoho.eu needs API calls to zohoapis.eu. Getting this wrong produces authentication errors that look like token problems.

The modern approach is to detect the data center automatically during OAuth. When you make the initial authorization request to `accounts.zoho.com`, the response includes a `location` parameter indicating the user's data center. You can also call `https://accounts.zoho.com/oauth/serverinfo` to get the full mapping of location codes to API domains. This beats asking users to identify their region manually.

![Zoho Books API](//images.ctfassets.net/d6o5ai4eeewt/5yZjOq7s9H3nOgLArolHYU/4ca140d75561c032c1afa5c437d295a2/Screenshot_2026-03-25_at_06.49.31.png)

## Authentication setup

Zoho uses OAuth 2.0 with the authorization code grant type. The flow works like most OAuth implementations, with a few Zoho-specific details.

**Register your application**

Go to the Zoho Developer Console and create a new client. You'll choose between two client types:

- **Web-based**: Standard OAuth flow with redirect URIs. Use this for applications where users authenticate through a browser.
- **Self-client**: Server-to-server authentication. Generates tokens without user interaction after the initial setup. Useful for backend services and scheduled syncs.

Registration gives you a client ID and client secret.

**Implement the authorization flow**

For web-based clients, redirect users to Zoho's authorization endpoint:

```
GET https://accounts.zoho.com/oauth/v2/auth
  ?response_type=code
  &client_id={your_client_id}
  &scope=ZohoBooks.invoices.READ,ZohoBooks.contacts.READ
  &redirect_uri={your_redirect_uri}
  &access_type=offline
```

The `access_type=offline` parameter is important. Without it, you won't receive a refresh token, and your integration will break after an hour when the access token expires.

After the user authorizes, Zoho redirects to your URI with an authorization code. Exchange it for tokens within two minutes:

```
POST https://accounts.zoho.com/oauth/v2/token
  ?code={authorization_code}
  &client_id={your_client_id}
  &client_secret={your_client_secret}
  &redirect_uri={your_redirect_uri}
  &grant_type=authorization_code
```

**Manage token lifecycle**

Access tokens expire after one hour. Refresh tokens don't expire unless revoked, and you can reuse the same refresh token to generate new access tokens repeatedly. Store the refresh token securely and use it to generate new access tokens before they expire:

```
POST https://accounts.zoho.com/oauth/v2/token
  ?refresh_token={refresh_token}
  &client_id={your_client_id}
  &client_secret={your_client_secret}
  &grant_type=refresh_token
```

Zoho's scopes are granular. Instead of broad permissions like "accounting:read", you request specific capabilities: `ZohoBooks.invoices.CREATE`, `ZohoBooks.contacts.READ`, `ZohoBooks.expenses.UPDATE`. Request only what you need. The full scope list covers contacts, settings, estimates, invoices, customer payments, credit notes, projects, expenses, sales orders, purchase orders, bills, debit notes, vendor payments, banking, and accountant operations.

## Key endpoints

| Category | Endpoint | Common operations |
|----------|----------|-------------------|
| Contacts | `/contacts` | Create and manage customers and vendors |
| Invoices | `/invoices` | Create, send, and track invoices |
| Expenses | `/expenses` | Record and categorize expenses |
| Bills | `/bills` | Manage accounts payable |
| Banking | `/bankaccounts`, `/banktransactions` | Bank feeds and reconciliation |
| Recurring | `/recurringinvoices`, `/recurringexpenses` | Subscription billing and repeat expenses |
| Orders | `/salesorder`, `/purchaseorder` | Sales and purchase order management |

A few endpoints worth noting:

`POST /invoices/fromsalesorder` creates an invoice directly from a sales order, which saves a round trip if you're building order-to-cash workflows.

`POST /invoices/email` and `POST /invoices/paymentreminder` handle customer communication without leaving the API.

`GET /organizations` returns all organizations the authenticated user can access, along with currency settings, fiscal year configuration, and time zone. Call this first to get the organization_id you'll need for everything else.

## Data mapping considerations

Zoho Books uses its own data model, which won't map 1:1 to other accounting systems. If you're building a [multi-platform integration](https://www.apideck.com/blog/top-15-accounting-apis-to-integrate-with), here are the fields that cause the most trouble.

**Contacts**

Zoho combines customers and vendors into a single contacts endpoint, distinguished by `contact_type`. The `contact_name` field has a 200-character limit. Company information goes in `company_name`, not the contact name. Billing and shipping addresses are nested objects with their own field structure.

**Invoices**

Tax handling is line-item based. Each line item can have its own tax rate, and the tax configuration at the header level must match the line items. Mismatches produce validation errors that aren't always obvious from the error message.

Line items use `item_id` for products from your Zoho inventory or can be created as custom items with `name`, `description`, `rate`, and `quantity`.

**Custom fields**

Most resources support custom fields through a `custom_fields` array. Each custom field requires a `customfield_id` (retrieved from the organization settings API) and a `value`. Custom field IDs are organization-specific, so don't hardcode them.

## Rate limits

Zoho Books has some of the most restrictive rate limits among major accounting APIs. Plan your integration accordingly.

**Per-minute limit**: 100 requests per minute per organization. Exceeding this returns HTTP 429 with error code 44.

**Daily limits** vary by plan:
- Free: 1,000 calls/day
- Standard: 2,000 calls/day
- Professional: 5,000 calls/day
- Premium/Elite/Ultimate: 10,000 calls/day

Exceeding daily limits returns HTTP 429 with error code 45.

**Concurrent limit**: Roughly 10 simultaneous requests per organization. HTTP 429 with error code 1070 indicates you've hit this ceiling.

The daily limit is shared across all API consumers for that organization. If your customer uses other Zoho integrations or third-party tools that call the API, those count against the same quota. This creates situations where your integration fails because something else exhausted the limit.

Build in exponential backoff for 429 responses. For bulk operations, consider batching and spreading requests across longer time windows.

## Error handling

Zoho Books returns HTTP status codes with JSON error bodies:

```json
{
  "code": 44,
  "message": "For security reasons your account has been blocked as you have exceeded the maximum number of requests per minute."
}
```

Common error codes:
- `0`: Success
- `44`: Per-minute rate limit exceeded
- `45`: Daily rate limit exceeded
- `1070`: Concurrent request limit exceeded
- `1000`-`1099`: Various validation and business logic errors

Log the full error response, not just the HTTP status. The `code` field often contains more actionable information than the status code alone.

## Testing your integration

Zoho Books doesn't offer a dedicated sandbox environment. You have two options:

1. **Create a test organization**: Set up a separate Zoho Books organization for development. This uses real API calls against real infrastructure but keeps test data isolated from production.

2. **Use a trial account**: Zoho offers free trials that provide API access. Useful for testing, but trial limitations may not reflect production behavior.

Test these scenarios specifically:
- Token refresh: Let an access token expire and verify your refresh logic works
- Rate limit handling: Intentionally exceed limits and confirm your backoff implementation
- Multi-organization: If your users might have multiple Zoho Books organizations, test the organization selection flow
- Regional domains: Test with accounts on different Zoho data centers if your customer base is international

## Webhooks and real-time sync

Zoho Books supports outgoing webhooks for real-time notifications. You can configure webhooks in Zoho Books to fire when events occur (invoices created, payments received, contacts updated, etc.), sending HTTP POST requests to your endpoint with the event payload. This eliminates the need for constant polling.

To set up webhooks, navigate to Settings > Automation > Webhooks in the Zoho Books UI and define the trigger events and destination URL. You can also receive incoming webhooks from external systems to create or update records in Zoho Books.

For scenarios where webhooks aren't practical, you can poll endpoints periodically using the `last_modified_time` field on most resources to filter for recent updates. But webhooks are the cleaner approach for near-real-time sync requirements.

## Connecting through a unified API

Building a direct Zoho Books integration makes sense if Zoho is your only target. But most B2B applications need to support multiple accounting platforms. Your QuickBooks customers expect the same sync features as your Zoho customers, and your Xero customers will ask for parity next quarter.

Direct integrations mean duplicating the authentication, data mapping, error handling, and maintenance work for each platform. A [unified accounting API](https://www.apideck.com/blog/what-is-a-unified-api) abstracts those differences behind a single interface.

[Apideck's accounting API](https://www.apideck.com/integrations/zoho-books) normalizes Zoho Books alongside QuickBooks, Xero, Sage, NetSuite, and 20+ other platforms. One integration gives your customers their choice of accounting software. Authentication, webhooks, and rate limit management are handled at the platform level.

This approach trades some Zoho-specific customization for dramatically reduced integration scope. If you're building [invoice automation](https://www.apideck.com/blog/how-to-integrate-your-app-with-quickbooks-online) or expense sync features, the normalized data model covers the common operations without requiring platform-specific code paths.

## Getting started

If you're building direct to Zoho Books:
1. Register at the Zoho Developer Console
2. Implement OAuth with offline access
3. Detect data centers automatically via the `location` parameter in OAuth responses
4. Store organization IDs and regional domains per customer
5. Build rate limit handling from day one

If you want to support multiple accounting platforms:
1. [Sign up](https://www.apideck.com/signup) for an Apideck account
2. Enable the Zoho Books connector
3. Use the unified accounting API for contacts, invoices, and expenses

---

## FAQ

**Does Zoho Books have a sandbox environment?**

No. Test against a separate organization or trial account to avoid polluting production data.

**How do I handle customers on different Zoho data centers?**

Detect the data center automatically during OAuth. The authorization response includes a `location` parameter (e.g., `us`, `eu`, `in`). Use `https://accounts.zoho.com/oauth/serverinfo` to map location codes to the correct API domains. Store the data center domain alongside the OAuth tokens for each customer.

**Why am I getting "invalid_code" when exchanging the authorization code?**

Authorization codes expire after two minutes and can only be used once. If your token exchange is slow or you retry a failed request with the same code, you'll hit this error.

**Can I increase the API rate limits?**

The limits are tied to the Zoho Books subscription plan. Your customer would need to upgrade to a higher tier for increased limits. There's no separate API-specific upgrade path.

**Does Zoho Books support webhooks?**

Yes. Zoho Books supports outgoing webhooks that notify your application when events occur. Configure them through Settings > Automation > Webhooks in the Zoho Books interface. You can trigger webhooks on invoice creation, payment receipt, contact updates, and other events.

A complete guide to integrating with the Zoho Books API covering authentication, key endpoints, rate limits, data mapping, and common pitfalls. Learn how to build a reliable integration or simplify the process using a unified API.

How to Integrate with the Zoho Books API

The rules around accrual and cash-based accounting vary by country, entity type, and business size. The US allows cash up to $31M in gross receipts. The UK now defaults to cash for sole traders. Germany requires accrual for most businesses. This post covers the regulatory differences across markets and what it means when you are building accounting integrations through APIs.

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

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](https://www.apideck.com/integrations/myob) 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](https://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:

```json
{
  "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](https://www.apideck.com/blog/accounting-integration).

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](https://developer.myob.com), 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](https://www.apideck.com/signup) to connect MYOB and other accounting platforms through a single unified API.

For more on building accounting integrations, see:

- [Top 15 Accounting APIs to Integrate with in 2026](https://www.apideck.com/blog/top-15-accounting-apis-to-integrate-with)
- [The Complete Guide to Accounting API Integrations for Fintech](https://www.apideck.com/blog/the-complete-guide-to-accounting-api-integrations-for-fintech)
- [How to Integrate Sage Business Cloud Accounting API](https://www.apideck.com/blog/how-to-integrate-sage-business-cloud-accounting-api)

Learn how to integrate with the MYOB API, including OAuth setup, March 2025 auth changes, company file GUIDs, rate limits, endpoints, and AccountRight Classic deprecation.

How to Integrate with the MYOB API

When integrating with ecommerce platforms through Apideck, different connectors have varying partnership requirements. Understanding these requirements is essential for planning your integration timeline and ensuring compliance with each platform's developer policies.

This guide categorizes our ecommerce connectors into three groups based on their partnership requirements, helping you understand what's needed before going live with each integration.

## Partnership Categories

### 🔴 Partnership Required

These platforms require the customer to register as a developer or partner with the third-party service and obtain their own API credentials before going live. This typically involves completing a developer profile, agreeing to terms of service, and potentially passing a security or data protection review. Examples include Amazon Seller Central, Walmart, and TikTok Shop.

### 🔵 Partnership Optional (Apideck Credentials Available)

For these connectors, Apideck has already established credentials that you can use, so you can start integrating immediately without registering your own app with the third-party service. When your users authenticate, Apideck will be shown as the application requesting access. You may optionally register your own app if you prefer your own branding during the OAuth consent flow.

### 🟢 No Partnership Required

These connectors allow immediate integration without requiring any formal partnership. Connection is typically established directly through API keys generated in the platform's admin panel. Examples include Shopify, BigCommerce, WooCommerce, and Wix.

## Connector Partnership Matrix

The table below provides a complete overview of partnership requirements, availability of partner introductions, associated fees, and links to documentation for each connector.

## 🔴 Partnership Required

| Connector | Partner Signup | Partner Intro | Partner Fee |
|-----------|---------------|---------------|-------------|
| **Amazon Seller Central** | [sell.amazon.com/developers](https://sell.amazon.com/developers) | Self-Serve | None. Requires Professional Seller account ($39.99/month) and SP-API developer registration with security review. |
| **Walmart** | [Walmart Partner Application](https://gecrm.my.site.com/channelpartnerprospectform/) | Available | None. Requires developer application and approval through Walmart's Solution Provider program. |
| **Lightspeed E-series** | [lightspeedhq.com/partners/developers](https://www.lightspeedhq.com/partners/developers/) | Self-Serve | None. Contact Lightspeed developer team for API access and app registration. |
| **TikTok Shop** | [partner.tiktokshop.com](https://partner.tiktokshop.com/) | Available | None. Requires TikTok Shop Partner Center registration and an activated TikTok Shop account. |
| **Shopify (Public App)** | [shopify.com/partners](https://www.shopify.com/partners) | Self-Serve | N/A. Free partner program; create a public app for the OAuth flow. |

## 🔵 Partnership Optional - Apideck Credentials Available

| Connector | Partner Signup | Partner Intro | Partner Fee |
|-----------|---------------|---------------|-------------|
| **Mollie** | [mollie.com/partners](https://www.mollie.com/partners) (optional) | Available | None with Apideck credentials |

**⚠️ Important:** When using Apideck's partner credentials (blue category), the OAuth consent screen will display "Apideck" as the application requesting access to your users' data. If white-labeling or custom branding is important for your use case, you should register for your own app with the connector.

## 🟢 No Partnership Required

| Connector | Partner Signup | Partner Intro | Partner Fee |
|-----------|---------------|---------------|-------------|
| **Shopify** | [shopify.com/partners](https://www.shopify.com/partners) (optional) | Self-Serve | N/A. Free partner program available for app development. |
| **BigCommerce** | [partners.bigcommerce.com](https://partners.bigcommerce.com/English/register_tech.aspx) (optional) | Self-Serve | N/A |
| **WooCommerce** | [woocommerce.com/partners](https://woocommerce.com/partners/) (optional) | Self-Serve | N/A. Open-source, API keys generated in WooCommerce admin. |
| **Adobe Commerce (Magento)** | [marketplace.magento.com](https://marketplace.magento.com/) (optional) | Self-Serve | N/A |
| **eBay** | [developer.ebay.com](https://developer.ebay.com/signin?tab=register) (optional) | Self-Serve | N/A. Free developer account for API access. |
| **Wix** | [dev.wix.com](https://dev.wix.com/) (optional) | Self-Serve | N/A |
| **PrestaShop** | [addons.prestashop.com](https://addons.prestashop.com/en/) (optional) | Self-Serve | N/A. Open-source, API access via admin panel. |
| **Shopware 6** | [shopware.com/partner](https://www.shopware.com/en/partner/become-partner/technology-partner/) (optional) | Self-Serve | N/A |
| **Bol.com** | [developers.bol.com](https://developers.bol.com/en/ecosystem/integrators) (optional) | Self-Serve | N/A |
| **Picqer** | N/A | Self-Serve | N/A. API keys generated in Picqer admin panel. |
| **Etsy** | [etsy.com/developers](https://www.etsy.com/developers) (optional) | Self-Serve | N/A. Free developer account for API access. |

*\* Green connectors require no customer-side setup in the Apideck dashboard. End-users authenticate directly with credentials from their own account on the platform.*

## Getting Started

### For Connectors Requiring Partnership (Red)

1. Review the partner signup link in the matrix above for your target connector.
2. Register as a developer or complete the partner application process with the ecommerce provider.
3. Obtain your API credentials (Client ID, Client Secret, API keys, etc.).
4. Configure your credentials in the Apideck dashboard under Connector Settings.
5. Follow the Connector Config Guide to complete your setup.

### For Connectors with Apideck Credentials (Blue)

1. Enable the connector in your Apideck dashboard — no additional setup required.
2. Your users will see "Apideck" during the OAuth flow when connecting their accounts.
3. (Optional) Register your own app for custom branding on the consent screen.

### For Connectors with No Partnership Required (Green)

1. Enable the connector in your Apideck dashboard.
2. Your end-users authenticate using their own credentials (API key, username/password, or OAuth consent) from the platform.
3. No customer-side configuration or partner registration is needed.

## Partner Introduction Program

For connectors where partner introductions are available, Apideck can facilitate an introduction to the platform's partnership team. This can help expedite your application process and ensure you're connected with the right contacts. Reach out to your Apideck account manager or contact partners@apideck.com to request an introduction.

## Need Help?

If you have questions about partnership requirements or need assistance with connector configuration, our team is here to help:

**Documentation:** [https://developers.apideck.com/](https://developers.apideck.com/)

**Support:** support@apideck.com

**Partnerships:** partners@apideck.com

Learn which ecommerce integrations require partnerships (Amazon, Walmart) vs. ready-to-use connectors. Complete guide to Apideck's ecommerce API partnership requirements, fees, and setup steps.

Ecommerce Partnership Guide

When integrating with CRM platforms through Apideck, different connectors have varying partnership requirements. Understanding these requirements is essential for planning your integration timeline and ensuring compliance with each platform's developer policies.

This guide categorizes our CRM connectors into three groups based on their partnership requirements, helping you understand what's needed before going live with each integration.

## Partnership Categories

### 🔴 Partnership Required

These platforms require the customer to register an OAuth app or developer account with the third-party service and enter the resulting credentials (Client ID, Client Secret, etc.) in the Apideck dashboard. Examples include Pipedrive, Zendesk Sell, and Blackbaud.

### 🔵 Partnership Optional (Apideck Credentials Available)

For these connectors, Apideck has already established OAuth credentials that you can use. This means you can start integrating immediately without registering your own app with the third-party service. However, when your users authenticate, Apideck will be shown as the application requesting access. You may optionally register your own app if you prefer your own branding during the OAuth consent flow. Examples include Salesforce, HubSpot, and Zoho CRM.

### 🟢 No Partnership Required

These connectors use API key, basic auth, custom authentication, or consumer-provided OAuth credentials, meaning there is no OAuth app registration needed on the customer side. Your end-users authenticate directly with their own credentials. Examples include Close, ActiveCampaign, and Freshsales.

## Connector Partnership Matrix

The table below provides a complete overview of partnership requirements, availability of partner introductions, associated fees, and links to documentation for each connector.

## 🔴 Partnership Required

| Connector | Partner Signup | Partner Intro | Partner Fee |
|-----------|---------------|---------------|-------------|
| **Pipedrive** | [pipedrive.readme.io](https://pipedrive.readme.io/docs/marketplace-registering-the-app) | Self-Serve | None. Register OAuth app in Pipedrive developer portal. |
| **Blackbaud** | [developer.blackbaud.com](https://developer.blackbaud.com/skyapi/docs/getting-started) | Self-Serve | Free developer tier (1,000 API calls/day). ISV partner tier includes higher quotas and [API connection fees](https://developer.blackbaud.com/skyapi/partners/revenue-rates). |
| **Zendesk Sell** | [developer.zendesk.com](https://developer.zendesk.com/api-reference/sales-crm/authentication/introduction/) | Self-Serve | None. Register OAuth app in Zendesk Sell settings (admin access required). |

## 🔵 Partnership Optional - Apideck Credentials Available

| Connector | Partner Signup | Partner Intro | Partner Fee |
|-----------|---------------|---------------|-------------|
| **Salesforce** | [salesforce.com](https://tbid.digital.salesforce.com/) (optional) | Self-Serve | None with Apideck credentials. [ISV program fees](https://www.salesforce.com/partners/become-an-isv-partner/) for own credentials. |
| **HubSpot** | [hubspot.com/partners/app](https://www.hubspot.com/partners/app) (optional) | Self-Serve | None with Apideck credentials |
| **Microsoft Dynamics CRM** | [developer.microsoft.com](https://developer.microsoft.com) (optional) | Self-Serve | None with Apideck credentials |
| **Zoho CRM** | [zoho.com](https://www.zoho.com/crm/developer/) (optional) | Self-Serve | None with Apideck credentials |
| **Attio** | [attio.com/partners](https://attio.com/partners) (optional) | Self-Serve | None with Apideck credentials |
| **Google Contacts** | [console.cloud.google.com](https://console.cloud.google.com/) (optional) | Self-Serve | None with Apideck credentials |
| **Slack** | [api.slack.com](https://api.slack.com/apps) (optional) | Self-Serve | None with Apideck credentials |
| **Teamleader** | Contact Apideck (optional) | Available | None with Apideck credentials |

**⚠️ Important:** When using Apideck's partner credentials (blue category), the OAuth consent screen will display "Apideck" as the application requesting access to your users' data. If white-labeling or custom branding is important for your use case, you should register for your own OAuth app with the connector.

## 🟢 No Partnership Required

| Connector | Partner Signup | Partner Intro | Partner Fee |
|-----------|---------------|---------------|-------------|
| **Odoo CRM** | N/A | Self-Serve | N/A |
| **Planhat** | [planhat.com/partners](https://www.planhat.com/partners) (optional) | Available | N/A |
| **Microsoft Outlook** | N/A | Self-Serve | N/A |
| **Close** | [close.com/partners](https://www.close.com/partners) (optional) | Self-Serve | N/A |
| **ActiveCampaign** | [activecampaign.com/partner](https://www.activecampaign.com/partner/tech) (optional) | Self-Serve | N/A |
| **Salesflare** | N/A | Self-Serve | N/A |
| **Act! CRM** | N/A | Self-Serve | N/A |
| **Flexmail** | N/A | Self-Serve | N/A |
| **Folk** | [developer.folk.app](https://developer.folk.app/) (optional) | Available | N/A |
| **Freshsales** | [freshworks.com/partners](https://www.freshworks.com/partners/) (optional) | Self-Serve | N/A |
| **Copper** | [copper.com/partners](https://www.copper.com/partners) (optional) | Self-Serve | N/A |

*\* Green connectors require no customer-side setup in the Apideck dashboard. End-users authenticate directly with credentials from their own account on the platform.*

## Getting Started

### For Connectors Requiring Partnership (Red)

1. Review the partner signup link in the matrix above for your target connector.
2. Register an OAuth app or complete the partner registration process with the CRM provider.
3. Obtain your API credentials (Client ID, Client Secret, etc.).
4. Configure your credentials in the Apideck dashboard under Connector Settings.
5. Follow the Connector Config Guide to complete your setup.

### For Connectors with Apideck Credentials (Blue)

1. Enable the connector in your Apideck dashboard: no additional setup required.
2. Your users will see "Apideck" during the OAuth flow when connecting their accounts.
3. (Optional) Register your own OAuth app for custom branding on the consent screen.

### For Connectors with No Partnership Required (Green)

1. Enable the connector in your Apideck dashboard.
2. Your end-users authenticate using their own credentials (API key, username/password, or service user token) from the platform.
3. No customer-side configuration or partner registration is needed.

## Partner Introduction Program

For connectors where partner introductions are available, Apideck can facilitate an introduction to the platform's partnership team. This can help expedite your application process and ensure you're connected with the right contacts. Reach out to your Apideck account manager or contact partners@apideck.com to request an introduction.

## Need Help?

If you have questions about partnership requirements or need assistance with connector configuration, our team is here to help:

**Documentation:** [https://developers.apideck.com/](https://developers.apideck.com/)

**Support:** support@apideck.com

**Partnerships:** partners@apideck.com

Learn which CRM integrations require partnerships vs. ready-to-use connectors (Salesforce, Hubspot, Zoho). Complete guide to Apideck's 20+ CRM API partnership requirements, fees, and setup steps.

CRM Partnership Guide

Most [accounting integrations](https://www.apideck.com/blog/accounting-integration) 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](https://www.apideck.com/integrations/netsuite) OneWorld customer running twelve legal entities.

This is the part of [accounting software integration](https://www.apideck.com/blog/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](https://www.apideck.com/blog/tracking-dimensions-in-accounting-integrations)" 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](https://softledger.com/). NetSuite OneWorld carries a [$10,000 to $30,000 annual premium](https://www.brokenrubik.com/blog/netsuite-oneworld-guide) 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](https://www.apideck.com/integrations/netsuite) OneWorld treats each legal entity as a [subsidiary record in a hierarchical tree](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N268563.html). 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](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N1475891.html). 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](https://www.apideck.com/integrations/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](https://www.houseblend.io/articles/netsuite-quickbooks-erp-evaluation) after an acquisition, and switched to NetSuite OneWorld to consolidate finances across entities. This is a common migration pattern.

[Xero](https://www.apideck.com/integrations/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](https://www.apideck.com/integrations/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:

```json
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:

```json
// 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](https://www.apideck.com/blog/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](https://www.apideck.com/blog/accounting-software-integration) 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](https://www.apideck.com/blog/what-is-open-accounting) 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](https://www.apideck.com/accounting-api):

```javascript
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](https://www.apideck.com/accounting-api).

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](https://www.apideck.com/blog/tracking-dimensions-in-accounting-integrations) 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](https://www.apideck.com/blog/accounting-erp-integration-banks-use-cases) or working capital need reliable consolidated financial data to underwrite risk accurately.

At the same time, [accounting platforms](https://www.apideck.com/blog/top-15-accounting-apis-to-integrate-with) 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](https://www.apideck.com/accounting-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.

Multi-entity accounting changes everything about GL integrations. Learn how NetSuite, QuickBooks, Xero, and Sage Intacct model subsidiaries differently, and how a unified accounting API normalizes the complexity.

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

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](https://developer.xero.com/documentation/api/finance/financialstatements) 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](https://developer.intuit.com/app/developer/qbo/docs/workflows/run-reports) 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](https://developer.xero.com/documentation/api/accounting/reports) 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](https://www.apideck.com/use-cases/business-lending-loan-underwriting). 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](https://causal.app), 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](https://www.apideck.com/blog/accounting-integration) 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](https://www.apideck.com/blog/the-complete-guide-to-accounting-api-integrations-for-fintech), 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](https://www.apideck.com/blog/build-an-integration-with-quickbooks-desktop-in-2025), 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](https://www.apideck.com/accounting-api), which covers the two most requested financial statement types natively. Balance Sheet and Profit and Loss endpoints work across [45+ accounting connectors](https://developers.apideck.com/apis/accounting), 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:

```javascript
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](https://www.apideck.com/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.

Most accounting APIs don't expose financial statements as clean endpoints. Learn which statement types are available across QuickBooks, Xero, NetSuite, and Sage, and how a unified API fills the gaps.

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

Learn how to integrate with the FreshBooks API, including OAuth 2.0 authentication, account and business IDs, key endpoints, pagination, webhooks, and common integration pitfalls.

How to Integrate with the FreshBooks API

Stripe processed $1.9 trillion in total payment volume in 2025. More than 300,000 businesses use Stripe Billing alone, managing close to 200 million active subscriptions. When your platform needs to connect to where money actually flows, Stripe is usually the first integration your customers request.

But Stripe's API surface is large. Over 500 endpoints across two namespaces (v1 and v2), covering one-time card charges, multi-party marketplace payouts, subscription billing, fraud detection, card issuing, treasury services, and tax compliance. Picking the right API for your use case saves you weeks. This guide covers each major surface, when to reach for it, and how the pieces connect.

## The Core Payments API

Most Stripe integrations start here. The central object is the PaymentIntent, which represents a single attempt to collect money from a customer. You create one with an amount and currency, attach a payment method, confirm it, and Stripe handles card network routing, 3D Secure authentication, retry logic, and settlement.

```bash
curl https://api.stripe.com/v1/payment_intents \
  -u sk_test_your_key: \
  -d amount=2000 \
  -d currency=usd \
  -d payment_method=pm_card_visa \
  -d confirm=true
```

The Payments API supports over 100 payment methods across 135+ currencies: cards, bank debits (ACH, SEPA), wallets (Apple Pay, Google Pay), and buy-now-pay-later options like Klarna and Affirm. For most SaaS platforms and e-commerce businesses, this is the only API you need to accept money.

Related endpoints include SetupIntents (saving payment methods without charging) and Refunds. There is also the older Charges API, which still works but lacks support for SCA requirements in Europe and newer payment methods. If you are starting a new integration, use PaymentIntents. Stripe has been steering developers toward this model since 2019, and their [llms.txt instructions section](https://www.apideck.com/blog/stripe-llms-txt-instructions-section) now explicitly tells AI coding assistants to do the same.

## Stripe Billing: Subscriptions and Invoices

Stripe Billing is the revenue engine for SaaS companies. It manages the full lifecycle of recurring payments: creating subscriptions, generating invoices, handling prorations on plan changes, managing trials, and collecting failed payments automatically.

The core objects are Product, Price, Subscription, and Invoice. A Product describes what you sell. A Price attaches a billing interval and amount to that product. A Subscription ties a customer to one or more prices and tells Stripe when to bill them. Invoices are generated automatically at each billing cycle.

The complexity Billing handles would take months to build yourself. When a customer on a $100/month plan upgrades to $200/month halfway through a billing cycle, Stripe calculates the prorated amount, generates the right invoice line items, and charges the difference. Subscription schedules let you model phased pricing, free trials that convert to paid plans, and multi-interval billing where different line items renew on different cadences.

Usage-based billing is another major capability. Stripe Billing supports metered pricing where you report usage throughout a billing period and Stripe calculates the total at invoice time. This model is common among AI and infrastructure companies that charge per API call, per token, or per compute hour. Anthropic, OpenAI, Cursor, and Midjourney all run on Stripe Billing.

At Stripe Sessions 2025, the company announced Scripts and Workflows: two extensibility primitives that turn Billing into a programmable revenue engine. Scripts let you inject custom business logic into specific API objects. Workflows let you orchestrate multi-step flows across Stripe products using conditional logic. These signal that Stripe views Billing as a platform in its own right.

For teams that need to sync Stripe Billing data with accounting platforms (QuickBooks, Xero, NetSuite, Sage), Apideck is building a dedicated Stripe Billing connector. This will pull subscription, invoice, and payment data from Stripe through Apideck's [Unified Accounting API](https://www.apideck.com/accounting-api) alongside [20+ other accounting platforms](https://www.apideck.com/blog/top-15-accounting-apis-to-integrate-with), using a single integration.

## Connect: Platforms and Marketplaces

Connect is Stripe's API for multi-party money movement. If your platform collects payments from customers and splits the proceeds among sellers, service providers, or other third parties, Connect handles funds flow, onboarding, compliance, and payouts.

### Accounts V2: the recommended path for new platforms

In December 2025, Stripe shipped the [Accounts V2 API](https://docs.stripe.com/connect/accounts-v2), which is now the recommended integration path for new Connect platforms. The core improvement: a single `Account` object that can be configured as a merchant (to accept payments), a customer (to be charged by your platform), and a recipient (to receive transfers). In the V1 API, representing the same business as both a connected account and a customer required creating and managing separate `Account` and `Customer` objects with no built-in relationship between them.

Accounts V2 provides three key advantages:

- **Flexible account configurations.** You assign `merchant`, `customer`, or `recipient` configurations to an Account to enable different capabilities. Adding a configuration later does not require re-collecting identity requirements that were already provided.
- **Centralized identity data.** KYC information is shared across configurations. A connected account that also subscribes to your platform's SaaS product does not need to verify their identity twice.
- **A single API for connected accounts and customers.** Any API endpoint that accepts a `customer` parameter also accepts a `customer_account` parameter, so you can use a configured Account in place of a Customer object when creating subscriptions, payment intents, or setup intents.

A V2 account creation call looks like this:

```bash
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Stripe-Version: 2025-12-15.clover" \
  --json '{
    "contact_email": "seller@example.com",
    "display_name": "Example Seller",
    "identity": {
        "country": "us",
        "entity_type": "company"
    },
    "configuration": {
        "merchant": {
            "capabilities": {
                "card_payments": { "requested": true }
            }
        }
    }
  }'
```

The V1 Accounts and Customers APIs are still fully supported. Stripe does not plan to remove them. You can also use the V2 API to manage accounts that were originally created with V1, including adding the `customer` configuration to existing V1 accounts. One caveat: if your platform uses OAuth to authenticate with connected accounts, continue using the V1 APIs for now.

### Charge models and funds flow

Whether you use V1 or V2, Connect's charge models remain the same. Each seller or provider on your platform gets a Stripe account, and Connect manages the relationship between your platform account and theirs. Three charge models are available: direct charges (the connected account is the merchant of record), destination charges (you collect payment and route funds to a connected account), and separate charges and transfers (you collect payment and transfer funds manually).

Connect also handles KYC verification, tax form generation (1099s in the US), and payout scheduling. Platforms like Shopify, DoorDash, Lyft, and Airbnb run on Connect. The API supports payouts to bank accounts in 118+ countries, instant payouts for eligible accounts, and cross-border payments in local currencies.

If you are building a [vertical SaaS](https://www.apideck.com/industries/vertical-saas) platform or marketplace, Connect is likely the most complex Stripe integration you will encounter. The onboarding flows alone require careful planning around what information to collect, when to verify it, and how to handle incomplete applications or failed identity checks.

![Stripe Connect API](//images.ctfassets.net/d6o5ai4eeewt/6ebvxbszeu0Vosjz4f7gDR/9dc6487e17001423330a029536d53db8/Screenshot_2026-03-22_at_12.37.35.png)

## Radar: Fraud Prevention

Radar is Stripe's machine learning fraud detection system. It runs on every payment processed through Stripe and assigns a risk score based on signals from the broader Stripe network. During Black Friday/Cyber Monday 2024, Radar blocked 20.9 million fraudulent transactions worth $917 million.

For most businesses, Radar works out of the box. You can also write custom rules using Stripe's rule language to block or review payments based on transaction amount, country of origin, velocity patterns, or metadata values. Radar for Fraud Teams adds manual review queues and more granular controls.

Risk scores are exposed through the Charge and PaymentIntent objects. You can feed Radar scores into your own fraud models via the API, which is useful if you run a multi-processor setup or have an in-house fraud team.

## Issuing and Treasury

Stripe Issuing lets you create, manage, and distribute virtual and physical payment cards programmatically. The typical use case is corporate expense cards, fleet cards, or rewards cards embedded in your platform. You create a cardholder, issue a card, set spending controls, and receive real-time authorization webhooks when the card is used.

Treasury provides banking-as-a-service infrastructure: FDIC-insured financial accounts, ACH and wire transfers, and the ability to hold, send, and receive funds. Together, Issuing and Treasury let platforms offer [embedded financial products](https://www.apideck.com/industries/fintech) (branded debit cards, business checking accounts inside your SaaS product) without becoming a bank.

Both APIs require additional onboarding with Stripe and typically involve partnerships with underlying bank partners like Evolve Bank or Cross River Bank.

## Tax, Sigma, and Data Pipeline

Stripe Tax automates sales tax, VAT, and GST calculation and collection across 102 countries. Since Sessions 2025, it also handles registration and filing, making it a full-cycle [tax compliance](https://www.apideck.com/use-cases/tax-automation) product. The API integrates with Checkout, Billing, and Invoicing, so you can enable tax collection by adding a single parameter to existing API calls.

Sigma provides a SQL interface for querying your Stripe data directly inside the Dashboard. Data Pipeline exports your Stripe data to external data warehouses (Snowflake, Redshift, BigQuery) on a scheduled basis. Both are useful for finance teams building custom reports, reconciliation workflows, or data models that combine Stripe data with other business data.

## Stripe Is Investing Heavily in Agent Experience

Stripe is one of the few API companies that has recognized a shift in who (or what) consumes its APIs. A growing share of Stripe integration code is now written by AI coding assistants, and Stripe is actively building infrastructure to make those interactions better. The company calls this [agent experience, or AX](https://www.apideck.com/blog/api-design-principles-agentic-era), a discipline parallel to developer experience but optimized for autonomous consumers.

The investments span multiple layers. Stripe hosts an official MCP server at `mcp.stripe.com`, giving AI agents direct, OAuth-secured access to Stripe's API. The `@stripe/agent-toolkit` provides function-calling integrations for LangChain, OpenAI's Agent SDK, CrewAI, and Vercel's AI SDK in both Python and TypeScript. Stripe also publishes OpenAPI specifications covering both v1 and v2 namespaces in a single file, which helps code generation tools and agent frameworks understand the full API surface.

The most distinctive piece is Stripe's [llms.txt instructions section](https://www.apideck.com/blog/stripe-llms-txt-instructions-section). Buried inside `docs.stripe.com/llms.txt` is a set of explicit instructions telling AI coding assistants to always use the Checkout Sessions API over the legacy Charges API, to default to the latest stable SDK version, and to never recommend the legacy Card Element or Sources API. No other API company has shipped anything like this. It is Stripe programming the behavior of every AI coding assistant that fetches that file before helping a developer integrate payments.

Stripe engineer Ian McCrystal said publicly that he expects AI tools to eventually become the predominant readers of Stripe's documentation. The company is building for that future now. Every docs page is available as clean Markdown (append `.md` to any URL), there are three separate llms.txt files across two domains, and the agent toolkit ships with granular permission controls via Restricted API Keys.

We wrote a [deeper analysis of Stripe's llms.txt approach](https://www.apideck.com/blog/stripe-llms-txt-instructions-section) and what it means for other API companies. If you run an API, that post is worth reading.

## API Design and Versioning

Stripe's API follows a REST design with form-encoded request bodies and JSON responses. Authentication uses secret API keys passed via HTTP Basic Auth. Every object has a consistent structure: an `id`, an `object` type field, and a `metadata` hash for attaching your own key-value pairs.

The API uses a rolling versioning model with named releases. The current major release is Clover (2025-09-30), following Basil and Acacia. Each major release can include breaking changes. Monthly releases within a major version are additive and backwards-compatible. You pin your integration to a specific version using the `Stripe-Version` header or your SDK version.

The v2 namespace (`/v2/`) introduces improved idempotency handling, thin events (lightweight webhooks containing only essential data rather than full object snapshots), and a clearer `include` parameter for requesting additional fields. You can mix v1 and v2 endpoints in the same integration.

Webhooks are essential for any production Stripe integration. Stripe sends events to your configured endpoints when objects change state. For billing, you will typically listen for `invoice.paid`, `invoice.payment_failed`, `customer.subscription.updated`, and `customer.subscription.deleted`. For payments, `payment_intent.succeeded` and `payment_intent.payment_failed` are the critical ones. The v2 thin event format reduces payload size and avoids the stale-snapshot problem from earlier webhook implementations.

## Where Apideck Fits: Connecting Stripe Billing to the Accounting Stack

Most businesses that use Stripe Billing also use an accounting platform. Invoices generated in Stripe need to appear in the general ledger. Subscription revenue needs to be recognized correctly. Payments need to reconcile against bank transactions.

Building a direct integration between Stripe and a single accounting platform is straightforward. Building integrations between Stripe and QuickBooks and Xero and NetSuite and Sage Intacct and FreshBooks is a different problem. Each platform has its own API, authentication scheme, data model, and rate limits. Maintaining five or six of these in parallel is a full-time job for an engineering team.

This is the problem Apideck's [Unified Accounting API](https://www.apideck.com/accounting-api) solves. One integration, [20+ accounting platforms](https://www.apideck.com/integrations), normalized data models, and [managed authentication](https://www.apideck.com/products/vault). For teams building [accounting integrations](https://www.apideck.com/blog/accounting-integration), it cuts months of development work down to days.

We are adding a Stripe Billing connector to bring subscription, invoice, and payment data from Stripe into the same unified schema that already covers QuickBooks, Xero, NetSuite, Sage, and the rest of the [accounting ecosystem](https://www.apideck.com/blog/the-complete-guide-to-accounting-api-integrations-for-fintech). If your platform needs to sync billing data across providers, or your customers use Stripe Billing alongside traditional accounting software, this connector simplifies that connection.

## Getting Started

If you are evaluating a Stripe integration, start by identifying which API surface you actually need. For one-time payments, the Payments API is sufficient. For recurring billing, add Stripe Billing. For marketplaces and platforms, add Connect. Layer in Radar, Tax, Issuing, or Treasury based on your specific requirements.

Stripe's developer documentation at [docs.stripe.com](https://docs.stripe.com) is among the best in the industry. The API reference includes runnable examples, test mode keys, and client libraries in seven languages. Their Discord server has active Stripe engineers answering technical questions.

For teams that need Stripe Billing data flowing into their accounting stack alongside other platforms, [get started with Apideck](https://www.apideck.com) and keep an eye on the Stripe Billing connector launch.

Stripe's API spans hundreds of endpoints across Payments, Billing, Connect, Radar, Issuing, Treasury, and Tax. This guide breaks down each API surface, when to use it, and how the pieces connect, including the new Accounts V2 API for Connect platforms and how Apideck's upcoming Stripe Billing connector fits into the accounting integration picture.

An introduction to the Stripe APIs: A Developer's Guide to Every API Surface

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](https://www.openbankingtracker.com) 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](/blog/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](https://www.apideck.com/integrations/oracle-netsuite) uses an ERP banking connector. A small business on [QuickBooks](https://www.apideck.com/integrations/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](/blog/accounting-erp-integration-banks-use-cases). 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](https://www.apideck.com/accounting-api) automatically. Challenger banks like Allica Bank and Monzo have turned this into a competitive differentiator, offering free integration with [Xero](https://www.apideck.com/integrations/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](/blog/treasury-management-systems-multi-bank-connectivity-integrations) 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](/blog/treasury-management-systems-multi-bank-connectivity-integrations).

### Unified API providers

For banks that need to connect to many accounting and ERP platforms at once, a [unified API](https://www.apideck.com/unified-apis/accounting) provides a single normalized interface that maps to multiple downstream systems. Instead of building separate integrations for QuickBooks, Xero, Sage, NetSuite, [Exact Online](https://www.apideck.com/integrations/exact-online), [MYOB](https://www.apideck.com/integrations/myob), and [Microsoft Dynamics 365](https://www.apideck.com/integrations/dynamics-365-business-central), the bank builds one integration and gets connectivity to all supported platforms through a single schema.

[Apideck's Accounting API](https://www.apideck.com/accounting-api) supports 30+ 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](https://www.apideck.com/blog/accounting-integration). 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](https://www.apideck.com/integrations/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](/blog/erp-api-integration) is an engineer not working on core banking products. This is the problem [unified accounting APIs](/blog/what-is-a-unified-api) 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](https://www.apideck.com/industries/banking) 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](https://www.apideck.com/accounting-api) for the accounting data pipe.

Apideck's [Accounting API](https://www.apideck.com/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](https://www.apideck.com/accounting-api).

ERP banking is the practice of embedding banking services directly inside ERP and accounting systems. This guide explains what it is, why it matters, how it works technically, and where the market is heading.

What Is ERP Banking? The Shift From Portal to Platform

If you work in partnerships or business development at a software platform, there's a good chance someone from a unified API provider has already reached out to you. Maybe it was us at Apideck. Maybe it was a competitor.

The instinct that usually follows is skepticism. Another middleware company asking for access to your API. Another layer wedged between your platform and the companies building on top of it. Why would you want that?

It's a fair question, and it deserves a straight answer instead of a pitch. So here is ours.

## What is a unified API provider?

A [unified API](https://www.apideck.com/blog/what-is-a-unified-api) provider builds and maintains connectors to multiple platforms inside a single software category, then gives B2B software companies one standardized API to reach all of them.

Take a B2B SaaS company that needs to connect to several accounting platforms: [QuickBooks](https://www.apideck.com/integrations/quickbooks), [Xero](https://www.apideck.com/integrations/xero), [Sage Intacct](https://www.apideck.com/integrations/sage-intacct), [NetSuite](https://www.apideck.com/integrations/netsuite), [FreshBooks](https://www.apideck.com/integrations/freshbooks), and a handful more. On its own, that team has to read each platform's API docs, build a separate connector for each, handle a different authentication method every time, normalize data across schemas that rarely agree, and then keep all of it working as those APIs change. Months of engineering per platform, and the maintenance never ends.

Through a unified API provider like Apideck, the same company integrates once per category. We build and maintain the underlying connectors, handle authentication through Vault (which keeps your platform's own branded OAuth experience intact), normalize responses into a consistent model, and absorb the ongoing maintenance. They ship the integration once, and it works across every supported platform in that category.

Apideck maintains more than 200 connectors across seven unified APIs: Accounting, HRIS, CRM, ATS, Ecommerce, File Storage, and Issue Tracking. Over 200 B2B SaaS and fintech companies build on that infrastructure.

### How this differs from an embedded iPaaS

You have probably been approached by embedded iPaaS providers too, and the difference between the two models matters most from where you sit as a platform.

An [embedded iPaaS](https://www.apideck.com/blog/top-embedded-ipaas-solutions) gives a B2B software company a visual workflow builder that lives inside its product. When that company's customers (the people using your platform every day) set up an integration, they work through the iPaaS interface, configuring workflows and mapping fields in a third-party layer. The iPaaS effectively becomes another product your customers have to learn.

A unified API provider stays out of view. The B2B software company's engineers build the integration straight into their product against a developer-friendly API. Your customers never touch Apideck. What they see is that your platform is natively supported inside the product they already use, so the integration reads as a native part of that product.

That difference has consequences for you. When a company connects to your platform through Apideck, your customers still authenticate through your own branded OAuth flow, and no third-party interface ever sits between your platform and the companies that rely on it.

## What this means for your platform

Every company that builds on Apideck and switches on your connector is a company whose product now integrates with your platform. That creates value in three directions.

### Your platform becomes stickier

Every integration running through Apideck makes your platform harder to leave. Once your customers wire their workflows into your product through the other tools they already run, the cost of switching to a competitor climbs. The more your ecosystem connects to, the deeper your platform sits in their daily operations.

The retention data is consistent on this. [ProfitWell's Integration Benchmarks study](https://www.profitwell.com/integration-benchmarks), drawn from 500,000 software companies, found that products with at least one integration see 10 to 15% higher retention, climbing to 18 to 22% once a product has four or more. Willingness to pay moves the same way: products with integrations command around 20% more from customers using five to ten of them, and over 30% more once customers pass eleven.

For a platform, that math runs in your favor. Every integration pointing at your API gives a customer one more reason to stay. And unlike the features you would otherwise have to build and keep alive yourself, integrations delivered through a unified API provider cost your engineering team nothing.

The buying side points in the same direction. [Gartner's 2024 Global Software Buying Trends report](https://www.gartner.com/en/digital-markets/insights/understanding-software-buyers-priorities), based on a survey of 2,499 B2B software buyers, found that a vendor's ability to support integrations is the top sales-related factor in a purchase decision, named by 44% of respondents. So integrations keep the customers you have, and they help those customers win deals of their own, which sends more activity back through your platform.

### Your customers' end users get a better experience

End users expect their software to work together. A finance team on your [accounting platform](https://www.apideck.com/blog/accounting-software-integration) assumes it will connect to the other tools they run every day, from spend management to tax compliance. When those connections aren't there, the work falls back to manual data entry, and that friction eventually turns into a reason to evaluate someone else.

The same holds well beyond accounting. An HRIS platform or an applicant tracking system sits in exactly the same web of connected tools its users depend on. A unified API provider closes that gap at scale, linking your platform to the wider ecosystem of B2B software your customers already work in.

### Your ecosystem partners can move faster

The companies building on your platform, through your marketplace or your developer program, gain from this too. They face the same integration problem from the other side: they need to connect to many platforms across a category, and [building each connector](https://www.apideck.com/blog/why-an-integration-platform-beats-point-to-point-saas-integrations) by hand is slow and expensive.

When your platform is reachable through a unified API, those partners get to your customers sooner. The barrier to joining your ecosystem drops, which means more applications in your marketplace and a richer set of options for the customers you already have.

## How the data flows

The question we hear most from platform partnership teams is some version of this: how does the data move, and are you storing our customers' data?

No, we don't store it. Apideck runs a [real-time passthrough](https://www.apideck.com/blog/the-power-of-real-time-unified-apis) architecture. When one of our customers makes an API call, we route that request to your platform's API as it happens. Your platform processes it and returns the response. We normalize that response into a standard format and pass it back to our customer. Nothing is stored or cached along the way.

Your platform stays the single source of truth and the data is always live, with no sync-and-cache layer in between to introduce staleness or data residency questions.

A few related details tend to matter to platform teams. Authentication runs through Apideck's Vault, which enforces OAuth 2.0 flows that follow your brand guidelines, so your customers see your own authorization screen when they connect. Our infrastructure honors your published rate limits and throttles requests to your specifications, so no surprise traffic spikes land on your API. And every API request is logged for 90 days, which lets developers troubleshoot integration issues themselves instead of routing them to your support team.

## Addressing common concerns

A few questions come up in almost every conversation we have with platform partnership teams.

### "Won't this undermine our direct partnerships?"

It works the other way around. A unified API provider doesn't replace the [partnership](https://www.apideck.com/blog/integration-partnerships-arent-a-hurdle) between your platform and the companies building on you; it removes the slowest part of that partnership, the technical integration, and leaves more room for everything else.

Every integration partnership has a technical side and a commercial side. The technical side is building and maintaining the connector, handling authentication, normalizing data, and tracking API changes. The commercial side is the marketplace listing, the co-marketing, the co-selling, the support alignment, the work that moves revenue.

Apideck takes the technical side off both your plates. That frees your team and the B2B software company to spend time on the commercial relationship instead of on engineering that has to finish before the partnership can show any results. Go-to-market starts on day one rather than after a quarter of build work.

Partner size doesn't change the logic. A large enterprise vendor gets to point its engineers at core product rather than connector maintenance. A small startup gets to list your platform as a supported integration without standing up and maintaining a connector of its own. Either way the partnership comes out stronger, because the technical barrier is gone and both sides can put their energy into the relationship.

### "How is this different from scraping or unofficial access?"

Apideck builds and maintains connectors against your platform's documented API, using OAuth 2.0 authentication and staying inside the terms and guidelines you publish. We don't reverse-engineer private APIs, scrape data out of user interfaces, or rely on credential-sharing workarounds; every connector we run is built to operate the way your platform intends integrations to work.

Where we hold certified partnerships, the connector is formally recognized and reviewed by the platform's own partnership team, and we keep pursuing that level of formal collaboration with more platforms.

### "What would working together actually look like?"

What collaboration looks like depends on what suits your platform.

The deepest version is a certified partnership. Apideck goes through your partner program and meets your technical and compliance requirements to become an officially recognized integration partner. Your team gets full visibility into how the connector behaves, and both sides get the most out of the arrangement. That is how our existing certified partnerships work.

A lighter version is developer program participation. Plenty of platforms run open developer or partner programs with documented requirements and self-serve onboarding, and Apideck joins those on the same terms and to the same standards as anyone else building on your API.

When neither of those is the right starting point, the essentials are enough: API documentation, access credentials, and a sandbox or test environment let us build and maintain a high-quality connector. That kind of access isn't always public, so we will work with your team to set it up in a way that fits your internal policies. It also lets both sides try the relationship with little commitment before deciding whether to formalize it.

Which model fits depends on your own policies and where you are in your integration strategy. We stay flexible because no two platforms arrive with the same needs.

## Who already works with Apideck

Apideck holds certified partnerships with some of the most widely used platforms in B2B software: Intuit (QuickBooks), Workday (where we are a Silver Partner), Sage Intacct, Sage Business Cloud Accounting, SAP, and HubSpot. Each of them ran its own evaluation and decided that working with Apideck was good for its ecosystem.

Beyond those certified partnerships, Apideck maintains more than 200 connectors across seven categories, and our customers include over 200 B2B SaaS and [fintech](https://www.apideck.com/blog/top-fintech-apis-for-startups) companies, from early-stage startups to established enterprise vendors.

On security, we are SOC 2 Type 2 compliant, encrypt data with AES-256, enforce TLS for everything in transit, and run regular third-party penetration tests.

## Getting started

If you want to see what working with Apideck could look like, the simplest first step is a conversation. We will show you how our connectors work and which model of collaboration fits your platform best.

There is no long-term commitment attached to that first conversation. It is a chance to talk through how we might help your ecosystem grow.

You can reach our partnership team at [partners@apideck.com](mailto:partners@apideck.com).

What a unified API provider does for your platform: stickier integrations, native UX, faster ecosystem partners, and zero engineering cost to you.

What platforms gain from working with a unified API provider

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](/blog/xero-api-pricing-and-the-app-partner-program) 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](/blog/how-to-get-xero-api-key), 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](/blog/bank-feeds-api-integration) 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](https://developers.apideck.com/connectors/xero/docs/application_owner+oauth_credentials) 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](/blog/accounting-and-erp-partnership-guide), 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](/blog/accounting-integration) 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](https://devblog.xero.com/upcoming-changes-to-xero-accounting-api-scopes-705c5a9621a0)

Xero's full scope reference documentation: [OAuth 2.0 Scopes](https://developer.xero.com/documentation/guides/oauth2/scopes/)

For a detailed breakdown of the pricing tiers that accompany these scope changes: [Xero API Pricing and the App Partner Program](/blog/xero-api-pricing-and-the-app-partner-program)

For teams evaluating alternatives alongside Xero: [Top 15 Accounting APIs to Integrate with in 2026](/blog/top-15-accounting-apis-to-integrate-with)

For a broader look at the Xero integration landscape: [Xero Integrations: The Complete Guide for 2026](/blog/xero-integrations)

Xero replaced two broad OAuth 2.0 scopes with ten granular ones for all apps created after March 2, 2026. Existing apps have until September 2027 to migrate. Here is what changed, what scopes you need, and how to handle the transition.

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

SnelStart is one of the most widely used accounting platforms in the Netherlands. It serves freelancers, small and medium-sized businesses, and accounting firms with bookkeeping, invoicing, VAT filing, and bank reconciliation. If you are building software that touches financial data for the Dutch market, SnelStart integration is likely on your roadmap.

This guide covers what you need to know to integrate with the SnelStart B2B API, from authentication and available endpoints to the certification process and the common pitfalls that make this integration more complex than it first appears.

## What SnelStart covers

SnelStart has been around for over 40 years. It started as a desktop bookkeeping program on Texel and has since grown into a full platform available in both desktop (SnelStart 12) and cloud (SnelStart Web) versions. The product handles core accounting workflows including general ledger management, accounts payable and receivable, invoicing, VAT and ICP declarations, bank statement imports, and inventory management through their InHandel add-on.

For accountants and bookkeepers, SnelStart offers a dedicated Accountant package with multi-client management, an integrated tax filing module, and a centralized dashboard. It connects to major Dutch banks including Rabobank, ABN AMRO, ING, Knab, Triodos, and RegioBank.

In mid-2025, SnelStart acquired embedded finance company [Flow](https://www.withflow.com/) and launched SnelStart Bankieren, a fully integrated banking product with Adyen providing the underlying banking infrastructure. This puts bank accounts directly inside the accounting interface, eliminating the need to switch between banking and bookkeeping tools.

## API overview

The SnelStart B2B API is a REST API hosted on Microsoft Azure API Management. The current version is v2, and the base URL is `https://b2bapi.snelstart.nl/v2`. The API documentation is auto-generated and available through the [SnelStart Developer Portal](https://b2bapi-developer.snelstart.nl/), but only after you register for an account. The documentation is exclusively in Dutch, which creates an extra barrier for international development teams.

The API covers a broad set of accounting resources. Key endpoints include:

- Artikelen (articles/products)
- Relaties (contacts/relations)
- Verkoopboekingen (sales bookings)
- Inkoopboekingen (purchase bookings)
- Memoriaalboekingen (journal entries)
- Grootboekrekeningen (general ledger accounts)
- BTW-tarieven (VAT rates)
- Bankafschriftbestanden (bank statement files)
- Documenten (documents)
- Facturen (invoices)
- Landen (countries)

The API supports standard CRUD operations on most resources. You can also import bank statements in MT940, CAMT.053, and CSV formats, as well as UBL invoices. OCR processing is available for scanned documents.

## Authentication

This is where SnelStart diverges significantly from other [accounting APIs](https://www.apideck.com/accounting-api). There is no standard OAuth 2.0 flow. Instead, SnelStart uses a multi-layered authentication setup that requires careful credential management.

You need three things to make API calls:

1. A subscription key from the SnelStart Developer Portal. You get this by subscribing to a product plan (start with the Ontwikkeling & Test plan for development).
2. A connection key (maatwerksleutel) generated from within the SnelStart web application under Koppelingen > Maatwerk.
3. An access token obtained by exchanging the connection key at the token endpoint (`https://auth.snelstart.nl/b2b/token`).

The access token expires every hour. Every API request must include both the subscription key (as a header) and the current access token. This means you need to build automated token refresh logic, handle expiration errors gracefully, and store credentials securely.

In a multi-tenant SaaS architecture where you are managing connections for multiple end users, this adds real operational complexity. Each customer's connection key needs to be stored separately, and you need to manage token lifecycle per connection.

Here is a simplified authentication flow in pseudocode:

```
// Step 1: Exchange connection key for access token
POST https://auth.snelstart.nl/b2b/token
Body: { "clientKey": "<connection_key>" }

// Step 2: Use the token with your subscription key
GET https://b2bapi.snelstart.nl/v2/artikelen
Headers:
  Ocp-Apim-Subscription-Key: <subscription_key>
  Authorization: Bearer <access_token>
```

There are open-source client libraries that handle some of this complexity. The [snelstart-php](https://github.com/iwd-nl/snelstart-php) library includes a `CachedAccessTokenConnection` class that manages token refresh automatically. A .NET client is also available on NuGet as `SnelStart.B2B.V2.Client`, though it is community-maintained and not feature-complete.

## Working with SnelStart data models

The SnelStart API exposes data in a way that reflects its internal accounting logic rather than a developer-friendly integration model. This creates several challenges.

Relations (contacts) may reference a country by internal ID rather than by ISO country code. To resolve this, you need a separate API call to the countries endpoint. Because SnelStart allows countries to be created, modified, or deleted, you cannot treat this reference data as static. You need caching strategies and dependency-aware synchronization.

Booking proposals (boekingsvoorstellen) require tax information at both the header level and on each individual line item. These must be consistent with each other. Any mismatch triggers a validation error. This means your data transformation layer needs robust validation logic to align your internal data structures with what SnelStart expects.

Many common integration use cases require multiple sequential API calls. Fetching a complete invoice with its customer details, line items, tax rates, and related documents can involve several round trips. Without careful orchestration, you will run into performance issues and risk data inconsistency.

## The certification process

SnelStart requires all integrations to go through a formal certification process before they can be used in production. The process works like this:

1. Register on the [SnelStart Developer Portal](https://b2bapi-developer.snelstart.nl/) and subscribe to a development plan.
2. Build your integration using the development subscription key and a test connection key.
3. When your integration is ready, submit it for certification through the SnelStart website.
4. SnelStart monitors your integration for approximately 12 days during the certification period.
5. If the integration meets their requirements, you receive a permanent production key (maatwerk- or productiesleutel).

SnelStart charges a one-time fee of 250 EUR (ex. BTW) per permanent key issued after certification. A production key allows an unlimited number of customers to use the integration.

Without certification, you only have access to a temporary development key. To operate in live customer environments, you must become an official SnelStart partner. This gating mechanism means you cannot ship a SnelStart integration to production without going through the approval process.

## Package requirements

Not every SnelStart subscription includes API access. Your customers need to be on the inZicht or inControle package to set up custom API connections via the Maatwerk tile. This is worth validating early in your sales process. If a customer is on a lower-tier plan, they will need to upgrade before your integration can work.

## Common integration challenges

Based on what developers encounter when building direct SnelStart integrations:

The documentation is only available in Dutch and requires registration to access. International teams face a translation overhead before they can even evaluate the API surface.

The hourly token expiration is aggressive compared to most accounting APIs. If your token refresh logic fails silently, requests will start returning 401 errors and your sync pipeline breaks.

The fragmented data model means simple operations often require multiple API calls. A single invoice sync might need calls to contacts, tax rates, ledger accounts, and the invoice endpoint itself.

Tax handling is unusually complex. The duplication of tax information at booking and line-item level increases the surface area for validation errors.

There is no webhook support documented in the public API. You will need to implement polling-based synchronization, which adds latency and API call volume.

## Scaling beyond SnelStart

If you are building for the Dutch market, SnelStart is a must-have connector. But most SaaS companies serving accounting workflows need to support more than one platform. Your Dutch customers might use SnelStart, but their international counterparts are on [QuickBooks](https://www.apideck.com/blog/quickbooks-api-pricing-and-the-intuit-app-partner-program), [Xero](https://www.apideck.com/blog/xero-api-pricing-guide), Exact Online, or [Sage](https://www.apideck.com/blog/your-guide-to-building-a-sage-intacct-api-integration).

Building and maintaining each of these integrations one-to-one is expensive. Each accounting API has its own authentication model, data schema, rate limits, and edge cases. SnelStart's multi-layer authentication and Dutch-only docs are a good example of why this does not scale.

A [unified API](https://www.apideck.com/blog/what-is-a-unified-api) gives you one integration point, one data schema, and one set of SDKs across all of them. Instead of managing SnelStart's token rotation, Xero's OAuth flow, and QuickBooks' different API versions separately, you write against a single normalized [Accounting API](https://developers.apideck.com/apis/accounting/reference) and let the platform handle the connector-specific complexity.

Check the full list of [accounting connectors](https://developers.apideck.com/apis/accounting) to see which platforms are available.

## Resources

- [SnelStart Developer Portal](https://b2bapi-developer.snelstart.nl/)
- [SnelStart API integration page](https://www.snelstart.nl/api)
- [snelstart-php client library (GitHub)](https://github.com/iwd-nl/snelstart-php)
- [SnelStart B2B V2 .NET client (NuGet)](https://www.nuget.org/packages/SnelStart.B2B.V2.Client)
- [Apideck Accounting API reference](https://developers.apideck.com/apis/accounting/reference)
- [Apideck accounting connectors](https://developers.apideck.com/apis/accounting)

A technical guide to integrating with the SnelStart B2B API. Covers authentication, key endpoints, the certification process, and common challenges developers face when building accounting integrations for the Dutch market.

How to Integrate With the SnelStart API

Bank API integration connects banks to accounting platforms and ERP systems through standardized interfaces. This guide covers use cases from bank feeds and payment initiation to credit underwriting, the engineering challenges of supporting multiple platforms, and how unified APIs solve the fragmentation problem.

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

TL;DR: MCP tool definitions can burn 55,000+ tokens before an agent processes a single user message. We built the Apideck CLI as an AI-agent interface instead:an ~80-token agent prompt replaces tens of thousands of tokens of schema, with progressive disclosure via `--help` and structural safety baked into the binary. Any agent that can run shell commands can use it. No protocol support required.

Your MCP Server Is Eating Your Context Window. There's a Simpler Way

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](https://www.numeric.io/blog/account-reconciliation-software) 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](/blog/treasury-management-systems-multi-bank-connectivity-integrations). 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](/blog/bank-feeds-api-integration) 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](/blog/money-movement-infrastructure-fintech-ledger-as-a-service), 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](https://developers.apideck.com/guides/bank-feeds-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](/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.

```javascript
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.

```javascript
// 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.

```javascript
// 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](https://developers.apideck.com/guides/bank-feeds-xero)), 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.

```javascript
// 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](/blog/what-is-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](/blog/top-15-accounting-apis-to-integrate-with), 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](/blog/what-is-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](/blog/accounting-integration).

## 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](/accounting-api) 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:**
- [Bank Feeds API Integration: Why You Can't Afford to Skip This Feature](/blog/bank-feeds-api-integration)
- [Treasury Management Systems: Multi-Bank Connectivity Guide](/blog/treasury-management-systems-multi-bank-connectivity-integrations)
- [Money Movement Infrastructure](/blog/money-movement-infrastructure-fintech-ledger-as-a-service)
- [What is Open Accounting?](/blog/what-is-open-accounting)
- [Top 15 Accounting APIs to Integrate with in 2026](/blog/top-15-accounting-apis-to-integrate-with)

---

*Disclaimer: Apideck's [Unified Accounting API](/accounting-api) supports journal entries, chart of accounts, bank feeds, and bank transaction sync across QuickBooks, Xero, NetSuite, Sage, and [30+ other accounting and ERP platforms](/integrations). If you are building treasury accounting features, [get in touch](/contact) or explore the [API reference](https://developers.apideck.com/apis/accounting/reference) to see how it works.*

Your treasury product is working. Customers are depositing funds, earning yield, and paying bills from a single platform. Then the finance team calls. They need to reconcile treasury activity in QuickBooks. And suddenly your product creates more manual work than it eliminates.

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

Oracle Fusion Cloud is one of the most widely deployed enterprise suites in the world. Oracle Fusion Cloud Financials, HCM, SCM, and CX together cover everything from general ledger and accounts payable to workforce management and supply chain. If you're building integrations that need to pull or push data to Oracle Fusion, you'll be working with its REST APIs. This guide walks through what you need to know to get up and running, from authentication to making your first API call and handling the quirks that aren't always obvious from the docs.

## Understanding the API landscape

Oracle Fusion Cloud is not a single API. It's a collection of REST APIs organized by product pillar, each with its own base path and resource structure:

- **ERP / Financials / SCM**: base path is `/fscmRestApi/resources/{version}/`. This covers Oracle Fusion Cloud Financials modules like General Ledger, Accounts Payable, Accounts Receivable, and Fixed Assets, as well as Procurement and Supply Chain.
- **HCM**: base path is `/hcmRestApi/resources/{version}/`
- **CX / Sales**: base path is `/crmRestApi/resources/{version}/`
- **Common features**: base path is `/fscmRestApi/resources/{version}/` (shared across pillars)

A full endpoint URL looks something like this:

```
https://{instance}.fa.{datacenter}.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices
```

The version string (e.g. `11.13.18.05`) matters. Some resources have multiple versions, and newer ones may include a `v1` path that uses Oracle's BOSS (Business Object Spectra Services) framework. The v1 APIs use a different, longer path pattern:

```
https://{instance}.fa.{datacenter}.oraclecloud.com/api/boss/data/objects/ora/{module}/{domain}/v1/$en/{resource}
```

You can tell which type you're working with by looking at the URL: if it contains `/api/boss/`, it's a BOSS v1 endpoint. If it contains `/RestApi/resources/`, it's the older ADF-based style.

All APIs use JSON as the default format and support standard HTTP methods: GET, POST, PATCH, and DELETE.

## Authentication

This is where Oracle Fusion integrations tend to get complicated. There are three supported authentication mechanisms, and the right one depends on your use case.

### Basic authentication over SSL

The simplest option. You pass a username and password in the HTTP Authorization header. This works for development and testing, but Oracle recommends against it for production.

```bash
curl -u username:password \
  -X GET "https://{instance}.fa.{datacenter}.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices" \
  -H "Content-Type: application/json"
```

One thing to watch out for: basic auth doesn't work if multi-factor authentication is enabled on the account.

### OAuth 2.0 (recommended for production)

Oracle Fusion uses OCI Identity and Access Management (IAM) as the authorization server. You'll need to create a confidential application in the IAM identity domain linked to your Fusion instance. At a high level:

1. Log in to the OCI IAM Admin Console and navigate to your Fusion identity domain.
2. Create a confidential application.
3. Choose the grant type. For server-to-server integrations without user involvement, use Client Credentials. For flows where a user needs to authorize access, use Authorization Code (3-legged OAuth).
4. Define the access scope. For v1/BOSS APIs, the scope follows the pattern `urn:opc:resource:fusion:{podname}:boss/`.
5. Activate the application and note the Client ID and Client Secret.

To get an access token with client credentials:

```bash
curl -u {client_id}:{client_secret} \
  --basic \
  -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
  --request POST \
  "https://{identity-domain-url}/oauth2/v1/token" \
  -d "grant_type=client_credentials&scope=urn:opc:resource:fusion:{podname}:boss/"
```

Then use the token in your API calls:

```bash
curl -X GET \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  "https://{instance}.fa.{datacenter}.oraclecloud.com/fscmRestApi/resources/11.13.18.05/invoices"
```

If you're using Client Credentials, you also need to configure the Client ID as a user in Fusion Applications through the Security Console. The username in Fusion must match the auto-generated Client ID exactly.

### JWT token authentication

For certificate-based flows, you can use a signed JWT to authenticate. This involves registering a certificate with Oracle Fusion's API Authentication configuration and using it to sign tokens. This approach gives you more control over certificate lifecycle management but requires more setup.

## Making your first request

Once authenticated, the pattern is consistent across all Fusion APIs. Here's a basic example fetching worker records from HCM:

```bash
curl -u username:password \
  -X GET \
  "https://{instance}.fa.{datacenter}.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers" \
  -H "Content-Type: application/vnd.oracle.adf.resourceitem+json"
```

To explore the structure of any resource, append `/describe` to the endpoint:

```bash
curl -u username:password \
  -X GET \
  "https://{instance}.fa.{datacenter}.oraclecloud.com/hcmRestApi/resources/11.13.18.05/workers/describe" \
  -H "Content-Type: application/vnd.oracle.adf.resourceitem+json"
```

This returns the full schema, including available fields, child resources, and supported operations.

### Creating a record

POST requests follow the same pattern. Here's a simplified example creating a supplier in the ERP module:

```bash
curl -u username:password \
  -X POST \
  "https://{instance}.fa.{datacenter}.oraclecloud.com/fscmRestApi/resources/11.13.18.05/suppliers" \
  -H "Content-Type: application/vnd.oracle.adf.resourceitem+json" \
  -d '{
    "Supplier": "Acme Corp",
    "SupplierType": "Supplier",
    "Status": "ACTIVE"
  }'
```

### Filtering and pagination

Oracle Fusion REST APIs support query parameters for filtering, but the syntax depends on which REST Framework Version your instance uses.

In Framework Version 1 (the default on most instances), the `q` parameter uses query-by-example syntax with semicolons separating conditions:

```
GET /fscmRestApi/resources/11.13.18.05/invoices?q=InvoiceNumber='INV-001';InvoiceCurrency=USD
```

In Framework Version 2 and later, the `q` parameter uses RowMatch expressions with SQL-like operators:

```
GET /fscmRestApi/resources/11.13.18.05/invoices?q=InvoiceNumber = 'INV-001' and InvoiceCurrency = 'USD'
```

Version 2 also supports `like`, `between`, `in`, and `or` operators. You can check which version your instance uses (or set it via the `REST-Framework-Version` request header).

For predefined queries, use the `finder` parameter. Finders are resource-specific and discoverable via the `/describe` endpoint. The syntax uses semicolons before the first variable and commas between subsequent ones:

```
GET /fscmRestApi/resources/11.13.18.05/currencyRates?finder=CurrencyRatesFinder;fromCurrency=INR,toCurrency=USD
```

Pagination is handled through `offset` and `limit` parameters. The default page size varies by resource, so always check the `hasMore` flag in the response:

```json
{
  "items": [...],
  "count": 25,
  "hasMore": true,
  "limit": 25,
  "offset": 0
}
```

## Choosing the right integration pattern

Not every integration scenario calls for REST APIs. Oracle provides multiple patterns, and picking the wrong one will cause headaches down the line.

REST APIs are best for real-time, low-volume operations. Think: creating or updating a single record, looking up a customer, or syncing a handful of transactions. Oracle enforces rate limits that vary by identity domain type and returns a 429 error when exceeded. Unofficial estimates put the threshold at roughly 5,000 API calls per hour per user, which is workable for transactional use cases but not enough for bulk operations.

File-Based Data Import (FBDI) is the recommended approach for high-volume data loads. You prepare CSV files, upload them to Oracle's Universal Content Management (UCM) server, and trigger an import process. This is batch-oriented, so it won't give you real-time feedback, but it handles millions of records reliably.

Business events are Oracle's publish/subscribe mechanism. When something changes in Fusion (a PO is approved, an invoice is created), the system raises an event. You can subscribe to these events to trigger downstream workflows. Outbound business events can invoke web services or send messages, but they require Oracle Integration Cloud (OIC) for third-party integrations.

BICC (Business Intelligence Cloud Connector) is built for large-volume data extraction from ERP and SCM. If you need to sync historical data or run incremental extracts, BICC is more appropriate than the REST APIs.

The general rule: use REST APIs for real-time reads and writes of individual records. Use FBDI for bulk imports. Use BICC for bulk exports. Use business events for event-driven workflows.

## Common pitfalls

A few things that trip up most developers building Oracle Fusion integrations for the first time:

POST operations have a record limit. Oracle recommends limiting POST operations to a maximum of 500 records per request. Exceeding this can lead to timeouts or partial failures.

Not all operations are supported on every resource. If a GET works but a PATCH doesn't, check whether the resource supports that method. Some resources are read-only. When an operation isn't available, Oracle's documentation usually points you to alternatives like SOAP services or FBDI.

Security roles and permission groups. Access to the API isn't just about authentication. The user or service account needs the right job roles assigned in the Fusion Security Console. For v1/BOSS APIs specifically, the roles also need permission groups enabled. Without these, you'll get 403 errors that can be difficult to troubleshoot.

Content-Type headers matter. Oracle Fusion APIs often expect `application/vnd.oracle.adf.resourceitem+json` rather than a plain `application/json`. Using the wrong content type can result in cryptic error responses.

Nested/child resources return limited data by default. When you fetch a parent resource, child data may not be included unless you explicitly expand it using the `expand` query parameter or request specific fields with `fields`.

Rate limiting is per user, not per application. If multiple systems share the same integration user, they share the same rate limit pool.

## Using a unified API to simplify Oracle Fusion integrations

Building direct integrations to Oracle Fusion works, but the authentication setup, permission management, and pillar-specific API differences add up fast, especially if your product also needs to integrate with other ERPs, accounting platforms, or HRIS systems.

Unified API platforms can abstract away the Oracle-specific complexity and give you a single interface that works across Oracle Fusion and dozens of other connectors. Instead of managing OAuth flows, permission groups, and content-type quirks for each system, you authenticate once and use a normalized data model.

This is particularly useful if you're integrating accounting, HRIS, or CRM data across customers who may be running Oracle Fusion, NetSuite, SAP, Workday, or QuickBooks. Rather than building and maintaining separate integrations for each, a unified API lets you build once and support all of them.

## Resources

- [Oracle Fusion Cloud REST API documentation](https://docs.oracle.com/en/cloud/saas/applications-common/25d/farca/index.html)
- [REST API for Oracle Fusion Cloud HCM](https://docs.oracle.com/en/cloud/saas/human-resources/farws/index.html)
- [OAuth configuration for Fusion Applications](https://docs.oracle.com/en/cloud/saas/applications-common/25c/oaext/configure-oauth.html)
- [Oracle A-Team: Authenticating with Fusion v1 APIs](https://www.ateam-oracle.com/authenticate-and-work-with-fusion-v1-api-rest)

A developer guide to integrating with Oracle Fusion Cloud REST APIs. Covers authentication (basic auth, OAuth 2.0, JWT), API structure across ERP, HCM, SCM, and CX pillars, filtering, pagination, and when to use REST vs FBDI vs BICC vs business events.

How to Integrate With the Oracle Fusion Cloud API

Campfire is an AI-native ERP for high-growth startups and mid-market companies. This guide covers integrating directly with the Campfire API and using a unified API like Apideck to connect to Campfire and 30+ other accounting platforms through a single integration.

How to Integrate With the Campfire API

## 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:

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

```python
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.

```python
# 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.

```python
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.

```python
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.

```python
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:

```python
# 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:

```python
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:

```python
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.

```python
# 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:

```python
# 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`

```python
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:

```python
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:

```javascript
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:

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

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

```http
X-Odoo-Database: your_database_name
```

### Reading Records (GET)

```python
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)

```python
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:

```python
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:

```python
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`:

```python
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:

```python
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:

```python
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:

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

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

```python
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](https://www.apideck.com/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](https://www.apideck.com/integrations/odoo) 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.

A practical guide to integrating with Odoo's API — covering authentication, core methods, accounting models (invoices, payments, chart of accounts), pagination, version handling, and webhooks.

How to Integrate with the Odoo API

> **Disclaimer:** Apideck does not currently support Horus Office as a connector yet. This guide is published for informational purposes to help developers who are building a direct integration with the Horus API.

# How to Integrate with the Horus Software API

*A practical guide for developers building integrations with Horus Office*

[Horus Office](https://www.horussoftware.be/nl/) is an accounting and business management platform used by fiduciaries and SMBs primarily in Belgium and Luxembourg. Its API gives developers programmatic access to folders, companies, book entries, invoices, account histories, and more, making it possible to build tight integrations between your application and your clients' accounting data.

If you are looking to connect multiple accounting platforms through a single, unified interface, Apideck provides a unified accounting API with connectors for dozens of platforms. But if Horus Office is your specific target, read on — this guide covers everything you need.

We will walk through registering your integration, completing the OAuth 2 authorization flow, understanding the API's request and response conventions, and working with the key resources available.

## 1. Getting Started: Registering Your Integration

The Horus API uses OAuth 2, and before any of that can happen you need to register your integration. Unlike APIs that offer instant self-service sign-up, Horus requires a registration request by email to:

**developer@horus-software.be**

Use the subject line "New Api Integration Request" and include:

- The name of your integration
- A contact person and their email address
- A short description of how and why you intend to use the API
- Your redirect URL(s) that will be used in the OAuth flow

Once approved, you will receive a `client_id` and a `client_secret`. Keep the `client_secret` server-side at all times — never expose it in client-side code, mobile apps, or public repositories.

> **Key concept:** Each fiduciary or SMB running Horus Office has its own dedicated database with its own API endpoint. Your client credentials work across all of them, but the per-user API endpoint is only revealed during the OAuth flow.

## 2. Authentication: The OAuth 2 Flow

Horus uses the standard authorization code flow. Here is the full sequence.

### Step 1: Redirect the user to the authorization page

Send the user to the Horus authorization endpoint. This always starts at the central `my-horus.com` domain regardless of which client they are connecting:

```
https://my-horus.com/fr/api/oauth2/authorize
  ?client_id=ck_5ekn8gsdr4h95fa
  &response_type=code
  &state=random_unique_string
  &redirect_uri=https://your-app.com/oauth/callback
```

The `state` parameter is optional but recommended as a CSRF protection measure. The user will log in, select which license (company database) to connect, and grant access to your integration.

### Step 2: Handle the redirect callback

If the user approves, Horus redirects back to your `redirect_uri` with three query parameters:

- `code` — the short-lived authorization code
- `state` — echoed back if you sent one
- `api_url` — the specific API endpoint for this user's license

```
https://your-app.com/oauth/callback
  ?code=Hjhfn45k
  &state=random_unique_string
  &api_url=https://horusapi.myfiduciary.com
```

Store the `api_url`. Every subsequent API call for this user must go to their specific endpoint. If the user denies access, the redirect instead includes an `error=access_denied` parameter.

> **Important:** The authorization code is valid for only 2 minutes. Exchange it for an access token immediately.

### Step 3: Exchange the code for an access token

POST to the `oauth2/access_token` path at the `api_url` you just received:

```bash
curl -X POST https://horusapi.myfiduciary.com/oauth2/access_token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=ck_XXXX' \
  -d 'client_secret=cs_XXXX' \
  -d 'code=Hjhfn45k' \
  -d 'grant_type=auth_code' \
  -d 'redirect_uri=https://your-app.com/oauth/callback'
```

The response is a standard Bearer token payload:

```json
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "h4vtwzwlfip68zx...",
  "refresh_token": "r3fr3sh..."
}
```

Attach the access token to subsequent requests using the Authorization header:

```
Authorization: Bearer h4vtwzwlfip68zx...
```

### Step 4: Refreshing the access token

Access tokens expire after 1 hour. Use the refresh token to get a new pair without requiring the user to re-authorize. Refresh tokens are single-use — each refresh issues a fresh pair.

```bash
curl -X POST https://horusapi.myfiduciary.com/oauth2/access_token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=ck_XXXX' \
  -d 'client_secret=cs_XXXX' \
  -d 'refresh_token=r3fr3sh...' \
  -d 'grant_type=refresh_token'
```

Refresh tokens remain valid until the user revokes them or uninstalls your integration.

## 3. API Conventions

### Endpoint format

The API uses a JSON-RPC-style naming convention. Endpoints follow the pattern:

```
https://{api_url}/RESOURCE.ACTION
```

For example: `/folders.list`, `/companies.info`, `/invoices.sales.new`. All requests must use HTTPS.

### GET vs POST

- Simple reads use GET with query parameters (e.g., `/users.me`, `/folders.info?Id=...`)
- Filtered or complex reads use POST with a JSON body (e.g., `/companies.list`, `/book-entries.list`)
- All create and update operations use POST with a JSON body

For POST requests, set the `Content-Type` header to `application/json`. URL-encoded form data is also accepted but JSON is strongly recommended, especially for nested structures like invoice lines.

### Response structure

All successful read responses wrap their payload in a top-level `Data` field:

```json
{
  "Data": {
    "Id": "14feb291-8b47-44c6-8cbb-97a3f24c33c8",
    "FirstName": "Robert",
    "LastName": "Doe",
    "IsAccountant": true
  }
}
```

Create and update operations return only the `Id` of the affected entity:

```json
{
  "Id": "14feb291-8b47-44c6-8cbb-97a3f24c33c8"
}
```

### Error handling

Non-authorization errors return a structured object with three fields:

```json
{
  "ErrorType": "not_found",
  "Details": "The requested book entry was not found.",
  "Message": "Element was not found"
}
```

Standard HTTP status codes used:

| Code | Meaning |
|------|---------|
| 200 | OK |
| 400 | Bad Request — invalid data or reference to a non-existing resource |
| 401 | Unauthorized — invalid, expired, or missing access token |
| 403 | Forbidden — the user is not allowed to access this resource |
| 404 | Not Found |
| 500 | Internal Server Error |

### Gzip compression

All endpoints support Gzip. Add a `Content-Encoding: gzip` header to your request and responses will be compressed automatically, which makes a noticeable difference on larger listing responses.

## 4. Sideloading Related Data

Sideloading lets you fetch related entities as part of a single request, avoiding extra round trips. For example, when listing book entries you can also pull the associated company in one call.

To sideload a relationship, add an `Include` parameter to your POST body using dot notation:

```json
{
  "FolderId": "83f26e75-f474-4b09-a1d3-aa698e18fbf0",
  "Include": "CompanyDetail.Company"
}
```

Sideloaded data comes back in a separate `Included` section, keyed by type. Multiple relationships can be sideloaded at once using comma separation: `"Include": "CompanyDetail.Company,Daybook,Folder"`

Sideloading is supported on: `book-entries.list`, `account-histories.list`, `companies.list`, and `invoices.sales.outstanding.list`.

![Horus API Docs](//images.ctfassets.net/d6o5ai4eeewt/6dapInxP5bd9a3FX2QpxQK/5d2ef2f3f9ac309c8036e42cecdcf059/Screenshot_2026-03-12_at_22.49.42.png)

## 5. Key Resources

### Licenses and Users

After authentication, your first calls establish context: which license is connected and who the authenticated user is.

- GET `/licenses.me` — Get the license for the authenticated user
- GET `/licenses.main` — Get the fiduciary's main license
- GET `/users.me` — Get the current authenticated user
- GET `/users.list` — List all users on this license
- GET `/users.info` — Get a specific user by Id

### Folders

A folder represents a company's accounting configuration. Fiduciaries manage many folders, one per client company. Most subsequent API calls require a `FolderId`.

- POST `/folders.list` — List folders (filter by name, VAT number, legislation, etc.)
- GET `/folders.info` — Get details for a specific folder

When listing folders, pass a `Mode` parameter: `0` for all accessible folders, `1` for folders you are responsible for.

### Companies

Companies are the legal entities associated with a folder — customers, suppliers, or beneficiaries. They hold VAT numbers, IBAN details, payment modes, and contact information.

- POST `/companies.list` — List companies with rich filtering
- GET `/companies.info` — Get a specific company by Id
- POST `/companies.new` — Create a new company
- POST `/companies.update` — Update an existing company

Note the naming convention: creation uses `.new`, not `.create`. This is consistent across all writable endpoints in the API.

### Book Entries

Book entries are the core accounting records. There is no single generic `/book-entries.create` endpoint — each entry type has its own endpoint:

- POST `/book-entries.list` — List book entries (sideloading supported)
- GET `/book-entries.info` — Get a specific book entry
- POST `/invoices.purchases.new` — Create a purchase invoice
- POST `/invoices.sales.new` — Create a sales invoice
- POST `/book-entries.banks.new` — Create a bank entry
- POST `/book-entries.financials.new` — Create a financial/credit card entry
- POST `/book-entries.miscellaneous-operations.new` — Create a miscellaneous operation

### Invoices

- POST `/invoices.sales.new` — Create a sales invoice
- POST `/invoices.sales.update` — Update a sales invoice
- POST `/invoices.sales.outstanding.list` — List open sales invoices with payment status
- POST `/invoices.purchases.new` — Create a purchase invoice
- POST `/invoices.purchases.update` — Update a purchase invoice

Both new endpoints accept optional attached documents. Use `multipart/form-data` with a `file` part and a `body` part (JSON) when attaching a PDF.

### Account Histories and Matching

Account histories track individual debit and credit movements. The matching endpoints let you reconcile open items.

- POST `/account-histories.list` — List account history entries (sideloading supported)
- GET `/account-histories.info` — Get a specific account history entry
- GET `/matching.next-number.customer` — Get the next available match number
- POST `/matching` — Match a set of account history entries

## 6. A Practical Integration Walkthrough

Here is a typical sequence for building a read-only sync:

1. Complete the OAuth flow and store the `api_url` and `refresh_token` securely, indexed by user.
2. Call `/users.me` and `/licenses.me` to establish context.
3. Call `/folders.list` to retrieve all folders the user has access to. Store folder IDs.
4. For each folder, call `/companies.list` to sync company records. Use `ModifiedAfter` on subsequent syncs.
5. Pull `/book-entries.list` with sideloading to get enriched transaction data. Or use `/invoices.sales.outstanding.list` to focus on open receivables.
6. Implement a background token refresh job. Access tokens expire after 1 hour; refresh proactively rather than waiting for a 401.

If you are building this pattern across multiple accounting platforms, [Apideck's accounting API](https://www.apideck.com/accounting) normalises these concepts into a single unified schema, so you write the integration once and connect to Horus, QuickBooks, Xero, and others through one interface.

## 7. Tips and Best Practices

- Store both the `access_token` and `api_url` per user. The `api_url` is permanent for a given license.
- Implement proactive token refresh. Tokens expire after 1 hour; do not wait for a 401 to find out.
- Use Gzip compression on all requests. Large listing responses compress significantly.
- Prefer JSON request bodies over URL-encoded, especially for nested structures like invoice lines.
- Use `ModifiedAfter` filters when syncing large datasets incrementally.
- Leverage sideloading to reduce round trips.
- The API is backwards-compatible by design: new optional fields and endpoints are non-breaking. Breaking changes are communicated by email in advance.

## Wrapping Up

The Horus Software API covers the full breadth of accounting operations: reading and writing folders, companies, book entries, invoices, account histories, and matching. The OAuth 2 flow with per-license API endpoints is the most unusual aspect initially, but once that is in place the rest follows consistent conventions.

For questions or to register your integration, reach out to developer@horus-software.be. The full API reference is available at horussoftwareapi.docs.apiary.io.

If your product needs to connect to multiple accounting platforms beyond Horus, [Apideck](https://www.apideck.com) offers a unified accounting API that normalises data from Horus, QuickBooks, Xero, Sage, and many others into a single integration.

A practical guide for developers building integrations with Horus Office. Covers OAuth 2 registration, authentication flow, API conventions, sideloading, and all key resources including folders, companies, book entries, invoices, and account histories.

How to Integrate with the Horus Software API

When integrating with HRIS platforms through Apideck, different connectors have varying partnership requirements. Understanding these requirements is essential for planning your integration timeline and ensuring compliance with each platform's developer policies.

This guide categorizes our HRIS connectors into three groups based on their partnership requirements, helping you understand what's needed before going live with each integration.

## Partnership Categories

### 🔴 Partnership Required

These platforms require the customer to register an OAuth app or developer account with the third-party service and enter the resulting credentials (Client ID, Client Secret, etc.) in the Apideck dashboard. Some also require the end-user to create or obtain credentials before connecting. Examples include Google Workspace, Factorial, and Okta.

### 🔵 Partnership Optional (Apideck Credentials Available)

For these connectors, Apideck has already established OAuth credentials that you can use. This means you can start integrating immediately without registering your own app with the third-party service. However, when your users authenticate, Apideck will be shown as the application requesting access. You may optionally register your own app if you prefer your own branding during the OAuth consent flow. Examples include Deel, Employment Hero, and Microsoft Dynamics 365 HR.

### 🟢 No Partnership Required

These connectors use API key, basic auth, custom authentication, or consumer-provided OAuth credentials — meaning there is no OAuth app registration needed on the customer side. Your end-users authenticate directly with their own credentials (API key, username/password, service user token, or consumer-provided OAuth credentials). Examples include BambooHR, HiBob, SAP SuccessFactors, and Personio.

## Connector Partnership Matrix

The table below provides a complete overview of partnership requirements, availability of partner introductions, associated fees, and links to documentation for each connector.

## 🔴 Partnership Required

| Connector | Partner Signup | Partner Intro | Partner Fee |
|-----------|---------------|---------------|-------------|
| **Microsoft Entra** | [azuremarketplace.microsoft.com](https://azuremarketplace.microsoft.com/en-us/sell) | Self-Serve | None. Register app in Azure portal. |
| **Google Workspace** | [partners.cloud.google.com](https://partners.cloud.google.com/) | Self-Serve | None. Create OAuth credentials in Google Cloud Console. |
| **ADP (iHCM & Workforce Now)** | [partners.adp.com](https://partners.adp.com) | Self-Serve | Partnership fees apply. Security review and Developer Participation Agreement (DPA) required. |
| **PayFit** | [payfit.com/partnerships](https://payfit.com/partnerships/) | Self-Serve | None |
| **Factorial** | [factorialhr.com](https://factorialhr.com/integrations-partner-program) | Available | None. Register OAuth app in developer portal. |
| **Rippling** | [rippling.com](https://www.rippling.com/en-GB/partners/technology-partners) | Self-Serve | None |
| **Gusto** | [gusto.com](https://dev.gusto.com/) | Self-Serve | None |
| **Liantis** | Contact Apideck | Available | Integration fees apply |
| **SD Worx** | Via email intro only | Available | Partnership fees may apply |
| **Okta** | [developer.okta.com](https://developer.okta.com/signup/) | Available | None. Register app in Okta developer portal. |
| **Namely** | [namely.com/partners](https://www.namely.com/partners/) | Self-Serve | N/A |
| **Loket.nl** | [loket.nl](https://www.loket.nl/koppelen-met-loket/) | Available | N/A |

## 🔵 Partnership Optional - Apideck Credentials Available

| Connector | Partner Signup | Partner Intro | Partner Fee |
|-----------|---------------|---------------|-------------|
| **Deel** | [deel.com/partner-program](https://www.deel.com/partner-program) (optional) | Available | None with Apideck credentials |
| **Employment Hero** | [employmenthero.com](https://employmenthero.com/partner-network/technology-integrations/) (optional) | Self-Serve | None with Apideck credentials |
| **Zoho People** | [zoho.com](https://www.zoho.com/partners/partner-signup.html) (optional) | Self-Serve | None with Apideck credentials |
| **Visma Nmbrs** | [appstore.nmbrs.com](https://appstore.nmbrs.com/partner/request) (optional) | Available | None with Apideck credentials |
| **Officient** | [officient.io](https://en.officient.io/partners) (optional) | Available | None with Apideck credentials |
| **Microsoft Dynamics 365 HR** | [developer.microsoft.com](https://developer.microsoft.com) (optional) | Self-Serve | None with Apideck credentials |

**⚠️ Important:** When using Apideck's partner credentials (blue category), the OAuth consent screen will display "Apideck" as the application requesting access to your users' data. If white-labeling or custom branding is important for your use case, you should register for your own OAuth app with the connector.

## 🟢 No Partnership Required

| Connector | Partner Intro | Partner Signup |
|-----------|---------------|----------------|
| **SAP SuccessFactors** | Self-Serve | [sap.com](https://www.sap.com/partners/partner-program.html) (optional) |
| **Workday** | Available | [workday.com](https://www.workday.com/en-us/company/partners/partner-program-overview.html) (optional) |
| **HiBob** | Available | [hibob.com/partner](https://www.hibob.com/partner/) (optional) |
| **BambooHR** | Self-Serve | [partners.bamboohr.com](https://partners.bamboohr.com/apps-marketplace-program/) (optional) |
| **TriNet** | Self-Serve | [developers.trinet.com](https://developers.trinet.com/accounts/create) (optional) |
| **People HR** | Available | [peoplehr.com](https://www.peoplehr.com/en-gb/integrations/) (optional) |
| **CharlieHR** | Available | Contact CharlieHR (optional) |
| **IRIS Cascade HR** | Self-Serve | [iris.co.uk](https://www.iris.co.uk/partner-program/) (optional) |
| **Personio** | Available | [personio.com/partner/tech](https://www.personio.com/partner/tech/) (optional) |
| **Breathe HR** | Self-Serve | [breathehr.com](https://www.breathehr.com/en-gb/partners) (optional) |
| **UKG Pro** | Self-Serve | [ukg.com](https://www.ukg.com/become-a-ukg-partner) (optional) |
| **AFAS Software** | Available | [partner.afas.nl](https://partner.afas.nl/aanmelden) (optional) |
| **CatalystOne** | Self-Serve | [catalystone.com](https://www.catalystone.com/technology-and-services/implementation-partners/) (optional) |
| **HR Works** | Available | N/A |
| **Cezanne HR** | Self-Serve | [cezannehr.com/partners](https://cezannehr.com/partners/) (optional) |
| **Sympa** | Available | [sympa.com](https://www.sympa.com/product/partner-programme/) (optional) |
| **Paylocity** | Self-Serve | [paylocity.com](https://www.paylocity.com/our-products/integrations/marketplace/) (optional) |
| **Humaans** | Available | [humaans.io/partner](https://humaans.io/partner) (optional) |
| **Sage HR** | Available | [sage.com](https://www.sage.com/en-us/partners/) (optional) |
| **Homerun HR** | Available | N/A |
| **CIPHR** | Self-Serve | [ciphr.com/partners](https://www.ciphr.com/partners) (optional) |
| **Lucca** | Available | [lucca-hr.com](https://www.lucca-hr.com/partnership/) (optional) |
| **Simployer One** | Available | N/A |
| **Dayforce** | Self-Serve | [dayforce.com](https://www.dayforce.com/how-we-help/services-and-support/partners/software-and-technology) (optional) |
| **Folks HR** | Self-Serve | N/A |
| **Acerta** | Available | N/A |
| **JumpCloud** | Self-Serve | [jumpcloud.com/partners](https://jumpcloud.com/partners/apply) (optional) |
| **OneLogin** | Self-Serve | N/A |
| **Kenjo** | Self-Serve | [kenjo.io](https://www.kenjo.io/partner-program-kenjo) (optional) |
| **Paychex** | Self-Serve | [developer.paychex.com](https://developer.paychex.com/partner) (optional) |
| **Keka** | Self-Serve | N/A |
| **Fourth** | Self-Serve | N/A |
| **Cegid Talentsoft** | Self-Serve | [partners.cegid.com](https://partners.cegid.com/English/) (optional) |
| **Sapling by Kallidus** | Self-Serve | [kallidus.com](https://www.kallidus.com/landing/partners/) (optional) |
| **Remote** | Available | [developer.remote.com](https://developer.remote.com/) (optional) |

*\* Green connectors require no customer-side setup in the Apideck dashboard. End-users authenticate directly with credentials from their own account on the platform.*

## Getting Started

### For Connectors Requiring Partnership (Red)

1. Review the partner signup link in the matrix above for your target connector.
2. Register an OAuth app or complete the partner registration process with the HRIS provider.
3. Obtain your API credentials (Client ID, Client Secret, etc.).
4. Configure your credentials in the Apideck dashboard under Connector Settings.
5. Follow the Connector Config Guide to complete your setup.

### For Connectors with Apideck Credentials (Blue)

1. Enable the connector in your Apideck dashboard — no additional setup required.
2. Your users will see "Apideck" during the OAuth flow when connecting their accounts.
3. (Optional) Register your own OAuth app for custom branding on the consent screen.

### For Connectors with No Partnership Required (Green)

1. Enable the connector in your Apideck dashboard.
2. Your end-users authenticate using their own credentials (API key, username/password, or service user token) from the platform.
3. No customer-side configuration or partner registration is needed.

## Partner Introduction Program

For connectors where partner introductions are available, Apideck can facilitate an introduction to the platform's partnership team. This can help expedite your application process and ensure you're connected with the right contacts. Reach out to your Apideck account manager or contact partners@apideck.com to request an introduction.

## Need Help?

If you have questions about partnership requirements or need assistance with connector configuration, our team is here to help:

**Documentation:** [https://developers.apideck.com/](https://developers.apideck.com/)

**Support:** support@apideck.com

**Partnerships:** partners@apideck.com

Learn which HRIS integrations require partnerships vs. ready-to-use connectors. Complete guide to Apideck's 60+ HRIS API partnership requirements, fees, and setup details.

We could not find that page

An error occurred.