DEV Community: Kate Apideck

How to Integrate with the MYOB API

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

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

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

What is the MYOB Business API?

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

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

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

Why integrate with MYOB?

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

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

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

Registration and API keys

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

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

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

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

Authentication: the March 2025 changes

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

New granular scopes

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

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

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

Admin-only authorization

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

Company file GUID retrieval

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

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

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

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

Token lifecycle

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

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

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

Store tokens securely and never log them.

Key API endpoints

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

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

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

Contacts

Contacts cover customers, suppliers, and employees.

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

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

Sales

Sales endpoints handle customer-facing transactions.

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

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

Purchases

Purchase endpoints mirror the sales structure for supplier transactions.

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

General Ledger

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

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

Inventory

Inventory endpoints manage products and stock.

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

Request headers and versioning

The API requires specific headers for all requests:

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

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

For cloud files, include the company file token:

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

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

Data mapping considerations

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

Invoice structure

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

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

Tax codes

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

Account mapping

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

Currency

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

Error handling and rate limits

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

Error responses include JSON with error codes and messages:

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

Rate limiting

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

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

OData filtering

The API supports OData query parameters for filtering results:

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

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

Deprecation: AccountRight Classic

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

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

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

Testing your integration

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

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

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

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

Unified API approach

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

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

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

Frequently asked questions

Can I access multiple company files with one integration?

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

Does MYOB support webhooks?

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

What happens when AccountRight releases a new version?

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

Can I email invoices through the API?

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

What's the difference between AccountRight and MYOB Business?

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

Next steps

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

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

For more on building accounting integrations, see:

How to Integrate with the Odoo API

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

How Odoo's API Works

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

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

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

Authentication

Odoo uses a two-step authentication process:

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

import xmlrpc.client

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

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

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

A few things worth noting:

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

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

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

Core API Methods

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

`search_read`

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

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

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

`create`

Creates one record and returns its ID.

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

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

`write`

Updates one or more records.

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

`unlink`

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

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

`execute_kw` with custom methods

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

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

Accounting Module: Key Models

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

Invoices and Bills — `account.move`

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

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

Key fields to know:

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

Invoice Lines — `account.move.line`

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

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

Payments — `account.payment`

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

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

To register a payment against a specific invoice:

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

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

Chart of Accounts — `account.account`

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

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

Contacts — `res.partner`

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

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

Working with the JSON-RPC Interface

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

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

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

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

Working with the Native REST API (Odoo 17+)

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

Authentication

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

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

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

X-Odoo-Database: your_database_name

Reading Records (GET)

import requests

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

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

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

invoices = response.json()

Creating Records (POST)

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

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

Calling Methods

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

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

The JSON-2 API (Odoo 19+)

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

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

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

Pagination and Performance

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

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

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

        if not batch:
            break

        all_invoices.extend(batch)
        offset += batch_size

    return all_invoices

A few performance tips:

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

Handling Odoo Versions

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

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

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

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

You can check the server version via:

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

Error Handling

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

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

Common error patterns:

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

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

Webhooks and Real-time Sync

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

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

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

from datetime import datetime, timedelta

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

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

Using a Unified API Instead

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

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

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

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

Wrapping Up

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

The main things to keep in mind as you build:

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

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

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

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

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

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

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

The full picture: types of financial statements

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

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

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

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

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

Why the gaps exist

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

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

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

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

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

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

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

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

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

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

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

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

Real use cases that depend on clean financial statement data

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

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

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

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

Building it yourself vs. using a unified API

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

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

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

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

import { Apideck } from '@apideck/unify'

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

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

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

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

What to evaluate in a financial statement API provider

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

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

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

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

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

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

Where this is heading

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

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

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

How to Integrate With the Pennylane API

Kate Apideck — Mon, 29 Jun 2026 11:05:57 +0000

Pennylane is a financial management and accounting platform built for SMEs and accounting firms in France. It handles everything from invoice creation to VAT declarations, and its API lets you programmatically connect your own software to that accounting backbone. As one of the top accounting APIs gaining traction in the European market, it's worth understanding how it works under the hood.

If you're building a product that touches invoicing, payments, or financial data for the French market, connecting to Pennylane is increasingly a requirement. Here's what you need to know to get started.

What the API covers

Pennylane exposes two separate APIs depending on your use case:

The Company API is designed for businesses that want to automate their own accounting workflows. Think: pushing invoices from your billing system into Pennylane, syncing supplier invoices, or creating ledger entries automatically. This falls squarely into the open accounting trend, where financial data flows freely between systems via APIs rather than manual exports.

The Firm API is for accounting firms managing multiple client companies. It provides access to client accounting data like trial balances, FEC exports, general ledgers, fiscal years, and client records.

Both APIs are now on v2, which is the official stable version. The v1 API has been deprecated, and Pennylane originally targeted end of 2025 for full removal. If you're starting a new integration, go straight to v2 as v1 will not receive any new features.

In terms of what you can actually build, the v2 API supports:

Creating and importing customer invoices (both from structured data and from PDF)
Importing supplier invoices
Managing quotes, billing subscriptions, and commercial documents (purchase orders, proformas)
Creating and reading ledger entries with analytical tags
Creating and retrieving banking transactions
Uploading file attachments (required for PDF-based invoice imports)
Payment matching and reconciliation
Tracking data changes via changelog endpoints for near real-time sync
Managing customers, suppliers, products, and ledger accounts
Importing Factur-X e-invoices (relevant for the upcoming French e-invoicing reform)

A few things are not natively supported yet. Downpayment invoices can be created as a workaround by importing an invoice line with ledger account 4191, though they won't display as a downpayment in the Pennylane UI. Delivery notes are not available through the API.

Authentication

There are three authentication paths depending on who you are:

Company API tokens can be generated directly in Pennylane account settings. You need admin access (Executive, Internal Accountant, or External Accountant role). You can create multiple tokens per company, each with their own scopes and expiration settings. Tokens are not stored by Pennylane and can't be retrieved after creation, so store them securely on your side.

Firm API tokens are generated from Firm account settings and give access to client data across the firm's portfolio.

OAuth 2.0 is required for any integration that will be published on the Pennylane Marketplace or used across multiple companies. You'll need to contact integrations@pennylane.com to get registered. Access tokens expire after 24 hours by default, and refresh tokens are valid for 90 days. Once a refresh token is used, it's revoked and replaced with a new one, so make sure your token rotation logic handles this properly. (This is one of the areas where building vs buying accounting integrations becomes a real trade-off, since a unified API can handle token management for you.)

All requests use Bearer token authentication in the Authorization header:

Authorization: Bearer <YOUR_API_KEY_OR_OAUTH_TOKEN>

The base URL for v2 endpoints is:

https://app.pennylane.com/api/external/v2/

Setting up a sandbox

Before hitting production, you'll want a sandbox environment. For companies, you can create one directly from your Pennylane account by navigating to your profile and selecting "Test environment." For firms, you use your existing Firm account (no sandbox needed). Integrators need to email integrations@pennylane.com with their name and email for sandbox creation.

The sandbox mirrors the production environment so you can test your full integration flow without affecting real data. If you plan to test invoicing, you'll also need to configure your invoice settings (company address, bank details, logo, and sequential numbering).

Making your first request

Start by verifying your credentials work:

curl https://app.pennylane.com/api/external/v2/me \
  -H "Authorization: Bearer <YOUR_TOKEN>"

A successful response returns your user and company context, confirming authentication is working and you're hitting the right environment.

Working with invoices

Invoicing is the most common accounting integration use case, and Pennylane distinguishes between two approaches:

Creating an invoice means Pennylane generates the invoice document from structured data you provide (customer ID, line items, VAT rates, amounts). This is the right path when your system is the source of truth for what should be on the invoice.

Importing an invoice means you're pushing a pre-existing PDF into Pennylane. This requires a two-step process in v2: first upload the PDF via the /file_attachments endpoint to get an attachment ID, then use that ID when calling the import endpoint. Only PDF files are accepted, up to 100 MB.

Here's the general flow for creating a customer invoice:

Look up or create the customer via /customers or /company_customers
Optionally look up products via /products for consistent pricing and VAT handling
Optionally look up ledger accounts via /ledger_accounts if you need specific account mappings
POST to /customer_invoices with the customer ID, line items, dates, and VAT rates

You can create invoices in draft mode by passing "draft": true, which is useful for review workflows before finalization. You can also convert a quote into an invoice directly via /customer_invoices/create_from_quote.

One important detail: customer, product, and ledger account IDs are unique per company. If your integration serves multiple Pennylane companies, you need to store these mappings per tenant.

Pagination and filtering

The v2 API uses cursor-based pagination instead of the offset-based pagination from v1. This is a meaningful change if you're migrating. Pennylane has a dedicated guide on implementing cursor-based pagination correctly.

For filtering, the API uses a structured filter parameter in query strings. Filters follow a JSON format specifying the field, operator, and value:

?filter=[{"field":"external_reference","operator":"eq","value":"ACME_001"}]

Filtering is available on most list endpoints, including customer invoices, supplier invoices, draft invoices, credit notes, customers, suppliers, ledger accounts, ledger entries, ledger entry lines, products, and categories.

Tracking changes

The changelog endpoints are particularly useful for keeping your system in sync with Pennylane. They let you poll for creation, update, and deletion events on specific resources in near real-time. Currently supported for customer invoices and supplier invoices.

When you receive change events, you'll need to make a follow-up request to fetch the complete resource data, since the changelog only tells you what changed, not the full payload.

Rate limits

The v2 API allows up to 5 requests per second. Rate limiting applies on both production and sandbox environments across all endpoints. If you exceed the limit, you'll receive a 429 HTTP error.

If you're processing high volumes (nightly invoice syncs, historical imports), you'll need proper queuing and retry logic with exponential backoff to handle 429 responses gracefully. This is a common challenge across accounting API integrations for fintech products. Also worth noting: Pennylane does not enforce idempotency on creation endpoints like /customer_invoices or /ledger_entries, so duplicate requests will create duplicate records. Build deduplication logic on your side.

Key differences from v1

If you're migrating from v1, a few structural changes to be aware of:

Internal IDs only. V2 uses Pennylane's internal IDs exclusively. You can no longer retrieve resources by source_id. To help with migration, v1 responses include a v2_id attribute so you can map old IDs to new ones.

Granular scopes. V2 introduces more specific OAuth scopes, each with a readonly counterpart. You'll need to update your OAuth app configuration and re-authenticate to use v2 endpoints.

Single-resource creation. V1 allowed creating multiple object types in a single call. V2 requires separate calls through dedicated endpoints, which simplifies error handling and debugging.

File attachments as resources. In v1, you could inline base64 file content or a URL directly in an invoice import call. In v2, file attachments are a separate resource that you create first and then reference by ID.

Linked collections. Where v1 returned nested arrays (like invoice lines inside an invoice), v2 returns a URL pointing to the collection endpoint instead.

Standardized response bodies. In v2, a data model like customer_invoice always returns the same response attributes regardless of whether you're hitting the show or list endpoint.

Practical tips

Store IDs per tenant. If your integration serves multiple companies, maintain a mapping of Pennylane IDs (customers, products, ledger accounts) for each company.

Use external references. When creating customers or other entities, populate the external_reference field with your own system's ID. This makes lookups much easier later.

Default VAT and ledger mappings. If you omit the ledger_account_id when creating invoices, Pennylane applies the company's default chart of accounts and VAT settings. This can simplify your integration if you don't need fine-grained control over accounting mappings.

Monitor the changelog. Pennylane's API evolves frequently with new endpoints and deprecations. Subscribe to their API changelog RSS feed to stay ahead of breaking changes.

Plan for role and plan requirements. End users need at least a "gestionnaire" (manager) role and an Essential plan or higher to activate API integrations. Surface clear error messages if users lack the required permissions.

Validate before you send. Check totals and VAT consistency on your side before making API calls. Pennylane returns detailed error payloads with a details object that tells you exactly which field caused the failure, but catching issues client-side saves round trips.

Using a unified API instead

If you're building integrations across multiple accounting platforms and not just Pennylane, building and maintaining direct integrations with each one adds up quickly. Each platform has its own authentication flows, data models, rate limits, and breaking changes to track. For a deeper look at this trade-off, see our guide on how fintech startups can integrate with 20+ accounting platforms using a single API.

Apideck's Unified Accounting API supports Pennylane as a native connector alongside QuickBooks, Xero, Sage, NetSuite, and 45+ other accounting platforms through a single integration. The Pennylane connector covers 15+ normalized data models, including customers, suppliers, invoices, bills, ledger accounts, tax rates, products, ledger entries, transactions, quotes, and bank accounts. Authentication is handled via OAuth 2.0 with automatic token refresh, and real-time webhooks keep your data in sync without polling.

This is especially relevant if your product needs to support both French and international accounting systems. Instead of managing Pennylane's OAuth token rotation, Xero's partner certification process, and QuickBooks' different API versions separately, a unified API platform gives you one integration point, one data schema, and one set of SDKs across all of them. Check the full list of accounting connectors to see what's available.

Resources

12 Best Practices for Accounting Integrations in Vertical SaaS

Kate Apideck — Fri, 26 Jun 2026 11:26:46 +0000

Accounting integrations fail not because accounting is complex, but because teams underestimate domain-specific workflows, platform differences, and long-term maintenance costs. The result is rework, data drift, and engineering resources permanently diverted from core product development.

This article documents where vertical SaaS accounting integrations commonly break and the engineering patterns that prevent these failures.

1. Start From Industry Workflows, Not the Ledger

The most common mistake is modeling integrations around generic general ledger objects, such as accounts, journals, and invoices, instead of the domain language your customers actually use.

Construction companies think in job costing and progress billing. Agencies operate on retainers and time-based billing. Marketplaces handle revenue sharing and payouts. Healthcare practices deal with insurance reconciliation and patient billing cycles. Each vertical moves money differently, and your integration needs to reflect that.

When you build around generic GL concepts, you force users to mentally translate between their workflow and accounting primitives. The result is poor UX, low adoption, and constant support requests.

What to do instead:

Map integrations to real workflows first. If your construction SaaS tracks job costs, the integration should sync job cost data, not just raw journal entries.
Define the source of truth per object. Your system might own contracts and billing schedules while the accounting platform owns account balances and tax filings.
Document edit authority across systems. Specify which fields can be modified where, and what happens when conflicts occur.

2. Narrow the First Use Case

Full ledger sync sounds impressive in a product demo. In practice, it fails.

Teams that try to replicate an entire accounting system in v1 encounter edge cases that derail the project: multi-currency transactions, prepayments, adjustments, voided invoices, partial payments, credit memos. Each one requires specific handling logic, and attempting all of them simultaneously means shipping nothing.

What to do instead:

Start with one value stream. For most vertical SaaS, this is approved invoices flowing to the ledger. That single flow delivers immediate value and establishes the integration pattern.
Validate mappings with real customer data before expanding scope. Your assumptions about how customers use their accounting system are probably wrong.
Add complexity incrementally based on actual usage. If 5% of customers use multi-currency, deprioritize it until you've nailed the core flow.

3. Respect Platform Differences

QuickBooks, Xero, NetSuite, Sage, and FreshBooks are not interchangeable. Treating them as such creates reconciliation nightmares.

Concrete examples of where platforms diverge:

Tax handling: QuickBooks Online requires tax codes on line items. Xero calculates tax at the invoice level. NetSuite supports tax groups and nexus rules.
Credit memos: Some platforms link credit memos to original invoices. Others treat them as standalone documents.
Payment application: The mechanics of applying payments to invoices differ significantly. Partial payments, overpayments, and unapplied cash all have platform-specific behaviors.
Chart of accounts: Account types, numbering schemes, and hierarchy support vary widely.

Naïve 1:1 field mappings produce data that technically syncs but doesn't reconcile.

What to do instead:

Design a normalized internal data model that captures the semantics your application needs.
Build explicit transformation logic per connector. Don't hide platform differences. Handle them.
Surface validation errors early and clearly. When a transaction can't be represented correctly in the target platform, tell the user before it becomes a reconciliation issue.

4. Use Robust Authentication and Tenant Isolation

OAuth failures are the leading cause of integration downtime. Token expiry, scope mismatches, revoked access, and tenant leakage create both operational problems and financial risk.

Common failure modes:

Tokens expire and the refresh mechanism fails silently. Sync stops, and no one notices until month-end close.
Scope changes during re-authentication reduce permissions. The integration has write access on Monday and read-only access on Tuesday.
Shared credential storage allows one tenant's token to access another tenant's data. This is a security incident waiting to happen.

What to do instead:

Implement OAuth 2.0 per provider with proper state management.
Isolate tokens per tenant and per connector. One customer's QuickBooks connection should have no relationship to another's.
Automate token refresh with monitoring. Alert when refresh fails, not when sync fails.
Request only the scopes you need and validate them on each authentication.

5. Design for Idempotency and Retry Safety

Network failures happen. API rate limits trigger. Timeouts occur. Your integration will retry operations, and those retries must be safe.

Financial side effects compound quickly. A duplicate invoice is annoying. A duplicate payment creates a real accounting discrepancy. Duplicate journal entries corrupt the ledger.

What to do instead:

Use idempotency keys on all write operations. Most accounting APIs support them, so use them consistently.
Maintain a mapping between your internal IDs and remote IDs. Before creating a new record, check if it already exists.
Process operations through a queue with exponential backoff. Don't retry immediately on failure.
Log enough context to diagnose retry failures. When an operation fails three times, you need to understand why.

6. Treat Webhooks as First-Class Infrastructure

Webhooks are how you learn about changes in the accounting system. Treating them as an afterthought causes data drift that's expensive to fix.

Problems that emerge:

Missed webhooks due to temporary downtime. Your system never learns about invoice updates.
Duplicate webhooks from provider retry logic. You process the same event twice.
Synchronous processing that blocks acknowledgment. The provider times out and retries, compounding the problem.

What to do instead:

Implement the verify-enqueue-acknowledge pattern. Validate the webhook signature, write it to a queue, return 200 immediately. Process asynchronously.
Deduplicate events using webhook IDs or event identifiers.
Build dead-letter queues for events that fail processing. Don't lose them.
Monitor event lag. If you're consistently behind, you have a scaling problem.

7. Build for Reconciliation and Auditability

Accountants care more about explainability than speed. They need to close books monthly, answer auditor questions, and trace every transaction to its source.

Black-box sync jobs that "just work" aren't good enough. When something doesn't reconcile, and something always doesn't reconcile, users need visibility.

What to do instead:

Implement per-transaction traceability. Every synced record should link back to its source in your system and its destination in the accounting platform.
Build sync status dashboards. Show what synced, what failed, and what's pending.
Maintain detailed logs with timestamps, payloads, and response codes. But set appropriate retention limits; you don't need raw payloads from three years ago.
Provide manual retry and skip controls. Sometimes the right answer is "don't sync this one."

8. Enforce Rigorous Data Validation

The worst place to discover a validation error is in a cryptic API response from the accounting platform. By that point, you've already confused the user, created a support ticket, and potentially left data in an inconsistent state.

Common validation failures:

Missing required fields that vary by platform configuration
Invalid account references (deleted accounts, wrong account types)
Date formats that don't match platform locale settings
Amount precision exceeding platform limits
Line item totals that don't sum to invoice totals

What to do instead:

Pre-validate against known ledger rules before sending data. Catch errors in your system, not theirs.
Provide human-readable error messages. "Invoice total must equal sum of line items" is useful. "422 Unprocessable Entity" is not.
Build validation guidance into your product UI. If an invoice won't sync because the customer record is incomplete, show that in the invoice editor.

9. Plan for Connector Sprawl and Maintenance

Building one accounting integration is a project. Maintaining ten is a product.

Long-term realities that teams underestimate:

API versioning and deprecation cycles. QuickBooks deprecated their v2 API. Xero has mandatory TLS requirements. NetSuite regularly updates their SOAP endpoints.
Authentication changes. OAuth scope requirements evolve. Token lifetimes change. New security requirements emerge.
Regional differences. UK VAT handling differs from US sales tax. Australian BAS reporting has specific requirements. Multi-entity support varies by platform and region.

Each connector becomes a maintenance liability that consumes engineering time indefinitely.

What to do instead:

Abstract integrations behind a single internal interface. Your application code shouldn't know whether it's talking to QuickBooks or Xero.
Reduce the blast radius of provider changes. When Xero updates their API, the fix should be isolated to one adapter.
Evaluate unified API platforms for connectors outside your core differentiation. Building and maintaining 15 accounting connectors is rarely the best use of engineering resources.

10. Align Integrations With Monetization

Accounting integrations often become cost centers: expensive to build, expensive to maintain, offered for free, and generating unlimited support tickets.

This is a product strategy failure, not a technical one.

What to do instead:

Package advanced integrations into premium tiers. Basic invoice sync might be included; multi-entity support, custom field mapping, and real-time sync can justify higher pricing.
Tie integrations to revenue-generating workflows. If the integration enables faster payment collection, capture some of that value.
Track integration usage and support costs. Know which integrations are worth maintaining and which are dragging down margins.
Treat integrations as product surface area. They deserve roadmaps, success metrics, and deprecation policies like any other feature.

11. Prioritize Security, Compliance, and Data Residency

Accounting integrations expand your attack surface and regulatory exposure. Financial data is sensitive, and the systems you're connecting to contain complete records of your customers' business operations.

Issues that surface late in development:

Data residency requirements. EU customers may require that their accounting data never touches US infrastructure.
Credential storage risks. Compromised OAuth tokens provide direct access to customer financial systems.
Audit requirements. SOC 2, PCI, and industry-specific frameworks all have implications for how you handle financial data.

What to do instead:

Encrypt data at rest and in transit. This is table stakes.
Implement role-based access controls. Not every employee needs access to integration credentials.
Minimize data retention. Sync what you need, don't cache what you don't.
Align with SOC 2 practices early. Retrofitting compliance is expensive.
Document your data flows. Know where financial data goes and how long it stays there.

12. Invest in Developer and Admin UX

Technically correct integrations that are painful to configure or debug don't get adopted. They generate support tickets, implementation delays, and churn.

UX problems that kill adoption:

Complex OAuth flows that confuse non-technical users
No visibility into sync status or errors
Mapping interfaces that require accounting expertise to configure
Missing sandbox or test modes

What to do instead:

Build clear onboarding flows. Guide users through connection, configuration, and initial sync.
Provide sandbox modes that connect to accounting platform sandbox environments. Let users test without risking production data.
Create admin tools for mapping and diagnostics. When something breaks, admins should be able to investigate without contacting support.
Write documentation that addresses real problems. Setup guides, troubleshooting steps, and mapping references.

Conclusion

These best practices align with open accounting principles — the idea that financial data should flow freely between systems through standardized APIs, enabling real-time visibility for all stakeholders.

Accounting integrations are infrastructure, not features. They require the same architectural rigor as your database layer or authentication system. The patterns outlined here, such as domain-driven design, incremental scope, platform abstraction, idempotency, and operational visibility, aren't novel. They're what distinguishes integrations that scale from integrations that become permanent maintenance burdens.

For teams that want to avoid building and maintaining dozens of direct accounting integrations, unified APIs like Apideck provide a standardized layer for authentication, normalized schemas, webhooks, and compliance. This allows engineering teams to focus on product logic instead of connector upkeep.

Xero Integrations: The Complete Guide to Integration with Xero (2026)

Kate Apideck — Thu, 25 Jun 2026 13:15:44 +0000

Integration with Xero is one of the most common requirements for SaaS products serving small and mid-sized businesses. Xero is cloud-based accounting software used by over 4.6 million subscribers across more than 180 countries. It dominates the SME market in the UK, Australia, and New Zealand, and is growing fast in the US. Its open API approach has made it one of the most integrated accounting platforms on the planet — with over 1,000 apps in its marketplace connecting to payroll, payments, eCommerce, CRM, expense management, and more.

This guide covers the most important Xero integrations by category, how they work, what to look for when choosing one, and — for product teams building a Xero integration into their own software — what it actually takes to build one.

The Xero App Marketplace

The Xero App Marketplace is Xero's official directory of third-party software that integrates with Xero. It's where businesses go to extend what Xero does — adding tools for payroll, inventory, payments, reporting, time tracking, and more — and where SaaS companies list their products to reach Xero's global customer base.

As of 2026, the marketplace hosts over 1,000 apps across more than 30 categories. Listings are organized by use case, industry, and region, making it relatively easy for a small business owner to find tools relevant to their workflow. Each listing shows ratings, pricing, and which Xero plans the app is compatible with.

To list in the marketplace, you need to become a certified Xero App Partner. That involves building a working integration, onboarding at least 3 active customers during a review window, and agreeing to Xero's commercial terms (which, as of March 2026, includes the new usage-based API pricing model rather than the previous revenue-share arrangement).

Xero by market

Xero's global footprint is uneven by design. The platform originated in New Zealand in 2006 and expanded first to Australia and the UK before moving into North America and beyond. Its adoption patterns, dominant integrations, and even regulatory requirements differ meaningfully by region.

Australia and New Zealand

This is Xero's home market and where its penetration is deepest. Australian and New Zealand SMEs tend to be highly digitized in their accounting practices, and Xero holds the dominant position against QuickBooks and MYOB. Payroll compliance here is particularly complex — single touch payroll (STP) reporting is mandatory for all employers in Australia, which means payroll integrations like Employment Hero and KeyPay are especially important in this region. Bank feed connectivity is also a high priority, as reconciliation speed is a key selling point for accountants. Apps built for this market often need to support multi-currency for NZD/AUD and handle GST rather than VAT.

United Kingdom

The UK is Xero's largest market by subscriber count outside ANZ. Adoption accelerated significantly after Xero positioned itself as the cloud alternative to Sage and QuickBooks in the mid-2010s. UK-specific requirements include Making Tax Digital (MTD) compliance — Xero is MTD-compatible for VAT, which is a non-negotiable feature for any UK accounting software. Payroll integrations need to handle PAYE, National Insurance, and Real Time Information (RTI) submissions to HMRC. Direct debit via GoCardless is the dominant payment collection method for subscription businesses. The UK also has a strong ecosystem of accounting practices built on Xero, making accountant-facing tools (practice management, client reporting) disproportionately popular here.

United States

Xero's fastest-growing but most contested market. QuickBooks Online holds an estimated 80% share of US small business accounting software, which means Xero is the challenger. Its US subscriber base skews toward businesses with international operations, founder-led tech companies, and businesses whose accountants actively recommend Xero as an alternative to Intuit's ecosystem. US-specific integrations cover federal and state payroll tax compliance (Gusto is the most widely used), sales tax automation (TaxJar, Avalara), and US bank feeds. The IRS 1099 reporting workflow is a common pain point for integrations in this market.

Canada

A smaller but meaningful Xero market, where it competes primarily with QuickBooks and Sage 50. GST/HST compliance is the primary tax requirement, and Canadian payroll is handled by integrations like Wagepoint and Humi. The Quebec market adds complexity with French-language requirements and distinct provincial tax rules.

Europe (ex-UK)

Xero has limited but growing presence in continental Europe, primarily among English-speaking founders and international businesses. Compliance requirements vary significantly by country — VAT regimes, payroll rules, and e-invoicing mandates (increasingly common across the EU) are not standardized. This fragmentation makes the European market harder to serve without localized integrations.

South Africa and Southeast Asia

Xero has a presence in South Africa and in markets like Singapore and Hong Kong, where English-language SMEs and accountants are comfortable with cloud-first tools. These markets tend to use the global app ecosystem rather than region-specific integrations, though local payroll and tax tools do exist.

What is integration with Xero?

Integration with Xero means connecting Xero to another software application so that data flows between the two systems automatically. Instead of manually exporting CSVs, copying invoice numbers, or reconciling data across tools, a Xero integration syncs that data in real time or on a defined schedule.

For a business using Xero, integrations mean the accounting ledger stays current without manual intervention. For a SaaS company, offering integration with Xero means customers can adopt your product without abandoning their accounting workflow.

Why Xero integrations matter

Finance teams live in Xero. When your product doesn't connect to it, you create friction at exactly the wrong moment — during a sales demo, at onboarding, or the first time a customer asks "does this sync with our accounting system?"

The business case is straightforward:

Fewer errors. Manual data entry between systems is one of the leading causes of accounting errors. Automated sync removes that entirely.
Faster close. Reconciliation takes hours when it's manual. With integrated bank feeds and automated transaction matching, finance teams close books in a fraction of the time.
Better visibility. Real-time data across connected tools means CFOs and finance managers have current numbers, not last-week's export.
Stronger retention. For SaaS products, accounting integrations are a lock-in mechanism. Customers who've embedded your product into their financial workflows don't churn easily.

Xero integration categories

Payments

Payment integrations connect Xero to your payment stack. Transactions get recorded automatically as they happen, matched to invoices, and reconciled in the ledger without manual entry.

Stripe is the most commonly used. When a customer pays an invoice, Stripe pushes the transaction to Xero, marks the invoice as paid, and logs the payment in the correct account. It supports card payments, Apple Pay, Google Pay, and cross-border transactions.

GoCardless is popular for recurring billing and direct debit. Particularly common with subscription businesses in the UK and Australia where bank debit is the norm.

PayPal has a native Xero integration for businesses processing payments through PayPal — it reconciles transactions against Xero invoices automatically.

Expense management

Expense integrations eliminate the paper trail. Employees capture receipts on mobile, expenses get categorized, and approved costs sync to Xero as journal entries or bills.

Xero Expenses is the native add-on built by Xero itself. From their phone, employees can log out-of-pocket expenses and snap a photo of each receipt. Claims are linked directly to the Xero account, so approvers can review and reimburse employees without switching tools. Because it's built by Xero, the data mapping is exact — no translation layer, no sync errors. For companies that don't need comprehensive spend management or better company cards, it's a solid starting point that reduces expense errors and speeds up reimbursement.

How it works:

Employees snap photos of receipts and log mileage claims from their phone.
Claims are processed and appear in the Xero ledger automatically.
Approvers track due dates and reimburse employees faster.

Ramp integrates directly with Xero for corporate card spend. It syncs accounting fields, transactions, reimbursements, vendor bills, and credits bidirectionally in real time. Accounts payable, expense management, and travel booking consolidate in one tool that stays in sync with Xero.

Expensify is one of the most widely used expense tools for Xero users. It handles receipt scanning, mileage tracking, and approval workflows, then pushes approved reports to Xero with correct GL coding.

Spendesk connects to Xero as part of a procure-to-pay workflow rather than a standalone expense sync: GL codes and tracking categories are assigned at the point of purchase approval, so the data arriving in Xero is already structured and policy-compliant before reconciliation begins. The integration covers card transactions, supplier invoices, and employee reimbursements, with three-way matching confirming PO-to-invoice alignment before payment is released via SEPA or Faster Payments. Invoices are archived in HMRC-compliant format automatically. Spendesk serves 200,000+ users across 29 EEA countries and the UK, and also integrates with QuickBooks, Sage, NetSuite, and DATEV.

Dext (formerly Receipt Bank) focuses specifically on document capture — bills, receipts, invoices — and extracts data to push into Xero before human review.

Payroll

Payroll integrations keep wage payments and tax withholdings accurate in the ledger without manual journal entries after every pay run.

Gusto syncs payroll transactions to Xero every time a payroll is run. You can choose how data appears — by employee, department, job title, or project. It handles US payroll, tax filings, and contractor payments. Pricing starts at $49/month plus $6 per person.

Employment Hero (formerly KeyPay) is the dominant Xero payroll integration in Australia and UK, handling award rate calculations, single touch payroll compliance, and automatic Xero reconciliation.

Xero Payroll is Xero's native offering in select regions. Where it's available, it's built directly into the platform — no integration required.

CRM

CRM integrations connect customer financial history to the sales and relationship layer. When your CRM knows what a customer owes or has paid, your sales and account management teams have full context.

HubSpot integrates with Xero to sync invoice data, payment status, and customer records. Sales teams see whether an account is current or overdue before reaching out. HubSpot's free tier supports basic integration; more advanced sync requires a paid plan.

Salesforce has multiple Xero connection options via marketplace apps. Enterprise B2B companies commonly use it to keep quote-to-cash data consistent between their CRM and accounting system.

eCommerce

eCommerce integrations sync sales, inventory, and payment data from your online store into Xero automatically.

Shopify has a native Xero integration that posts a daily sales summary to Xero, tracks pending payments from Shopify Payments and PayPal through a clearing account, and reconciles completed transactions against the correct bank account. It's free to enable in most regions.

WooCommerce integrates via apps like Xero for WooCommerce, pushing orders, refunds, and payment data into Xero as they happen.

A2X is widely used as a middleware layer for eCommerce businesses. It summarises Amazon, Shopify, Etsy, and other marketplace payouts into clean Xero journal entries by period.

Reporting and analytics

Reporting integrations extend beyond what Xero's native reports offer — particularly for multi-entity businesses, custom dashboards, and forward-looking financial modelling.

Fathom pulls Xero data to generate KPI dashboards, visual reports, and variance analysis. Used by accounting firms to build client-facing reporting packages.

Spotlight Reporting is common in the accounting and advisory space for consolidated multi-entity reports and three-way forecasting (P&L, balance sheet, cash flow).

Syft Analytics provides real-time Xero-connected dashboards, benchmarking, and automated narrative commentary for financial statements.

Inventory and operations

Cin7 and DEAR Inventory (now Cin7 Core) are the most widely used inventory management tools with Xero integration. They handle multi-location stock, purchase orders, and manufacturing BOMs, syncing financial transactions to Xero in real time.

Unleashed is popular in the wholesale and distribution space. It syncs inventory valuations, sales orders, and purchase orders to Xero and handles multi-currency.

Time tracking and professional services

Harvest integrates with Xero to convert tracked time into invoices, which are then pushed to Xero for accounts receivable management.

WorkflowMax (Xero's own project management tool, now independently operated as BlueRock's WFM) provides time tracking, job management, and invoicing with a direct Xero connection.

How to build a Xero integration into your product

If you're a SaaS company or fintech adding Xero support to your product, there are a few things to understand before you start.

The Xero API

Xero uses OAuth 2.0 for authentication. Access tokens expire every 30 minutes, so you need token refresh logic built in from day one. Refresh tokens last 60 days — but once used, they expire within 30 minutes, so accurate timing is essential. Always use the most recently issued token set and discard older ones; stale tokens cause auth errors that surface as bugs for your users.

For a full technical walkthrough, see our guide on Xero integration authentication and accounts receivable best practices.

To get your API credentials, you'll need to create an app in the Xero developer portal and generate a Client ID and Client Secret. See how to get your Xero API key.

Xero App Partner program

Xero limits unapproved apps to 25 active connections by default. To go beyond that, you need to apply to become a Xero App Partner — which involves onboarding at least 3 active customer connections within 30 days during review, and agreeing to commercial terms.

In March 2026, Xero moved to a new tiered API pricing model with five tiers (Starter, Core, Plus, Advanced, Enterprise) based on active connections and data egress volume. This replaced the previous revenue-share model. For a detailed breakdown of what each tier costs and how to optimize your spend, see our Xero API pricing guide.

Bank Feeds

If you're building a fintech product that needs to push transactions into Xero automatically, you'll need access to Xero's Bank Feeds API. This is a closed API — it's not available to all developers by default. You need a direct partnership agreement with Xero, which involves a certification process that typically takes 15–30 months.

For most fintech companies, that timeline is a dealbreaker. See our detailed breakdown of bank feeds API integration and what it actually takes to ship this feature.

The maintenance problem

Building a direct Xero integration is the start, not the end. Xero ships API changes. Authentication flows evolve. Data models update. Every change requires engineering time to track, assess, and patch. Over a multi-year timeline, this overhead compounds.

That's before you factor in customer demand for QuickBooks, NetSuite, Sage, and other platforms. Each direct integration multiplies the maintenance surface.

Xero integration best practices

Xero publishes official integration best practices that every developer building on the platform should internalize. These aren't just technical recommendations — with the move to usage-based pricing, they're also directly commercial. Inefficient API calls now cost real money.

Use webhooks instead of polling

Polling — repeatedly asking "has anything changed?" on a timer — is the most common source of unnecessary API calls and data egress. Xero supports webhooks for key endpoints, which means Xero pushes a notification to your app when something changes. You only fetch data when there's actually something to fetch.

If you genuinely can't use webhooks for a specific use case, choose longer polling intervals, support user-initiated refresh, and respect Xero's Retry-After response headers with exponential backoff. Don't hammer the API on a fixed schedule.

Cache aggressively

Caching Xero responses — and storing a timestamp of when you last fetched — is often the single biggest win for cutting unnecessary API calls. If your data was fresh five minutes ago and nothing has changed, don't fetch it again. For static or slow-changing data like account codes, chart of accounts, or tax rates, cache for hours or days. Only invalidate the cache when a webhook or user action signals that something has changed.

Use pagination and bulk retrieval correctly

When a customer first connects to your app, you may need to pull their full history — contacts, invoices, bank transactions, items. Don't do this with repeated single-record calls. Use Xero's pagination parameters (page=1, page=2, etc.) and increase the default page size from 100 up to 1,000 records per request using the pageSize parameter. Pull in bulk from Xero and parse at your end — it's far more efficient than trying to filter server-side across many small requests.

For subsequent syncs, use the modifiedAfter filter to only retrieve records that have changed since your last sync. This is one of the most impactful API efficiency improvements available.

Respect rate limits and handle errors gracefully

Xero enforces both per-tenant and app-wide rate limits. When you hit a limit, Xero returns a 429 Too Many Requests response along with a Retry-After header telling you how long to wait. Build this handling in from the start — catch 429s, read the header, wait the specified time, and retry. Don't retry immediately. Don't retry in a tight loop.

Beyond rate limits, build general error handling that logs failures with context. Silent errors that get swallowed are the hardest bugs to find later.

Manage connections carefully

With usage-based pricing, every active connection to a Xero organisation counts toward your monthly bill. Audit your connections regularly. If a customer has disconnected, churned, or is on a free tier that doesn't use Xero data, remove or deactivate the connection rather than leaving it live. Xero's Developer Portal has a History (and soon, Logs) page where you can see connection usage and rate-limit hits — use it proactively to spot patterns before they become cost problems.

For multi-tenant apps where multiple users in the same organisation may authenticate separately, store and reuse tokens per organisation rather than per user where possible. Avoid creating duplicate connections to the same Xero tenant.

Minimise data egress

Data egress — the volume of data returned by API calls — is the other variable in Xero's pricing model. Use field filtering where the API supports it to return only the fields your app actually uses. Don't pull full invoice objects when you only need the status and total. Combine this with caching and webhook-driven fetches, and your egress footprint can drop significantly without any change to the user experience.

Keep data integrity tight

Xero's data model is precise and transactional. A few rules that catch teams out:

Never post duplicate transactions. Use idempotency keys where supported, and check whether a record already exists before creating a new one.
Reconcile regularly. If your integration writes data to Xero, build a reconciliation mechanism that compares your internal state against Xero's ledger on a schedule. Catch drift early.
Handle rounding correctly. Xero applies specific rounding rules to line items and totals. Mismatched rounding is a common source of sync errors that only surface at month-end.
Don't modify data in Xero that the user owns. Integrations should write what they're responsible for and leave everything else alone.

Building Xero integrations with a unified API

The alternative to building direct is using a unified API layer. Apideck's Unified Accounting API connects your product to Xero and 29+ other accounting platforms through a single normalized interface. You write the integration once, and it works across Xero, QuickBooks Online, NetSuite, Sage Intacct, MYOB, and more.

What this means in practice:

No OAuth headaches. Apideck handles token refresh, credential storage, and connection management through a pre-built Vault component your users authorize directly.
No data model wrangling. Invoices, contacts, accounts, and journals look the same regardless of which accounting platform a customer uses.
No API maintenance. When Xero ships a change, Apideck absorbs it. Your code doesn't need to change.
Bank feeds support without the 15–30 month partnership process. Apideck has the Xero partnership in place.

A quick example using the Node.js SDK:

import { Apideck } from '@apideck/unify'

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

// List invoices from Xero
const result = await apideck.accounting.invoices.list({
  serviceId: 'xero'
})

// Switch serviceId to 'quickbooks' or 'netsuite' — same code

For a broader look at the accounting API landscape, see top 15 accounting APIs to integrate with in 2026.

Choosing the right Xero integration

A few questions to anchor the decision:

What data needs to flow? Invoice sync is different from bank feeds, which is different from expense categorization. Start with the specific data objects your use case requires and check whether the integration actually supports them — not just in marketing copy, but in the API documentation.

Which direction does data need to move? Some integrations are read-only (pulling Xero data for reporting). Others write back (pushing payments, bills, or journal entries). Bidirectional sync is more complex and more valuable.

What accounting platforms do your customers actually use? If 60% of your customers use Xero but 30% use QuickBooks, building only for Xero leaves a third of your customer base underserved. A unified API solves this.

What are the ongoing maintenance costs? A direct integration that ships in 6 weeks might cost 2x as much over three years once you account for maintenance. Factor this in.

For a broader context on what accounting integrations are and why they matter for modern SaaS products, see accounting integrations: what they are and how to build them.

Frequently asked questions

What is integration with Xero?
Integration with Xero means connecting another software application to Xero so that data syncs automatically between them — without manual exports, copy-pasting, or duplicate data entry. Common examples include syncing invoices from a CRM, pushing payroll transactions from a payroll tool, and feeding bank transactions from a fintech product.

What is the most popular Xero integration?
Stripe, Shopify, and Gusto are among the most widely used. The most popular category depends on the business type: payroll for service businesses, eCommerce connectors for online retailers, and expense management for companies with distributed spend.

How long does it take to build a Xero integration?
A minimal direct integration takes 4–8 weeks for a small engineering team. Production-ready, with error handling, token refresh, and webhook support, is closer to 3–6 months. Using a unified API like Apideck compresses that to days.

Does Xero charge for API access?
As of March 2, 2026, yes. Xero moved to a tiered pricing model based on connected organizations and API usage. There is a free Starter tier suitable for MVPs and testing, with paid tiers (Core, Plus, Advanced, Enterprise) for production applications.

What is the Xero App Marketplace?
The Xero App Marketplace is Xero's directory of third-party applications that integrate with Xero. It contains over 1,000 apps across categories including payments, payroll, eCommerce, and CRM. Listing your app requires becoming a Xero App Partner.

Can I integrate Xero with QuickBooks?
Not directly — they're competing platforms. However, if you're building a product that needs to support both, a unified API handles both through the same codebase.

Summary

Xero's integration ecosystem is one of its biggest strengths. With over 1,000 apps across every category a small or mid-sized business touches — payroll, payments, eCommerce, CRM, expenses, reporting — there's rarely a workflow that can't be automated with the right connector.

For businesses evaluating Xero integrations: focus on the specific data flows your team needs, check that the integration supports bidirectional sync if you need it, and consider the ongoing support footprint before committing.

For product teams building a Xero integration: the direct API route works but carries a maintenance burden that compounds over time, especially as you expand to other accounting platforms. A unified API handles the infrastructure so your engineering team can focus on the product.

Get started with Apideck's Xero integration →

If you're building products that connect to Xero alongside other accounting platforms, Apideck's Accounting API provides a unified integration layer for Xero, QuickBooks, NetSuite, Sage, and more — so you build once and connect to all of them through a single, normalized API.

Agentic Payments Are Rewriting Spend Management From Scratch

Kate Apideck — Wed, 24 Jun 2026 13:03:04 +0000

AI agents can now hold virtual Visa cards, execute purchases autonomously, and settle transactions with other agents. Every major payment network is racing to build the rails. For fintech founders, this is not a feature to bolt on. It is a new category of financial infrastructure emerging in real time.

The stakes are large. McKinsey estimates $3 to $5 trillion in global agentic commerce by 2030. Yet the infrastructure remains dangerously fragmented, with competing payment protocols, no interoperability, and a liability vacuum that no legal framework has fully addressed. Before getting into who is building what, it helps to understand what "agentic payments" actually means in practice.

Four layers of agent commerce

Most of what people call agent commerce today is not truly autonomous. There are four distinct layers.

Layer one: you research a product using an AI assistant and place the order yourself. Layer two: the agent finds the product and you confirm the payment. Layer three: you set a condition and the agent buys automatically when it is met. All three of these layers still use your payment credentials.

Layer four is where things get genuinely different. Your agent needs to call another model's API, purchase a dataset to complete a task, or hire a sub-agent to handle a subtask. In these scenarios, the agent is not using your card. It needs its own payment credentials. The current workaround is for developers to buy access on the agent's behalf and hand over credentials. That is not agency. That is acting as a purchasing agent.

Virtual cards are the first serious answer to this problem.

What agent-native virtual cards actually do

A product like AgentCard makes the mechanics concrete. You top up a balance, the agent calls a tool like create_card(amount=$50), and the provider issues a one-time prepaid Visa card locked to exactly that amount. The card is single-use, automatically deactivated after the transaction, and the agent never sees your underlying funding source. No overdraft risk. No credential exposure.

This is not just a developer toy. It reflects a structural shift in how software budgets will work: per-task allocation replacing per-employee card programs.

Three conditions matured simultaneously to make this possible. The demand side arrived with a new class of software builders: 25% of YC's Winter 2025 batch has over 95% of its codebase generated by AI, and 67% of Bolt.new's five million users are non-professional developers. On the supply side, APIs like Stripe Issuing made virtual card issuance programmable. And at the network layer, Visa and Mastercard both shipped agent payment protocols in 2025, with Cloudflare and Fiserv following quickly. Everyone saw the same thing: agents need their own financial infrastructure.

A three-layer solution stack

Virtual cards solve the compatibility problem but they inherit a core limitation from traditional card rails: slow settlement. When a merchant receives a card payment, funds can take days or weeks to clear. For an agent managing high-frequency micropayments across APIs and sub-agents, that lag compounds quickly. Cross-border fees add further friction.

The x402 protocol, developed by Coinbase with Cloudflare, addresses this at the HTTP layer. An agent sends a request, the server responds with a 402 status code and a price, the agent signs a USDC transfer, and the data is returned. No account registration, no subscription, pay-as-you-go. The entire transaction is a single HTTP exchange. x402 has already reached $600 million in annualised volume.

These two approaches serve different use cases and are not competing. Virtual cards work wherever Visa is accepted: online retail, SaaS subscriptions, cloud service billing. x402 and similar stablecoin rails work for agent-to-agent payments, API calls, and sub-agent hiring where card rails are either too slow or too expensive.

The three-layer stack that is emerging looks like this. Virtual cards address compatibility with the existing merchant world. Stablecoins address settlement speed and micropayment economics. Native programmable wallets address the governance complexity that emerges when one agent is managing dozens of sub-agents, each with their own transaction history. Which layer matters most depends entirely on what your agent is transacting with today.

This is directly relevant for teams building on open banking infrastructure: the same account-to-account payment rails that power open banking are candidates for the stablecoin-speed settlement layer, without requiring new network relationships.

The infrastructure players

The established networks moved quickly. Mastercard launched Agent Pay in mid-2025, processing its first on-network agentic transaction and rolling out to all US cardholders by November 2025. The system uses Agentic Tokens tied to each authorised agent interaction. In March 2026, Mastercard and Santander completed Europe's first live end-to-end AI agent payment within a regulated banking framework.

Visa responded with Intelligent Commerce, opening VisaNet to developers building AI commerce agents. The suite includes tokenised AI-Ready Cards and Payment Instructions loaded directly into VisaNet. Over 100 partners are in build or sandbox. By December 2025, Visa had completed hundreds of secure agent-initiated transactions in US pilots.

Stripe moved fastest on open protocol. The Agentic Commerce Protocol, co-developed with OpenAI and released in September 2025, powers ChatGPT's Instant Checkout. It introduced Shared Payment Tokens: scoped, time-limited, revocable credentials that let agents initiate payments without exposing underlying card details. Affirm and Klarna both integrated buy-now-pay-later via SPTs in March 2026. Google's Agent Payments Protocol took a different approach, using cryptographically signed Mandates and W3C Verifiable Credentials to create a tamper-proof audit trail that is payment-rail agnostic.

At the startup layer, Skyfire raised $9.5 million from a16z CSX and Coinbase Ventures to build agent identity and KYA (Know Your Agent) infrastructure. Natural raised $9.8 million to build B2B payment rails for agent-led procurement workflows. Payman AI raised $13.8 million with participation from Visa and Coinbase Ventures, building a platform for financial institutions to deploy agent-driven transactions. Kite AI raised $35 million from PayPal and General Catalyst to build a Layer 1 blockchain specifically for agent payment infrastructure.

What this means for spend management

Traditional spend management platforms face a two-wave disruption.

Wave one is actually strengthening them in the short term. Brex launched AI-driven expense automation in fall 2025, claiming 99% of expense reports handled without human review. Ramp Agents, launched in July 2025, catches 15 times more out-of-policy spend than non-AI alternatives with 99% policy enforcement accuracy. Upload a policy document and the agent builds a reasoning graph in minutes. Vendr went a step further with Ruth Negotiations, launching AI agent contract negotiations powered by their dataset of billions in dollars of software purchases. You describe the deal and target price, Ruth analyzes the quote, builds a negotiation strategy, and runs the negotiation on your behalf, handling the tail spend that finance teams typically do not have bandwidth to optimize.

Wave two is more disruptive. When agents transact autonomously via agent-native protocols, settling in stablecoins through programmable wallets with per-task budgets, the concept of a corporate card built around human-in-the-loop approvals becomes structurally misaligned. A card network's 30-cent fixed fee makes micropayments uneconomical. Its assumption of a human authorising each transaction breaks at machine speed. These are not product problems. They are architectural ones. The ERP API integrations that currently connect spend management platforms to ERPs will need to accommodate agent-initiated transaction records that arrive at very different frequencies and formats than human expense submissions.

a16z put it plainly: an agent streaming $0.001 per second to a compute provider and a manufacturer settling a $50,000 vendor invoice can share the same rail, but only on stablecoin infrastructure.

The unsolved liability problem

Every major institution converges on the same unresolved question: who is liable when an agent makes a bad purchase?

The Consumer Bankers Association's January 2026 white paper, convening Bank of America, JPMorgan, PNC, Google, Stripe, Visa, and Mastercard, concluded that under the Electronic Fund Transfer Act, consumers may be liable for mistakes their agents make when they voluntarily grant an access device to an AI. Chargebacks introduce an additional party with no established allocation of responsibility.

Fraud vectors are shifting in parallel. Visa has reported a significant increase in dark web activity around AI agent fraud tooling. The threat model has moved from stolen credentials to hijacked agents: malware that distorts agent behaviour so transactions technically follow preset rules but do not reflect user intent. High-frequency, small-value abuse can overwhelm fraud teams before it shows up as a visible loss.

Authorization standards remain fragmented. Mastercard uses Agentic Tokens, Visa uses Trusted Agent Protocol, Google uses cryptographic Mandates. None of these interoperate. The "Know Your Agent" standard being developed mirrors KYC for machines, but no unified standard exists yet.

Gartner predicts over 40% of agentic AI projects will be cancelled by end of 2027 due to escalating costs or inadequate risk controls. The EU AI Act's 2026 obligations require human oversight and auditability. PSD2's Strong Customer Authentication has no mechanism for treating AI agents as equivalent to human payers.

The historical pattern and where the opportunity is

The pattern here is consistent. eBay created a marketplace of individual sellers who could not get merchant accounts. PayPal solved their payment problem. Independent developers needed to accept online payments without an enterprise sales cycle. Stripe solved it with a few lines of code. Each platform shift produced a new class of merchants that existing rails could not serve. The winner was whoever served them first.

The new merchant class is agents. Millions of builders who could not write production code two years ago are now shipping software with AI. Their agents will transact, and those transactions need infrastructure.

The competitive map has a clear gap. Networks own identity and authorisation. Stripe and Google own checkout protocols. Brex and Ramp own the automation layer for human-in-the-loop workflows. What remains almost entirely unbuilt is the connective tissue: cross-protocol interoperability, real-time policy engines that work across competing standards, agent identity registries, and the audit and liability infrastructure for when things go wrong.

The unified API layer becomes meaningful here. When an enterprise deploys agents across procurement, vendor payments, and sub-agent orchestration, the accounting system of record needs to receive all of it coherently, regardless of whether the underlying transaction settled on a Visa rail, via x402, or through a stablecoin wallet. Normalising agent-initiated transaction data across those surfaces is exactly the kind of integration problem that a unified API layer exists to solve.

Whoever builds the governance layer that makes autonomous spending trustworthy, the compliance infrastructure, the audit trails, the policy engines, and the kill switches that let an enterprise hand an agent a budget and operate confidently, will define the next generation of financial infrastructure. The scaffolding is in place. The real infrastructure has barely started.

Accounting Software Integration: Architecture, Trade-offs, and Costs for SaaS Teams

Kate Apideck — Fri, 19 Jun 2026 13:33:23 +0000

Accounting software integration is product infrastructure. For B2B SaaS, fintech, and vertical SaaS companies that handle financial data, connecting your product to external accounting systems like QuickBooks, Xero, NetSuite, or Sage is an architectural decision that directly affects reliability, time to market, total cost of ownership (TCO), and customer retention.

The open accounting trend is making accounting software integration a baseline expectation rather than a nice-to-have — businesses now demand that their financial tools connect seamlessly.

This article covers what accounting integration involves at a technical level, the architecture options available to your team, the real costs of building in-house versus buying through a unified API, and a practical framework for evaluating providers.

What "Accounting Software Integration" Actually Means

Accounting software integration is the programmatic connection between your product and one or more external accounting systems. The goal is bidirectional data flow: your application creates, reads, updates, and syncs financial objects (invoices, payments, journal entries, accounts, contacts, tax rates) inside your customers' accounting platforms.

This goes well beyond a single API call. A production-grade integration requires OAuth flow handling and token lifecycle management across providers, mapping your internal data model to each provider's schema, managing sync patterns (real-time webhooks where available, scheduled polling where not), rate limit and retry logic on a per-provider basis, and multi-tenant credential isolation.

Each accounting platform brings its own API design, authentication method, object model, and constraints. QuickBooks Online uses OAuth 2.0 with short-lived tokens. Xero requires tenant-specific headers and enforces strict rate limits. NetSuite uses token-based authentication with an entirely different data model. Multiply these differences across ten or twenty providers and the scope of the problem becomes clear.

Why It Matters for Your Product and Customers

Integration support directly impacts buying decisions. According to SMB Group's 2024 Technology Buying Journey survey, 34% of SMBs rank compatibility with existing systems as a top factor when shortlisting solutions, with that number climbing even higher for companies between 100 and 499 employees. Separately, Capterra's SMB Software Buying Trends Survey found that 38% of SMBs rate integration capabilities as one of the most important factors when evaluating new software. If your product can't connect to the accounting tool a prospect already uses, you lose the deal before the demo ends.

The business case extends beyond deal velocity. Integrated accounting systems eliminate manual data duplication and provide real-time visibility into financial operations. Expend, for example, uses Apideck's accounting unified API to provide seamless integration with platforms like Xero, QuickBooks, and Sage, enabling automatic categorization and tracking of expenses while reducing manual entry for their customers. When your product automatically syncs invoices, payments, or expense data to a customer's general ledger, you reduce reconciliation errors, accelerate month-end close for their finance teams, and embed your product into their core financial workflow.

For SaaS teams, this translates to higher retention rates, expanded deal sizes (integration is often a gating criterion for mid-market and enterprise accounts), and lower support load.

Common Integration Scenarios

Before evaluating architecture models, it's worth grounding the discussion in the specific workflows your product will need to support.

Invoice sync is the most common starting point. Your product generates an invoice and needs to create or update the corresponding record in the customer's accounting system with correct line items, tax treatment, and account mapping. Payment reconciliation follows closely: matching payments received in your platform against open invoices in the accounting system, handling partial payments, credits, and refunds.

Other high-value workflows include accounts receivable sync, chart of accounts mapping (allowing customers to map your product's categories to their GL structure), expense and payout posting, and journal entry creation for complex transactions that don't fit standard invoice or payment objects.

Each workflow multiplies the integration surface area. The invoice object alone varies significantly between providers with different required fields, tax calculation models, currency handling, and line-item structures.

Four Integration Architecture Models (and When They Make Sense)

Native Vendor Integrations

Some accounting platforms offer their own integration tooling through pre-built connectors or app marketplace frameworks. The upside is speed: you can ship a single integration quickly using the vendor's SDK.

The limitation is control and breadth. You're locked into one vendor's ecosystem, and the integration surface is restricted to what the vendor exposes. If your customers use a mix of accounting tools (which is almost always the case), native integrations don't scale.

Custom In-House Integrations

Building point-to-point integrations gives your team full control over data flow, error handling, and business logic. For a single connector against a well-documented API, this can be a reasonable starting point.

The cost equation changes fast when you add a second or third provider. Each new connector introduces its own authentication flow, data model, rate-limiting behavior, webhook format (if webhooks exist at all), and edge cases. Industry analysis consistently shows that a single production-grade connector requires roughly 30+ person-days of engineering effort covering scoping, implementation, testing, documentation, and deployment, with significant ongoing maintenance thereafter.

The real cost driver is combinatorial complexity. Auth handling for five providers means five different OAuth implementations (or a mix of OAuth, API key, and token-based schemes). Object mapping for five providers means five different invoice schemas, five different payment models, five different error response formats. Your integration layer becomes a second product that demands its own roadmap, on-call rotation, and monitoring infrastructure.

iPaaS and Automation Platforms

Tools like Zapier, Workato, or Tray.io are designed for workflow automation, primarily for internal operations. They work well for connecting internal tools: syncing CRM data to a spreadsheet, triggering notifications between systems.

For product-embedded accounting integrations, iPaaS platforms fall short. They typically lack multi-tenant isolation, add latency through a dependency layer you can't fully control, and aren't designed for structured bidirectional data sync. They're also difficult to embed into your product's UX as a native experience.

Unified API Providers

A unified API abstracts multiple accounting platforms behind a single normalized API layer. You integrate once against a standardized schema (invoices, payments, contacts, ledger accounts) and the provider handles per-platform translation, authentication, rate limiting, and connector maintenance.

The architectural advantage is clear: one integration surface instead of many. The vendor maintains individual connectors, handles upstream API version changes, and exposes a consistent set of endpoints regardless of which accounting system the end user connects.

The trade-off is that you're introducing a dependency and may lose some provider-specific functionality. Strong unified API providers mitigate this by offering passthrough or raw-field access alongside the normalized schema, so you can still reach provider-specific endpoints when needed.

Trade-offs at a Glance

Factor	Native Vendor	Custom In-House	iPaaS	Unified API
Time to first integration	Fast	Moderate	Fast	Fast
Multi-provider scalability	Poor	Expensive	Limited	Strong
Control over logic	Limited	Full	Partial	High (with passthrough)
Maintenance burden	Low (single)	Very high	Moderate	Low
Product embedding fit	Varies	Strong	Weak	Strong
TCO at 5+ providers	High	Very high	Moderate	Low

Core Technical Requirements for Reliable Integrations

Regardless of architecture model, a production-grade accounting integration needs to handle several non-trivial concerns.

Authentication and consent management. Every integration starts with getting the customer to authorize access to their accounting data. This means implementing OAuth 2.0 flows (with provider-specific variations), securely storing and refreshing tokens, handling revocation and re-authorization, and building the UI for customers to manage connections. With a unified API, this entire surface is handled by the provider. Your product calls a single authorization endpoint while the vendor manages per-provider OAuth complexity.

Data model normalization. An invoice in QuickBooks Online is structurally different from an invoice in Xero, which differs again from NetSuite. Line item representations, tax handling, currency fields, custom fields, and required-versus-optional attributes all vary. Building in-house means creating and maintaining a mapping layer for each provider. A unified API normalizes these into a consistent schema, typically with the option to access raw provider-specific fields.

Sync patterns and reliability. Some providers support webhooks for real-time change notifications; others only support polling. Your sync engine needs to handle both, along with idempotency (preventing duplicate records from the same event), deduplication, conflict resolution, and ordering guarantees. Invoice creation may need to be near-real-time, while chart-of-accounts sync can be periodic.

Error handling and observability. Accounting APIs fail in provider-specific ways: rate limit errors, validation failures, temporary outages, schema changes. A robust integration layer needs structured retry logic (exponential backoff, dead-letter queues), clear error surfacing to end users, and internal observability (dashboards, alerting, structured logs).

Security and compliance. Financial data carries regulatory weight. Token storage must be encrypted, API traffic encrypted in transit, and audit trails should capture who accessed what data and when. A proxy-based architecture that passes data through without storing it reduces the compliance surface significantly.

Multi-tenancy. In a SaaS context, every customer connection is an isolated tenant. Credential isolation, per-tenant rate limiting, and per-tenant error handling are table stakes. Easy to underestimate during initial development; painful to retrofit later.

Build vs Buy: A Total Cost of Ownership Framework

This is where the engineering decision becomes a financial one.

In-house cost reality. Building a single accounting connector covering authentication, core CRUD operations, error handling, testing, and documentation typically consumes 30+ person-days of engineering time. Depending on team location and seniority, that translates to roughly $20,000–$40,000 per connector in direct engineering cost.

The initial build is only the beginning. Ongoing maintenance (handling API version changes, fixing production edge cases, managing token refresh failures, updating documentation) can consume 20–30% of an engineer's time in perpetual maintenance mode. Add observability, SLA management, and support ticket triage, and a single connector's annual run-rate often exceeds the initial build cost.

Multiply that across five, ten, or twenty providers and the math gets uncomfortable fast.

Year 1 TCO = (Number of connectors × Build cost per connector) + Infrastructure + Tooling

Year 2+ TCO = (Number of connectors × Annual maintenance cost) + New connector builds + Infrastructure

For a team building five accounting connectors in-house, a conservative three-year estimate: $100,000–$200,000 in initial build costs, plus $75,000–$150,000 per year in ongoing maintenance, totaling $325,000–$650,000 over three years. That excludes the opportunity cost of diverting engineering resources from your core product roadmap.

Unified API cost reality. With a unified API provider, you build one integration and gain access to multiple accounting platforms immediately. The vendor absorbs per-connector build and maintenance costs. Your spend becomes a predictable monthly or annual fee that scales with connected consumers, not with engineering headcount.

To put concrete numbers against this: Apideck's Launch plan starts at $599/month for 25 consumers and includes access to 2 Unified API categories (e.g., Accounting and CRM), passthrough API support, and web books. The Scale plan covers 100+ consumers with additional features like custom field mapping and data scopes. Annual billing reduces costs by 10%. At $599/month ($7,188/year), you get access to every accounting connector Apideck supports, with connector maintenance, authentication handling, and infrastructure included.

Compare that to the in-house scenario above: five connectors built in-house run $325,000–$650,000 over three years. The same coverage through a unified API runs roughly $21,500 over three years on the Launch plan, or more on Scale/Enterprise tiers as your consumer count grows. Even at higher tiers, the cost difference is substantial, and your engineering team stays focused on your core product.

The ROI inflection point is typically around the second or third connector. If you only need a single accounting integration with no plans to expand, building in-house may be the right call. Once you're supporting three or more providers, or expect to within 12–18 months, the unified API model almost always wins on TCO.

Choosing the Right Integration Provider

When evaluating unified API providers or any third-party integration solution, here is a practical checklist:

Provider coverage and data depth. How many accounting platforms does the vendor support, and how deep is the coverage? Listing a connector is one thing. Supporting full CRUD operations on invoices, payments, journal entries, and contacts across that connector is another.

Normalized schema plus raw access. A strong unified API provides a clean, normalized data model for common objects and the ability to access provider-specific fields or endpoints when needed. Without raw access, you'll hit walls on edge cases the normalized model doesn't cover.

Developer experience. Evaluate documentation, SDKs, sandbox environments, and API reference quality. Your engineers will work with this tooling daily. Poor developer experience creates friction that compounds over time.

Reliability and observability. Ask about uptime SLAs, how the vendor handles upstream provider outages, and what monitoring and logging tools are available. You need visibility into the integration layer, particularly when things break.

Security posture. SOC 2 Type II certification is a baseline expectation. Examine how the vendor handles token storage, whether they use a proxy-based architecture (passing data through without persisting it) or a caching model, and how they address data residency requirements.

Pricing predictability. Per-API-call pricing can be unpredictable and creates cost anxiety as you scale. Per-consumer or per-connected-account pricing tends to be more predictable and aligns with your own revenue model.

Roadmap velocity. How fast does the vendor ship new connectors and expand endpoints on existing connectors? Ask about release cadence and how they prioritize new provider coverage.

Practical Implementation Guidance for Engineering Teams

Accounting integrations work best when rolled out in phases, whether you build or buy.

Phase 1: MVP with a single high-impact workflow. Pick the workflow your customers ask about most (usually invoice sync or payment reconciliation) and implement it for the one or two accounting platforms that cover the largest share of your customer base. Keep scope tight: one workflow, one or two providers, basic error handling and retry logic. Build the connection UX (OAuth flow, account mapping) and start collecting production feedback.

Phase 2: Expand workflows and add reconciliation. Layer on additional workflows (AR sync, journal entries, expense posting) and harden the reliability layer with idempotency, deduplication logic, and structured observability. Build or integrate a mapping UI that lets customers configure how your product's entities correspond to their chart of accounts.

Phase 3: Multi-provider coverage and abstraction. Expand to additional accounting providers. With a unified API, this phase is mostly configuration. If you've built in-house, this is where per-connector multiplication hits and many teams realize the maintenance trajectory is unsustainable. Invest in a clean internal abstraction layer so your product code isn't coupled to any single provider's implementation details.

At each phase, build diagnostic tooling for your support team: connection status, sync history, error logs, and the ability to trigger manual re-syncs.

Where Unified APIs Shine (and Where They Don't)

Unified APIs are the clear choice when your customer base uses a mix of accounting platforms, you need to support three or more providers now or within the next year, the integration is embedded in your product rather than used internally, your engineering team can't dedicate multiple engineers to integration maintenance, and speed to market is a priority.

In-house still makes sense when you have a single-provider mandate with deep niche extensions no unified API covers, your workflows are highly specialized (for example, complex multi-entity consolidation requiring direct NetSuite SuiteScript access), or regulatory requirements demand full control over every component in the data path.

For most B2B SaaS, fintech, and vertical SaaS companies, the unified API path delivers better TCO, faster time to market, and lower operational overhead.

Vendor Landscape and What It Means for Your Architecture

The unified API market for accounting integrations has matured. When evaluating vendors, focus on architectural differences that affect your product.

Proxy-based versus caching architectures. Some unified APIs cache data from upstream providers and serve it from their own storage. Others operate as a real-time proxy, forwarding requests directly to the upstream provider. A proxy-based model reduces the vendor's data storage footprint, minimizes staleness, and shrinks the compliance surface because your customers' financial data passes through but isn't stored by a third party.

Normalized schema with passthrough access. The strongest platforms provide a clean normalized API for standard operations while exposing passthrough endpoints for provider-specific functionality. This gives your team the speed of a unified interface without sacrificing access to each underlying provider's full capabilities.

Multi-category coverage. If your product touches not just accounting but also CRM, HRIS, e-commerce, or payments, a platform that covers multiple integration categories through the same architecture can simplify your stack further.

Apideck, for example, uses a proxy-based architecture with normalized schemas and raw field access across 200+ connectors spanning accounting and multiple other categories. Its consumer-based pricing model aligns cost with connected accounts rather than API call volume, providing more predictable scaling economics for SaaS teams. The platform includes embeddable UI components for connection management, sandboxed development environments, and SOC 2 Type II certification.

Regardless of which vendor you evaluate, the architectural pattern matters most: a normalized integration layer that abstracts provider complexity, reduces maintenance burden, and frees your engineering team to focus on the product features that differentiate your business.

How to Integrate with the Rillet API in 2026

Kate Apideck — Fri, 19 Jun 2026 08:53:54 +0000

Rillet has quietly become one of the more interesting accounting platforms for SaaS and fintech companies. Built on REST principles, following the OpenAPI Specification, and recently shipping an MCP server — it's a system that's clearly designed by people who have actually integrated with legacy ERPs and didn't want to recreate that pain.

This guide covers everything you need to get up and running with the Rillet API: authentication, pagination, idempotency, webhooks, error handling, and the newer MCP server setup. Whether you're syncing financial data from a payment processor, building a custom integration between Rillet and your internal systems, or using an AI coding agent to accelerate development, this should give you a solid foundation.

If you'd rather skip the direct integration work, Apideck now supports Rillet as a connector through the Unified Accounting API. That means you can read and write Rillet data through the same API you'd use for QuickBooks, Xero, NetSuite, or any of 30+ other accounting platforms. More on that at the end of this guide.

What the Rillet API Actually Is

Before jumping into code, it's worth understanding the scope. The Rillet API is a REST API that gives you programmatic access to everything a user can do in the UI: customers, invoices, payments, credit memos, journal entries, chart of accounts, reports (balance sheet, trial balance), and more. It's versioned, paginated, and follows RFC 9457 for structured error responses — which is a good sign.

The API spec is available as an OpenAPI download at https://docs.api.rillet.com/openapi, which means you can generate client code in any language you prefer without hand-rolling everything.

Environments

Rillet provides two environments:

Production: https://api.rillet.com
Sandbox: https://sandbox.api.rillet.com

Start in sandbox. The sandbox mirrors production behavior, so anything you build there will work in production without surprises. All examples in this guide use the sandbox URL.

Authentication

Rillet uses API key authentication. To get a key, contact your Rillet team to enable API access, then create and manage keys in your Organization Settings under API Access.

Every request needs the key in the Authorization header as a Bearer token:

curl --request GET \
  --url https://sandbox.api.rillet.com/customers \
  --header 'Authorization: Bearer YOUR_API_KEY'

That's it. No OAuth dance, no token expiry to manage. Keep your key in an environment variable and never hardcode it.

const RILLET_API_KEY = process.env.RILLET_API_KEY;

const headers = {
  'Authorization': `Bearer ${RILLET_API_KEY}`,
  'Content-Type': 'application/json',
};

API Versioning

The API is versioned, and you should always target a specific version explicitly rather than relying on the default (which falls back to v1.0). Pass the version in an HTTP header:

curl --request GET \
  --url https://sandbox.api.rillet.com/customers \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'X-Rillet-API-Version: 3'

At the time of writing, v3 is the current version. Pinning your version header means you won't get unexpectedly broken by a major API update. Check the docs for the exact format — the changelog indicates versions are referenced as integers (2, 3), not decimals.

Pagination

All list endpoints use keyset-based pagination, which is the right choice for financial data where consistent page sizes and response times matter more than offset-based approaches.

Responses come back in reverse chronological order and include a pagination object:

{
  "data": [...],
  "pagination": {
    "next_cursor": "VdW1ptsZbOB4E1fq"
  }
}

To fetch the next page, pass the cursor as a query parameter:

curl "https://sandbox.api.rillet.com/invoices?cursor=VdW1ptsZbOB4E1fq"

A few things to know:

Cursors are valid for 2 hours. If yours expires, a new pagination sequence starts from the first page.
The default page size is 25. You can set it with the limit parameter, up to a maximum of 100.
When there's no next_cursor in the response, you've reached the last page.

Here's a simple function to paginate through all invoices:

async function getAllInvoices() {
  const invoices = [];
  let cursor = null;

  do {
    const url = new URL('https://sandbox.api.rillet.com/invoices');
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);

    const response = await fetch(url, { headers });
    const data = await response.json();

    invoices.push(...data.data);
    cursor = data.pagination?.next_cursor ?? null;
  } while (cursor);

  return invoices;
}

Incremental Sync with `updated_at` Filters

Rillet has been rolling out updated_at timestamps and updated.gt filter support across its entities. As of February 2026, accounts and custom fields explicitly gained both the timestamp field and the filter parameter. Other entities — customers, invoices, payments, credit memos, and journal entries — already carried updated_at in responses, though filter support varies by entity; check the changelog and OpenAPI spec for what's available on each.

For accounts specifically, confirmed as of February 2026:

curl "https://sandbox.api.rillet.com/accounts?updated.gt=2026-02-01T00:00:00Z" \
  --header 'Authorization: Bearer YOUR_API_KEY'

For reporting journal entries, the endpoint also supports updated.gt filtering:

curl "https://sandbox.api.rillet.com/reports/journal-entries?updated.gt=2026-02-01T00:00:00Z" \
  --header 'Authorization: Bearer YOUR_API_KEY'

The general pattern — poll periodically, store the last sync timestamp, fetch only what's changed — is the right approach for building a sync pipeline. Before assuming updated.gt works on a given entity, verify it against the current OpenAPI spec at https://docs.api.rillet.com/openapi.

Idempotency

For POST requests (creating invoices, customers, journal entries, etc.), Rillet supports idempotency keys. This is critical if you're dealing with network failures or retries — you don't want to double-create an invoice because a request timed out.

Pass a unique key in the Idempotency-Key header:

curl --request POST \
  --url https://sandbox.api.rillet.com/invoices \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Idempotency-Key: f0e9a51e-905d-4caf-a5dc-64d326574646' \
  --header 'Content-Type: application/json' \
  --data '{"customer_id": "cust_123", ...}'

A few rules:

Use UUID v4 for your keys — high entropy, low collision risk.
The same response is returned for 24 hours after the first successful request. After that, the same key will create a new object.
If a request fails due to a validation error, the response isn't saved and you can safely retry with the same key.
If a second request arrives while the first is still processing, you'll get a 409 Conflict.

Rate Limiting

The limit is 60 requests per rolling minute. Requests over that threshold return HTTP 429. Build in retry logic with exponential backoff:

async function rilletRequest(url, options, retries = 3) {
  for (let attempt = 0; attempt < retries; attempt++) {
    const response = await fetch(url, { ...options, headers });

    if (response.status === 429) {
      const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    return response;
  }

  throw new Error('Rate limit exceeded after retries');
}

At 60 requests per minute, you're unlikely to hit this in normal operations unless you're running a bulk sync. If you are, batch your calls and space them out accordingly.

Error Handling

Rillet follows RFC 9457 for structured error responses. A 4xx error looks like this:

{
  "type": "https://rillet.com/illegal-argument",
  "title": "Bad Request",
  "status": 400,
  "detail": "The start date (2026-01-01) must not be after the end date (2025-12-31). Please review the contract item."
}

The detail field is human-readable and actually useful — it tells you what went wrong. Parse the type field for programmatic error handling, and surface detail in your logs.

async function handleRilletResponse(response) {
  if (!response.ok) {
    const error = await response.json().catch(() => null);
    const detail = error?.detail ?? `HTTP ${response.status}`;
    throw new Error(`Rillet API error: ${detail}`);
  }
  return response.json();
}

Monetary Values

Financial amounts are returned as strings, not floats — which is the correct approach for avoiding floating point precision issues. Each amount comes with a currency code:

{
  "amount": "100.99",
  "currency": "USD"
}

The currency field is always an ISO-4217 three-letter code. Note that Rillet allows more decimal places than the ISO standard for certain fields like unit prices, so don't assume two decimal places — parse flexibly.

Use a decimal library (like decimal.js or Python's decimal module) rather than JavaScript's native Number when doing arithmetic on these values.

Webhooks

Rather than polling for changes, you can subscribe to real-time events via webhooks. Rillet supports events across entities like Invoice, Customer, Payment, and Credit Memo, with event types like CREATED and UPDATED.

Setup

Go to Organization Settings > Webhooks in the Rillet dashboard:

Give it a name.
Provide a publicly accessible HTTPS URL.
Select the events you want to receive.
Enable the webhook.

An organization can have up to 5 webhooks. The recommendation from Rillet's docs is to use a single endpoint and handle routing in your application.

Incoming Request Structure

Every webhook request is a POST with a JSON body and these headers:

Header	Description
`X-Rillet-Signature`	HMAC-SHA256 signature (Base64-encoded)
`X-Rillet-Timestamp`	ISO 8601 timestamp
`X-Rillet-Id`	Unique UUID for this delivery
`X-Rillet-Entity`	Entity type (e.g., `INVOICE`)
`X-Rillet-Event`	Event type (e.g., `CREATED`)

Your endpoint must respond with a 2xx status within 30 seconds. Rillet retries failed deliveries in groups of 3 with exponential backoff, up to 5 groups before marking the webhook as failed.

Use X-Rillet-Id for idempotency on your side — deduplicate incoming events by this ID.

Verifying Signatures

Always verify the signature. The signature is an HMAC-SHA256 hash of a concatenated payload, Base64-encoded. The signed payload format is:

{timestamp}.{id}.{entity}.{event}.{raw_body}

Here's a TypeScript implementation:

import * as crypto from 'crypto';
import { Buffer } from 'node:buffer';

export function verifyRilletWebhook(
  headers: Record<string, string>,
  rawBody: string,
  token: string
): void {
  const signatures = (headers['X-Rillet-Signature'] ?? '')
    .split(',')
    .map(s => s.trim())
    .filter(Boolean);

  const timestamp = headers['X-Rillet-Timestamp'];
  const id = headers['X-Rillet-Id'];
  const entity = headers['X-Rillet-Entity'];
  const event = headers['X-Rillet-Event'];

  if (!signatures.length || signatures.length > 10 || !timestamp || !id || !entity || !event) {
    throw new Error('Missing or invalid Rillet webhook headers');
  }

  const signedPayload = `${timestamp}.${id}.${entity}.${event}.${rawBody}`;
  const tokenBytes = Buffer.from(token, 'base64');

  const verified = signatures.some(sig => {
    const expected = crypto
      .createHmac('sha256', tokenBytes)
      .update(signedPayload)
      .digest('base64');

    const receivedBuf = Buffer.from(sig, 'base64');
    const expectedBuf = Buffer.from(expected, 'base64');

    return (
      receivedBuf.length === expectedBuf.length &&
      crypto.timingSafeEqual(receivedBuf, expectedBuf)
    );
  });

  if (!verified) throw new Error('Invalid webhook signature');
}

And the Python equivalent:

import hashlib
import hmac
import base64

def verify_rillet_webhook(headers, raw_body, token):
    signatures = [s.strip() for s in headers.get('X-Rillet-Signature', '').split(',') if s.strip()]
    timestamp = headers.get('X-Rillet-Timestamp')
    event_id = headers.get('X-Rillet-Id')
    entity = headers.get('X-Rillet-Entity')
    event = headers.get('X-Rillet-Event')

    if not signatures or len(signatures) > 10 or not all([timestamp, event_id, entity, event]):
        raise ValueError('Missing or invalid Rillet webhook headers')

    signed_payload = f"{timestamp}.{event_id}.{entity}.{event}.{raw_body}"
    token_bytes = base64.b64decode(token)

    for sig in signatures:
        expected = hmac.new(token_bytes, signed_payload.encode('utf-8'), hashlib.sha256).digest()
        received = base64.b64decode(sig)
        if hmac.compare_digest(received, expected):
            print('Signature verified.')
            return

    raise ValueError('Invalid webhook signature')

One edge case worth knowing: the signature header can contain up to 10 comma-separated signatures to support token rotation without downtime. Your code should verify any of them, not just the first.

Using the Rillet MCP Server

This is the part that's new in 2026 and genuinely useful if you're using AI coding agents to build or maintain your integration.

Rillet ships a remote MCP server at https://docs.api.rillet.com/mcp. You can connect AI tools like Claude Code, Cursor, Windsurf, or Claude Desktop to it, and they'll have direct access to your Rillet account data and documentation. This means your AI assistant can look up your actual customers, check for overdue invoices, or generate integration code that reflects your real chart of accounts.

Setting Up with Claude Code

# Sandbox
claude mcp add --transport http rillet-mcp-sandbox \
  https://docs.api.rillet.com/mcp \
  --header "Authorization: Bearer YOUR_SANDBOX_KEY"

# Production
claude mcp add --transport http rillet-mcp-prod \
  https://docs.api.rillet.com/mcp \
  --header "Authorization: Bearer YOUR_PROD_KEY"

# Verify
claude mcp list

When prompting your AI agent, specify which environment to use: "Use the Rillet MCP in sandbox." From there you can ask questions like "What customers do I have?" or "Do I have any overdue invoices?" and get answers grounded in your actual data.

This is particularly useful during development — instead of manually reading through API docs and constructing test requests by hand, you can have an AI agent explore the API surface against your sandbox data while you're building.

Pulling Financial Reports

Rillet has been adding financial report endpoints through early 2026. The current set includes:

# Balance sheet
GET /reports/balance-sheet

# Trial balance
GET /reports/trial-balance

# Income statement
GET /reports/income-statement

# Cash flow statement
GET /reports/cash-flow-statement

All four support subsidiary_id and breakdown_by parameters for multi-entity setups. The trial balance returns beginning balance, debits, credits, and ending balance per account. The income statement and cash flow statement both accept a date range. There's also a reporting journal entries endpoint (GET /reports/journal-entries) that returns amounts converted to the subsidiary's reporting currency — useful for multi-currency consolidations.

The Unified API Alternative: Apideck's Rillet Connector

If you're building a product that needs to support multiple accounting platforms and Rillet is one of them, there's a faster path than building a direct integration from scratch.

Apideck now supports Rillet as a connector through the Unified Accounting API. You can use a single API to read and write data across Rillet, QuickBooks, Xero, NetSuite, Sage, and 30+ other accounting systems.

The trade-off is the same as any abstraction layer: you get breadth and speed at the cost of some depth. The Unified API covers the core accounting objects (invoices, payments, customers, journal entries, chart of accounts) that most integrations need. If your product requires Rillet-specific features like the financial report endpoints or the MCP server, you'll still want the direct integration described above.

For many use cases, starting with Apideck's connector and adding direct Rillet API calls where you need deeper functionality is the pragmatic move. Build once, connect to every accounting platform your customers use, and go deeper on Rillet where it matters.

A Minimal Integration Example

To tie this all together, here's a minimal Node.js integration that fetches invoices from Rillet:

import fetch from 'node-fetch';

const BASE_URL = 'https://api.rillet.com';
const API_KEY = process.env.RILLET_API_KEY;
const headers = {
  'Authorization': `Bearer ${API_KEY}`,
  'X-Rillet-API-Version': '3',
};

async function syncInvoices() {
  const invoices = [];
  let cursor = null;

  do {
    const url = new URL(`${BASE_URL}/invoices`);
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);

    const response = await fetch(url.toString(), { headers });

    if (!response.ok) {
      const error = await response.json().catch(() => ({}));
      throw new Error(`Rillet error: ${error.detail ?? response.status}`);
    }

    const data = await response.json();
    invoices.push(...data.data);
    cursor = data.pagination?.next_cursor ?? null;
  } while (cursor);

  return invoices;
}

// Usage
const invoices = await syncInvoices();
console.log(`Fetched ${invoices.length} invoices`);

Summary

The Rillet API is well-designed for a relatively new platform. A few things stand out: the OpenAPI-first approach means you can generate typed clients, updated_at timestamps across most entities make incremental sync viable (check entity-by-entity which ones support updated.gt filtering), and the MCP server is a genuinely useful addition for teams using AI coding tools.

The main things to get right from the start are version pinning, idempotency keys on write operations, webhook signature verification, and using a decimal library for monetary arithmetic. Get those four right and the rest is just building out the specific data flows your product needs.

If you need to support Rillet alongside other accounting platforms, Apideck's Unified Accounting API covers the core objects through a single integration. For Rillet-specific depth, the direct API is the way to go.

For the full API reference, see docs.api.rillet.com and the changelog for what's new.

How to Integrate Your App with QuickBooks Online: A Complete Guide for 2026

Kate Apideck — Thu, 18 Jun 2026 13:45:59 +0000

You've decided to integrate QuickBooks Online into your app. Good call — it's the accounting platform your customers actually use. Now comes the part nobody warns you about: there's a big difference between getting it working in a sandbox and shipping something real.

This guide covers the full path from initial setup to production, including the parts Intuit's documentation glosses over: getting production OAuth approval, keeping tokens alive, syncing data reliably, and what the Intuit App Partner Program actually means for your costs.

If you want the technical deep-dive on specific APIs, check out:

This post is about architecture decisions, production readiness, and what the integration actually costs you to build and maintain.

What You're Building

Before writing a line of code, nail down which type of integration you need.

Push-only integrations write data into QuickBooks from your system — creating invoices when deals close, syncing payments from your payment processor, creating expense records from employee submissions. These are mostly POST operations, which are free under Intuit's current pricing regardless of volume.

Pull integrations read data from QuickBooks — syncing the chart of accounts, pulling transaction history, fetching reconciliation data. These are GET operations (CorePlus API calls), which are metered starting at 500,000 calls/month on the free tier.

Bidirectional sync does both. This is the most common real-world requirement and the most complex to implement correctly, especially around conflict resolution when both systems can modify the same record.

Knowing which type you need determines your architecture, your costs under the Intuit App Partner Program, and how much operational complexity you're signing up for.

The OAuth 2.0 Flow

QuickBooks uses OAuth 2.0 with a few quirks worth knowing before you build.

Setting Up

Create your app at developer.intuit.com. You get two sets of credentials:

Development: Works with sandbox companies only. No approval needed.
Production: Works with real QuickBooks accounts. Requires app assessment (more on this later).

Set your redirect URIs in the app settings. In development, http://localhost is fine. In production, you need HTTPS — no exceptions.

The Authorization Flow

// Step 1: Redirect user to QuickBooks consent page
const authUrl = `https://appcenter.intuit.com/connect/oauth2?
  client_id=${CLIENT_ID}
  &response_type=code
  &scope=com.intuit.quickbooks.accounting
  &redirect_uri=${encodeURIComponent(REDIRECT_URI)}
  &state=${generateSecureState()}`;

res.redirect(authUrl);

// Step 2: Handle the callback
app.get('/callback', async (req, res) => {
  const { code, realmId, state } = req.query;

  // Validate state to prevent CSRF
  if (state !== getStoredState()) {
    return res.status(400).send('State mismatch');
  }

  const tokens = await exchangeCodeForTokens(code, realmId);
  await saveTokens(realmId, tokens);
  res.redirect('/dashboard');
});

// Step 3: Exchange code for tokens
async function exchangeCodeForTokens(code, realmId) {
  const response = await fetch('https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64')}`,
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code,
      redirect_uri: REDIRECT_URI
    })
  });

  const { access_token, refresh_token, expires_in } = await response.json();

  return {
    accessToken: access_token,
    refreshToken: refresh_token,
    expiresAt: Date.now() + (expires_in * 1000),
    realmId
  };
}

Token Lifecycle Management

This is where most integrations break in production. Access tokens expire after 60 minutes. Refresh tokens for the com.intuit.quickbooks.accounting scope have a maximum validity of 5 years (as of Intuit's updated November 2025 policy — previously they were rolling with no hard expiry as long as used every 100 days).

What this means practically:

Build proactive token refresh (refresh before expiry, not after a 401)
Tokens will eventually reach their 5-year hard expiry — build a reconnection flow for when that happens
Store the refresh_token_expiry value returned in the token response to know when a user will need to reauthorize

async function getValidAccessToken(realmId) {
  const tokens = await getStoredTokens(realmId);

  // Refresh if within 5 minutes of expiry
  if (tokens.expiresAt - Date.now() < 5 * 60 * 1000) {
    return await refreshAccessToken(realmId, tokens.refreshToken);
  }

  return tokens.accessToken;
}

async function refreshAccessToken(realmId, refreshToken) {
  const response = await fetch('https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64')}`,
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      refresh_token: refreshToken
    })
  });

  if (!response.ok) {
    await markConnectionExpired(realmId);
    throw new Error('TOKEN_EXPIRED');
  }

  const { access_token, refresh_token, expires_in } = await response.json();

  await saveTokens(realmId, {
    accessToken: access_token,
    refreshToken: refresh_token,
    expiresAt: Date.now() + (expires_in * 1000)
  });

  return access_token;
}

Store tokens in a database, not in memory or session storage. Index by realmId (the QuickBooks company ID). One user can have multiple companies.

Making API Calls

The base URL differs between sandbox and production:

const BASE_URL = process.env.NODE_ENV === 'production'
  ? 'https://quickbooks.api.intuit.com'
  : 'https://sandbox-quickbooks.api.intuit.com';

async function qboRequest(realmId, method, path, body = null) {
  const accessToken = await getValidAccessToken(realmId);

  const response = await fetch(
    `${BASE_URL}/v3/company/${realmId}${path}?minorversion=75`,
    {
      method,
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: body ? JSON.stringify(body) : null
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new QBOError(error, response.status);
  }

  return response.json();
}

Always include minorversion=75 in your requests. This pins you to a specific API version so Intuit's schema changes don't silently break your integration.

Data Sync Patterns

The hardest part of a QBO integration isn't the API calls — it's keeping data consistent between two systems.

Initial Sync

For a new connection, you need to pull all historical data. QuickBooks uses a SQL-like query language with pagination:

async function syncAllInvoices(realmId) {
  let startPosition = 1;
  const pageSize = 1000; // Max allowed
  let hasMore = true;

  while (hasMore) {
    const result = await qboRequest(
      realmId,
      'GET',
      `/query?query=SELECT * FROM Invoice STARTPOSITION ${startPosition} MAXRESULTS ${pageSize}`
    );

    const invoices = result.QueryResponse?.Invoice || [];
    await upsertInvoices(realmId, invoices);

    hasMore = invoices.length === pageSize;
    startPosition += pageSize;
  }
}

For large accounts, this can take a while. Run it as a background job, not in the request lifecycle.

Incremental Sync

After the initial sync, only pull records modified since your last sync:

async function syncRecentInvoices(realmId, lastSyncTime) {
  const since = lastSyncTime.toISOString().split('.')[0];

  const result = await qboRequest(
    realmId,
    'GET',
    `/query?query=SELECT * FROM Invoice WHERE MetaData.LastUpdatedTime >= '${since}'`
  );

  return result.QueryResponse?.Invoice || [];
}

Store the last successful sync time per-company in your database. If a sync fails partway through, rerun from the last checkpoint.

Conflict Resolution with SyncToken

QuickBooks uses SyncToken for optimistic locking. Any update must include the current SyncToken or QuickBooks rejects it with error code 5010 (stale object):

async function updateInvoice(realmId, invoiceId, changes) {
  // Fetch current version to get SyncToken
  const current = await qboRequest(realmId, 'GET', `/invoice/${invoiceId}`);
  const invoice = current.Invoice;

  const response = await qboRequest(realmId, 'POST', '/invoice', {
    ...invoice,
    ...changes,
    Id: invoiceId,
    SyncToken: invoice.SyncToken,
    sparse: true
  });

  return response.Invoice;
}

If you get 5010, refetch and retry.

Webhooks

Polling for changes works but burns through your CorePlus API quota. Use webhooks for real-time updates.

In the Intuit Developer Portal, go to your app → Webhooks and register your endpoint.

app.post('/webhooks/quickbooks', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['intuit-signature'];
  const payload = req.body;

  if (!verifyWebhookSignature(payload, signature)) {
    return res.status(401).send('Invalid signature');
  }

  // Respond immediately — Intuit disables slow endpoints
  res.status(200).send('OK');

  // Process async
  processWebhookPayload(JSON.parse(payload)).catch(console.error);
});

function verifyWebhookSignature(payload, signature) {
  const computed = crypto
    .createHmac('sha256', WEBHOOK_VERIFIER_TOKEN)
    .update(payload)
    .digest('base64');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computed)
  );
}

async function processWebhookPayload(payload) {
  for (const notification of payload.eventNotifications) {
    const { realmId, dataChangeEvent } = notification;
    for (const entity of dataChangeEvent.entities) {
      await queueSyncJob(realmId, entity.name, entity.id, entity.operation);
    }
  }
}

Two non-negotiables: verify the signature (Intuit will disable your webhooks if you skip this), and respond with 200 before doing any processing.

Webhooks tell you what changed, not the new value. You still need to fetch the updated record via API. They can also arrive out of order or be delayed by hours during incidents. Design sync logic to be idempotent, and run a periodic poll as a fallback.

Getting to Production

Moving from sandbox to production requires Intuit's approval — this is where teams get surprised.

The App Assessment

Before you can use production credentials, you need to complete Intuit's app assessment:

Security questionnaire: How you store tokens, your data retention policy, whether you're SOC 2 compliant
Use case review: What your app does, which APIs you use, who your users are
Demo: For some apps, Intuit wants to see it working
Terms of Service: Developer TOS plus the Intuit App Partner Program terms

Budget 1-3 weeks. Fill in the questionnaire thoroughly and you'll get through it.

The Intuit App Partner Program

Once approved, your tier determines API costs:

Tier	Monthly Fee	CorePlus Calls Included	Overage Rate
Builder	Free	500,000	Blocked
Silver	$300	1,000,000	$3.50/1k
Gold	$1,700	Higher allocation	Better rates
Platinum	$4,500	Up to 75M	$0.25/1k

Core (write) API calls are free at every tier. For most apps, Builder is fine at launch.

Listing on the Intuit App Store

Optional but worth it — the App Store is a real distribution channel. Customers searching for integrations inside QuickBooks can find your app.

To list:

Get production access (app assessment must be complete)
Build a landing page with a clear description, privacy policy, and support contact
Submit for App Store review in the developer portal
Pass a UX review: Intuit checks that your OAuth flow is clean

Being listed also signals legitimacy to enterprise buyers doing procurement reviews.

The Apideck Alternative

Everything above is the native path. It works, but it takes weeks to build and requires ongoing maintenance — complexity that scales with each additional accounting platform your customers use.

Apideck's Unified Accounting API handles OAuth, token management, data normalization, and rate limit handling for QuickBooks and 30+ other platforms through a single integration.

Native vs Apideck

Native QuickBooks:

// You're managing:
// OAuth 2.0 + CSRF, token storage + refresh (60-min access token expiry,
// 5-year refresh token maximum), reconnection flows, sandbox vs prod routing,
// QBO data model (SyncToken, DetailType, ItemRef nesting), CorePlus quota
// tracking, platform-specific error codes, webhook signature verification,
// pagination, minorversion pinning, app assessment + App Store listing...
// ...multiplied by every additional accounting platform you add later

const invoice = await qboRequest(realmId, 'POST', '/invoice', {
  CustomerRef: { value: customerId },
  Line: lineItems.map(item => ({
    Amount: item.qty * item.price,
    DetailType: 'SalesItemLineDetail',
    SalesItemLineDetail: {
      ItemRef: { value: item.productId },
      Qty: item.qty,
      UnitPrice: item.price
    }
  })),
  DueDate: dueDate
});

With Apideck:

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

const apideck = new Apideck({
  apiKey: process.env.APIDECK_API_KEY,
  appId: process.env.APIDECK_APP_ID
});

// Same code works for QuickBooks, Xero, NetSuite, Sage
const { data } = await apideck.accounting.invoices.add({
  consumerId: userId,
  serviceId: 'quickbooks', // swap to 'xero' or 'netsuite' anytime
  invoice: {
    customer_id: customerId,
    line_items: lineItems.map(item => ({
      description: item.name,
      quantity: item.qty,
      unit_price: item.price
    })),
    due_date: dueDate
  }
});

Apideck's Vault handles the OAuth flow. You embed a pre-built UI component, users connect their QuickBooks account, and Apideck manages credentials from there.

Build native if: QuickBooks is the only platform you'll ever need, you have deep customization requirements, or you have the bandwidth to build and maintain it.

Use Apideck if: You'll need more than one accounting integration, you want to ship in days rather than weeks, or you'd rather not manage OAuth infrastructure.

For most B2B SaaS companies, QuickBooks is first but not last. The second integration is when teams switch to a unified API.

Common Production Issues

Token expiry during long-running jobs: If a background sync exceeds 60 minutes, your access token expires mid-job. Refresh proactively before starting any long operation, and handle token refresh inside your sync loop.

Multiple company files: One QuickBooks user can have multiple companies. Don't assume one user = one realmId.

Sandbox vs production data divergence: Sandbox data resets periodically. Your integration needs to handle IDs that exist in sandbox but not production.

Rate limits at scale: 500 requests per minute per company seems generous until you're doing an initial sync for a customer with a decade of transaction history. Implement request queuing and respect Retry-After headers.

Webhook reliability: Intuit webhooks can be delayed by hours during incidents. Don't rely on them as your only sync mechanism.

Next Steps

If you're going native:

Create your developer account at developer.intuit.com
Set up a sandbox company and test your OAuth flow
Build and test sync logic against sandbox data
Complete the app assessment to get production credentials
Submit for App Store listing

If you're using Apideck:

Sign up and get your API key
Embed Vault for OAuth
Start calling the Unified Accounting API

The investment is real either way. So is the payoff — QuickBooks integration is a checklist item on a lot of procurement reviews, and having it is often the difference between winning and losing deals in the verticals where QuickBooks dominates.

Related guides:

How to integrate the QuickBooks Invoice API in 2026

Kate Apideck — Mon, 25 May 2026 22:15:04 +0000

Building invoicing into your app sounds straightforward—until you open the QuickBooks API docs.

Nested objects three levels deep. Fields named SalesItemLineDetail inside DetailType inside Line. A SyncToken you need to track for every update. Error code 5010 when someone else touched the record 200ms before you did.

The QuickBooks Invoice API is powerful, but it wasn't designed for developers who just want to create an invoice and move on.

This guide covers both paths:

The native approach — Full endpoint reference, working code examples, and the gotchas that'll save you hours of debugging
The unified API approach — How to reduce 100+ lines of QuickBooks-specific code to 20 lines that work across QuickBooks, Xero, NetSuite, and 30+ other accounting platforms

Whether you're building a direct integration or evaluating unified APIs, you'll walk away knowing exactly what QuickBooks invoicing requires under the hood.

QuickBooks Invoice API Overview

Before diving in, make sure you have your QuickBooks API credentials set up. If you're evaluating whether to build this integration yourself or use a unified API, check out our QuickBooks API pricing breakdown to understand the costs involved.

The QuickBooks Invoice API lets you programmatically:

Create and send invoices
Add line items with products/services
Apply discounts and taxes
Track payment status
Send payment reminders
Void or delete invoices
Query invoice history

API Endpoints

Operation	Method	Endpoint
Create	POST	`/v3/company/{realmId}/invoice`
Read	GET	`/v3/company/{realmId}/invoice/{invoiceId}`
Update	POST	`/v3/company/{realmId}/invoice`
Delete	POST	`/v3/company/{realmId}/invoice?operation=delete`
Void	POST	`/v3/company/{realmId}/invoice?operation=void`
Send	POST	`/v3/company/{realmId}/invoice/{invoiceId}/send`
Query	GET	`/v3/company/{realmId}/query?query=SELECT * FROM Invoice`

Base URLs:

Production: https://quickbooks.api.intuit.com
Sandbox: https://sandbox-quickbooks.api.intuit.com

Note: Updates use the same endpoint as create. The distinction is in the request body—updates must include Id and SyncToken fields. Working with QuickBooks Desktop instead? See our QuickBooks Desktop integration guide.

Creating Invoices with the Native API

Basic Invoice

const createInvoice = async (realmId, accessToken) => {
  const invoice = {
    CustomerRef: {
      value: "123" // Customer ID
    },
    Line: [
      {
        Amount: 150.00,
        DetailType: "SalesItemLineDetail",
        SalesItemLineDetail: {
          ItemRef: {
            value: "1",
            name: "Consulting Services"
          },
          Qty: 3,
          UnitPrice: 50.00
        },
        Description: "Strategy consulting - 3 hours"
      }
    ],
    DueDate: "2024-02-15"
  };

  const response = await fetch(
    `https://quickbooks.api.intuit.com/v3/company/${realmId}/invoice?minorversion=75`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify(invoice)
    }
  );

  return response.json();
};

Invoice with Multiple Line Items

const invoice = {
  CustomerRef: { value: "123" },
  Line: [
    {
      Amount: 500.00,
      DetailType: "SalesItemLineDetail",
      SalesItemLineDetail: {
        ItemRef: { value: "1" },
        Qty: 10,
        UnitPrice: 50.00
      },
      Description: "Development services"
    },
    {
      Amount: 200.00,
      DetailType: "SalesItemLineDetail",
      SalesItemLineDetail: {
        ItemRef: { value: "2" },
        Qty: 4,
        UnitPrice: 50.00
      },
      Description: "Design services"
    }
  ],
  DueDate: "2024-02-15",
  PrivateNote: "Internal note: Rush project"
};

Invoice with Discount and Tax

const invoiceWithDiscountAndTax = {
  CustomerRef: { value: "123" },
  Line: [
    {
      Amount: 1000.00,
      DetailType: "SalesItemLineDetail",
      SalesItemLineDetail: {
        ItemRef: { value: "1" },
        Qty: 10,
        UnitPrice: 100.00,
        TaxCodeRef: { value: "TAX" }
      }
    },
    {
      Amount: 100.00,
      DetailType: "DiscountLineDetail",
      DiscountLineDetail: {
        PercentBased: true,
        DiscountPercent: 10,
        DiscountAccountRef: { value: "86" }
      }
    }
  ],
  TxnTaxDetail: {
    TxnTaxCodeRef: { value: "2" },
    TotalTax: 74.25 // (1000 - 100) * 8.25%
  }
};

Reading and Querying Invoices

Get Single Invoice

const getInvoice = async (realmId, invoiceId, accessToken) => {
  const response = await fetch(
    `https://quickbooks.api.intuit.com/v3/company/${realmId}/invoice/${invoiceId}?minorversion=75`,
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Accept': 'application/json'
      }
    }
  );

  return response.json();
};

Query Examples

QuickBooks uses a SQL-like query syntax with some limitations:

Supported: WHERE, LIKE (% wildcard only), ORDER BY, IN, AND, comparison operators, STARTPOSITION, MAXRESULTS

Not supported: OR, NOT, JOIN, GROUP BY, projections (selecting specific fields)

// Unpaid invoices
const query = "SELECT * FROM Invoice WHERE Balance > '0' ORDER BY DueDate";

// Customer's invoices
const query = `SELECT * FROM Invoice WHERE CustomerRef = '${customerId}'`;

// Overdue invoices
const today = new Date().toISOString().split('T')[0];
const query = `SELECT * FROM Invoice WHERE DueDate < '${today}' AND Balance > '0'`;

// Date range (note: use single quotes for values)
const query = `SELECT * FROM Invoice WHERE TxnDate >= '2024-01-01' AND TxnDate <= '2024-01-31'`;

// With pagination (default: 100 results, max: 1000)
const query = `SELECT * FROM Invoice STARTPOSITION 1 MAXRESULTS 200`;

Updating Invoices

QuickBooks uses sparse updates—send only changed fields plus Id and SyncToken. Updates use the same endpoint as create; the presence of Id and SyncToken signals an update operation:

const updateInvoice = async (realmId, invoice, accessToken) => {
  const updatePayload = {
    Id: invoice.Id,
    SyncToken: invoice.SyncToken, // Required for optimistic locking
    sparse: true,
    DueDate: "2024-03-01"
  };

  const response = await fetch(
    `https://quickbooks.api.intuit.com/v3/company/${realmId}/invoice?minorversion=75`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(updatePayload)
    }
  );

  return response.json();
};

Note: Even with sparse updates, some operations may still require CustomerRef and Line items depending on what you're changing.

Sending and Managing Invoices

Send via Email

const sendInvoice = async (realmId, invoiceId, email, accessToken) => {
  const url = email
    ? `https://quickbooks.api.intuit.com/v3/company/${realmId}/invoice/${invoiceId}/send?sendTo=${email}`
    : `https://quickbooks.api.intuit.com/v3/company/${realmId}/invoice/${invoiceId}/send`;

  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/octet-stream'
    }
  });

  return response.json();
};

Auto-Send on Creation

To automatically email an invoice when creating it, set EmailStatus to NeedToSend. Note that BillEmail is required when using this option:

const invoice = {
  CustomerRef: { value: "123" },
  BillEmail: { Address: "customer@example.com" }, // Required when EmailStatus is NeedToSend
  EmailStatus: "NeedToSend", // Options: NotSet, NeedToSend, EmailSent
  Line: [/* ... */]
};

Void an Invoice

const voidInvoice = async (realmId, invoice, accessToken) => {
  const response = await fetch(
    `https://quickbooks.api.intuit.com/v3/company/${realmId}/invoice?operation=void`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        Id: invoice.Id,
        SyncToken: invoice.SyncToken
      })
    }
  );

  return response.json();
};

Reconciling Payments

Once invoices are sent, you'll need to record payments against them. QuickBooks uses a separate Payment API that links payments to invoices through the LinkedTxn object.

Record a Full Payment

To record a payment against an invoice, create a Payment object that references the invoice:

const recordPayment = async (realmId, invoiceId, amount, customerId, accessToken) => {
  const payment = {
    CustomerRef: { value: customerId },
    TotalAmt: amount,
    Line: [
      {
        Amount: amount,
        LinkedTxn: [
          {
            TxnId: invoiceId,
            TxnType: "Invoice"
          }
        ]
      }
    ]
  };

  const response = await fetch(
    `https://quickbooks.api.intuit.com/v3/company/${realmId}/payment?minorversion=75`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json',
        'Accept': 'application/json'
      },
      body: JSON.stringify(payment)
    }
  );

  return response.json();
};

Partial Payments

QuickBooks supports partial payments—just set the Amount to less than the invoice total:

const recordPartialPayment = async (realmId, invoiceId, partialAmount, customerId, accessToken) => {
  const payment = {
    CustomerRef: { value: customerId },
    TotalAmt: partialAmount,
    Line: [
      {
        Amount: partialAmount,
        LinkedTxn: [
          {
            TxnId: invoiceId,
            TxnType: "Invoice"
          }
        ]
      }
    ]
  };

  const response = await fetch(
    `https://quickbooks.api.intuit.com/v3/company/${realmId}/payment?minorversion=75`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payment)
    }
  );

  return response.json();
};

After recording a partial payment, the invoice's Balance field will reflect the remaining amount due.

Payment Against Multiple Invoices

A single payment can be applied across multiple invoices:

const payment = {
  CustomerRef: { value: "123" },
  TotalAmt: 1500.00,
  Line: [
    {
      Amount: 1000.00,
      LinkedTxn: [{ TxnId: "invoice-1", TxnType: "Invoice" }]
    },
    {
      Amount: 500.00,
      LinkedTxn: [{ TxnId: "invoice-2", TxnType: "Invoice" }]
    }
  ]
};

Apply Credits to Invoices

If a customer has credits (from overpayments or credit memos), you can apply them to invoices:

const applyCredit = async (realmId, invoiceId, creditMemoId, amount, customerId, accessToken) => {
  const payment = {
    CustomerRef: { value: customerId },
    TotalAmt: 0, // Zero when applying credits only
    Line: [
      {
        Amount: amount,
        LinkedTxn: [{ TxnId: invoiceId, TxnType: "Invoice" }]
      },
      {
        Amount: amount,
        LinkedTxn: [{ TxnId: creditMemoId, TxnType: "CreditMemo" }]
      }
    ]
  };

  const response = await fetch(
    `https://quickbooks.api.intuit.com/v3/company/${realmId}/payment?minorversion=75`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payment)
    }
  );

  return response.json();
};

Query Payment Status

Check if an invoice has been paid by querying its Balance field or by finding linked payments:

// Find all payments for an invoice
const query = `SELECT * FROM Payment WHERE Line.LinkedTxn.TxnId = '${invoiceId}'`;

// Or check invoice balance directly
const invoice = await getInvoice(realmId, invoiceId, accessToken);
const isPaid = invoice.Invoice.Balance === 0;
const isPartiallyPaid = invoice.Invoice.Balance > 0 && 
                        invoice.Invoice.Balance < invoice.Invoice.TotalAmt;

With Apideck

Apideck normalizes payment recording across all accounting platforms:

// Record a payment
const { data } = await apideck.accounting.payments.add({
  consumerId,
  serviceId: 'quickbooks',
  payment: {
    customer_id: customerId,
    total_amount: 500.00,
    transaction_date: new Date().toISOString(),
    allocations: [
      {
        type: 'invoice',
        id: invoiceId,
        amount: 500.00
      }
    ]
  }
});

// List payments for a customer
const { data: payments } = await apideck.accounting.payments.all({
  consumerId,
  serviceId: 'quickbooks',
  filter: { customer_id: customerId }
});

Before & After: Native QuickBooks vs. Apideck

Here's where developer experience really matters. Building invoicing with the native API requires understanding QuickBooks-specific concepts. With Apideck, you use a clean, normalized model that works across QuickBooks, Xero, NetSuite, and 30+ other accounting platforms.

Before: Native QuickBooks Invoice Creation

// The full picture of what you need to manage

class QuickBooksInvoiceService {
  constructor() {
    this.auth = new QuickBooksAuth();
  }

  async createInvoice(customerData, lineItems, options = {}) {
    // 1. Handle authentication
    const accessToken = await this.auth.getAccessToken();
    const realmId = await this.auth.getRealmId();

    // 2. Transform your data to QuickBooks format
    const qbInvoice = {
      CustomerRef: { value: customerData.id },
      Line: lineItems.map((item, index) => ({
        // QuickBooks requires Amount at line level
        Amount: item.quantity * item.unitPrice,
        // Must specify DetailType exactly
        DetailType: "SalesItemLineDetail",
        SalesItemLineDetail: {
          // ItemRef is required and must exist in QuickBooks
          ItemRef: {
            value: item.productId,
            name: item.productName // Optional but helps debugging
          },
          Qty: item.quantity,
          UnitPrice: item.unitPrice,
          // TaxCodeRef uses QuickBooks-specific codes
          TaxCodeRef: item.taxable ? { value: "TAX" } : { value: "NON" }
        },
        Description: item.description,
        LineNum: index + 1
      })),
      // Date format must be YYYY-MM-DD
      DueDate: this.formatDate(options.dueDate || this.addDays(new Date(), 30)),
      TxnDate: this.formatDate(options.invoiceDate || new Date()),
      // QuickBooks calls this DocNumber (max 21 characters)
      DocNumber: options.invoiceNumber,
      // Private note vs customer memo are different fields
      PrivateNote: options.internalMemo, // Internal only, up to 4000 chars
      CustomerMemo: options.customerNote ? { value: options.customerNote } : undefined,
      // Email handling - BillEmail required if EmailStatus is NeedToSend
      BillEmail: customerData.email ? { Address: customerData.email } : undefined,
      EmailStatus: options.sendImmediately ? "NeedToSend" : "NotSet"
    };

    // 3. Handle tax if applicable
    if (options.taxRate) {
      qbInvoice.TxnTaxDetail = {
        TxnTaxCodeRef: { value: options.taxCodeId },
        TotalTax: this.calculateTax(lineItems, options.taxRate)
      };
    }

    // 4. Make the API call
    const response = await fetch(
      `https://quickbooks.api.intuit.com/v3/company/${realmId}/invoice?minorversion=75`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'Content-Type': 'application/json',
          'Accept': 'application/json'
        },
        body: JSON.stringify(qbInvoice)
      }
    );

    // 5. Handle QuickBooks-specific errors
    if (!response.ok) {
      const error = await response.json();
      const qbError = error.Fault?.Error?.[0];

      switch (qbError?.code) {
        case '6140':
          throw new Error(`Duplicate document number: ${options.invoiceNumber}`);
        case '6240':
          throw new Error(`Duplicate name exists (customer/vendor/employee)`);
        case '610':
          throw new Error(`Customer not found: ${customerData.id}`);
        case '2500':
          throw new Error(`Invalid item reference in line items`);
        case '5010':
          throw new Error('Stale data - invoice was modified. Refetch and retry.');
        default:
          throw new Error(`QuickBooks error: ${qbError?.Message || 'Unknown'}`);
      }
    }

    const result = await response.json();

    // 6. Send email if requested (already handled via EmailStatus, but can also call send endpoint)
    if (options.sendImmediately && !qbInvoice.EmailStatus) {
      await this.sendInvoice(result.Invoice.Id, customerData.email);
    }

    // 7. Transform response back to your format
    return this.transformFromQuickBooks(result.Invoice);
  }

  formatDate(date) {
    return date.toISOString().split('T')[0];
  }

  addDays(date, days) {
    const result = new Date(date);
    result.setDate(result.getDate() + days);
    return result;
  }

  calculateTax(lineItems, taxRate) {
    const taxableAmount = lineItems
      .filter(item => item.taxable)
      .reduce((sum, item) => sum + (item.quantity * item.unitPrice), 0);
    return taxableAmount * taxRate;
  }

  transformFromQuickBooks(qbInvoice) {
    return {
      id: qbInvoice.Id,
      invoiceNumber: qbInvoice.DocNumber,
      customerId: qbInvoice.CustomerRef.value,
      status: qbInvoice.Balance > 0 ? 'open' : 'paid',
      total: qbInvoice.TotalAmt,
      balance: qbInvoice.Balance,
      dueDate: qbInvoice.DueDate,
      createdAt: qbInvoice.MetaData.CreateTime,
      // ... more field mapping
    };
  }
}

Pain points:

100+ lines for basic invoice creation
QuickBooks-specific field names (DetailType, SalesItemLineDetail, etc.)
Manual date formatting
Complex nested object structure
Platform-specific error codes to handle
Transform data in and out

After: With Apideck

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

const apideck = new Apideck({
  apiKey: process.env.APIDECK_API_KEY,
  appId: process.env.APIDECK_APP_ID
});

// Create invoice - clean, intuitive API
const createInvoice = async (consumerId, invoiceData) => {
  const { data } = await apideck.accounting.invoices.add({
    consumerId,
    serviceId: 'quickbooks', // Switch to 'xero' or 'netsuite' anytime
    invoice: {
      customer_id: invoiceData.customerId,
      invoice_number: invoiceData.invoiceNumber,
      invoice_date: invoiceData.date,
      due_date: invoiceData.dueDate,
      memo: invoiceData.memo,
      line_items: invoiceData.items.map(item => ({
        name: item.name,
        description: item.description,
        quantity: item.quantity,
        unit_price: item.unitPrice,
        tax_rate_id: item.taxRateId
      }))
    }
  });

  return data;
};

// List invoices with filters
const getUnpaidInvoices = async (consumerId) => {
  const { data } = await apideck.accounting.invoices.all({
    consumerId,
    serviceId: 'quickbooks',
    filter: {
      status: 'open'
    }
  });

  return data;
};

// Get single invoice
const getInvoice = async (consumerId, invoiceId) => {
  const { data } = await apideck.accounting.invoices.one({
    consumerId,
    serviceId: 'quickbooks',
    id: invoiceId
  });

  return data;
};

// Update invoice
const updateInvoice = async (consumerId, invoiceId, updates) => {
  const { data } = await apideck.accounting.invoices.update({
    consumerId,
    serviceId: 'quickbooks',
    id: invoiceId,
    invoice: updates
  });

  return data;
};

// Delete invoice
const deleteInvoice = async (consumerId, invoiceId) => {
  await apideck.accounting.invoices.delete({
    consumerId,
    serviceId: 'quickbooks',
    id: invoiceId
  });
};

Code Comparison

Aspect	Native QuickBooks	Apideck
Lines of code	100+	20
Auth handling	Manual (50+ lines)	Automatic
Data transformation	Required (both ways)	None needed
Error handling	Platform-specific codes	Unified errors
Multi-platform	Complete rewrite	Change `serviceId`
Learning curve	QuickBooks docs	One unified API

Real-World Example: CRM to Invoice

Native approach:

// When deal closes, create invoice - native QuickBooks
async function onDealWon(deal) {
  const qbAuth = new QuickBooksAuth();
  const accessToken = await qbAuth.getAccessToken();
  const realmId = await qbAuth.getRealmId();

  // First, find or create customer in QuickBooks
  let customer = await findQuickBooksCustomer(deal.company.email, accessToken, realmId);

  if (!customer) {
    const customerResponse = await fetch(
      `https://quickbooks.api.intuit.com/v3/company/${realmId}/customer?minorversion=75`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          DisplayName: deal.company.name,
          PrimaryEmailAddr: { Address: deal.company.email },
          CompanyName: deal.company.name
        })
      }
    );
    customer = (await customerResponse.json()).Customer;
  }

  // Then create the invoice
  const invoice = {
    CustomerRef: { value: customer.Id },
    Line: deal.products.map(p => ({
      Amount: p.quantity * p.price,
      DetailType: "SalesItemLineDetail",
      SalesItemLineDetail: {
        ItemRef: { value: mapProductToQBItem(p.id) },
        Qty: p.quantity,
        UnitPrice: p.price
      }
    })),
    DueDate: formatDate(addDays(new Date(), 30))
  };

  const response = await fetch(
    `https://quickbooks.api.intuit.com/v3/company/${realmId}/invoice?minorversion=75`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(invoice)
    }
  );

  // Handle errors, send email, etc...
}

With Apideck:

// When deal closes, create invoice - with Apideck
async function onDealWon(deal) {
  // Create customer if needed
  const { data: customer } = await apideck.accounting.customers.add({
    consumerId: deal.accountId,
    serviceId: 'quickbooks',
    customer: {
      display_name: deal.company.name,
      company_name: deal.company.name,
      email: deal.company.email
    }
  }).catch(async (err) => {
    // If customer exists, find them
    if (err.status === 409) {
      return apideck.accounting.customers.all({
        consumerId: deal.accountId,
        serviceId: 'quickbooks',
        filter: { email: deal.company.email }
      });
    }
    throw err;
  });

  // Create invoice
  const { data: invoice } = await apideck.accounting.invoices.add({
    consumerId: deal.accountId,
    serviceId: 'quickbooks',
    invoice: {
      customer_id: customer.id,
      line_items: deal.products.map(p => ({
        description: p.name,
        quantity: p.quantity,
        unit_price: p.price
      })),
      due_date: addDays(new Date(), 30).toISOString()
    }
  });

  return invoice;
}

Common Error Handling

QuickBooks Error Codes Reference

Error Code	Message	Solution
6000	Business Validation Error	Check required fields
6140	Duplicate Document Number	Use unique DocNumber
6240	Duplicate Name Exists	Customer/vendor/employee name already exists
610	Object Not Found	Customer or Item invalid
5010	Stale Object	Refresh SyncToken and retry
2500	Invalid Reference	Referenced entity doesn't exist

With Apideck

Errors are normalized across all platforms:

try {
  await apideck.accounting.invoices.add({ ... });
} catch (error) {
  if (error.status === 400) {
    // Validation error - check error.detail
  } else if (error.status === 404) {
    // Customer or item not found
  } else if (error.status === 409) {
    // Duplicate invoice number
  }
}

Get Started

Choosing between native integration and a unified API? Consider your long-term roadmap. If you'll need multiple accounting integrations, the unified approach saves significant engineering time.

Native QuickBooks

Register at developer.intuit.com
Create an app
Implement OAuth flow
Learn QuickBooks data model
Build integration
Handle edge cases

Timeline: 2-4 weeks

With Apideck

Sign up at apideck.com
Get API key
Use Vault for OAuth
Start making API calls

Timeline: 1 day

// You're ready to go
const apideck = new Apideck({ apiKey, appId });

const { data } = await apideck.accounting.invoices.add({
  consumerId: 'user-123',
  serviceId: 'quickbooks',
  invoice: {
    customer_id: 'cust-456',
    line_items: [{ description: 'Services', quantity: 1, unit_price: 1000 }]
  }
});

console.log('Invoice created:', data.id);

Start building with Apideck →

Related:

QuickBooks guides:

Accounting integrations:

Platform comparisons:

Understanding Tracking Dimensions in Accounting Integrations

Kate Apideck — Thu, 21 May 2026 15:43:14 +0000

If you're building accounting integrations, you've likely encountered a common challenge: your customers want to segment their financial data by department, location, project, or business unit—but every accounting platform handles this differently.

QuickBooks calls them "Classes." Xero uses "Tracking Categories." NetSuite has departments, locations, subsidiaries, AND classes. Intuit's new Enterprise Suite supports up to 20 custom dimensions. Sage Intacct offers eight.

In this post, we'll break down how tracking dimensions work across major accounting platforms and show you how to build integrations that handle these differences gracefully.

What Are Tracking Dimensions?

Tracking dimensions are metadata tags attached to accounting transactions that enable segmented reporting. Think of them as labels that let finance teams answer questions like:

"What's our P&L for the Marketing department?"
"How much revenue did the New York office generate?"
"What are the expenses for Project Alpha?"

Most accounting platforms support some combination of four dimension types:

Dimension	Purpose	Examples
Department	Organizational unit or cost center	Marketing, Sales, Engineering
Location	Physical or logical place	NYC Office, London, Online Store
Subsidiary	Legal entity in multi-company setup	US Holdings Inc, UK Ltd
Tracking Category	Flexible custom tags	Project Alpha, Grant #12345

The Challenge: Every Platform Is Different

Here's where it gets interesting. Each accounting platform implements tracking dimensions differently:

Xero: Keep It Simple (Maybe Too Simple)

Xero takes a minimalist approach—you get exactly two tracking categories per organization. That's it. No departments, no locations, no subsidiaries.

{
  "tracking_categories": [
    { "id": "region-uuid", "name": "North America" },
    { "id": "dept-uuid", "name": "Sales" }
  ]
}

Many Xero users work around this by creating one tracking category for "Department" and another for "Region." It works, but requires careful planning since you can't add a third dimension later.

QuickBooks Online: The Naming Confusion

QuickBooks supports departments, locations, AND classes—but there's a catch. In QuickBooks, "Department" often functions more like what other systems call "Location" (tracking by branch or region).

{
  "department_id": "58",
  "location_id": "1",
  "tracking_categories": [
    { "id": "5000000000000026437", "name": "Enterprise" }
  ]
}

Also, these features aren't enabled by default. Your customers need to turn on "Track locations" and "Track classes" in their QuickBooks settings.

NetSuite OneWorld: All The Dimensions

NetSuite goes all-in with full support for departments, locations, subsidiaries, and classes. The tradeoff? Complexity.

{
  "department_id": "3",
  "location_id": "1",
  "subsidiary_id": "2",
  "tracking_categories": [
    { "id": "1", "name": "Class A" }
  ]
}

For NetSuite OneWorld (multi-subsidiary) accounts, subsidiary_id is often required. Transactions without a valid subsidiary get rejected. Your integration needs to handle this gracefully.

Intuit Enterprise Suite: The Modern Approach

Intuit Enterprise Suite (IES) is Intuit's new mid-market offering, and it takes a fundamentally different approach than QuickBooks. Instead of fixed dimension types, IES supports up to 20 custom dimensions with unlimited values and 5 levels of hierarchy.

{
  "dimensions": [
    { "type": "Department", "value": { "id": "dept-001" } },
    { "type": "Location", "value": { "id": "loc-001" } },
    { "type": "Project", "value": { "id": "proj-001" } },
    { "type": "CostCenter", "value": { "id": "cc-001" } }
  ]
}

IES vs QuickBooks Online:

Feature	QuickBooks Online	Intuit Enterprise Suite
Custom dimensions	3 fixed	Up to 20
Hierarchy depth	2 levels	5 levels
Multi-entity	No	Yes (native)
Shared dimensions	N/A	Across entities

If your customers are outgrowing QuickBooks, IES is often the next step—and your integration needs to handle the richer dimension model.

Sage Intacct: Maximum Flexibility

Sage Intacct supports up to eight custom dimensions plus the standard ones. Great for complex enterprise requirements, but it means more edge cases to handle.

Building Integrations That Handle The Differences

Here's our recommended approach for building robust accounting integrations:

1. Always Discover Dimensions First

Before writing transactions with tracking data, query what dimensions are available:

// Fetch available dimensions for the connected account
const departments = await accounting.departments.list();
const locations = await accounting.locations.list();
const trackingCategories = await accounting.trackingCategories.list();

This tells you:

Which dimensions exist in this account
What valid IDs you can use
How the customer has configured their tracking

2. Handle Missing Support Gracefully

Not every connector supports every dimension. Your code should check before including fields:

const invoice = {
  customer_id: customerId,
  line_items: lineItems
};

// Only include tracking if supported
if (connectorSupports('departments')) {
  invoice.department_id = departmentId;
}

if (connectorSupports('tracking_categories')) {
  invoice.tracking_categories = categories;
}

For connector-specific fields that aren't in the unified model, you can use pass_through to send them directly to the downstream API.

3. Use Line Items for Mixed Tracking

Real-world invoices often span multiple departments or projects. Most platforms support tracking at the line item level:

{
  "customer_id": "cust-123",
  "line_items": [
    {
      "description": "Sales consulting",
      "department_id": "sales",
      "tracking_categories": [{ "id": "project-a" }]
    },
    {
      "description": "Technical implementation",
      "department_id": "engineering",
      "tracking_categories": [{ "id": "project-a" }]
    }
  ]
}

Line item values override header values, giving you granular control.

4. Validate Subsidiary Requirements

For enterprise platforms like NetSuite and Sage Intacct, check if subsidiary is required:

if (serviceId === 'netsuite') {
  const subsidiaries = await accounting.subsidiaries.list();
  if (subsidiaries.data.length > 1 && !transaction.subsidiary_id) {
    throw new Error('subsidiary_id is required for multi-subsidiary accounts');
  }
}

5. Cache Dimension Lists

Tracking dimensions change infrequently. Cache them to avoid unnecessary API calls:

const departments = await cache.getOrSet(
  `departments:${consumerId}:${serviceId}`,
  () => accounting.departments.list(),
  { ttl: 3600 } // 1 hour
);

Quick Reference: Connector Support Matrix

Here's what each major platform supports:

Connector	Departments	Locations	Subsidiaries	Tracking Categories
NetSuite	✅	✅	✅	✅
Sage Intacct	✅	✅	✅	✅
Intuit Enterprise Suite	✅	✅	—	✅ (up to 20)
QuickBooks Online	✅	✅	—	✅
Workday	✅	—	✅	—
Dynamics 365 BC	—	✅	—	✅
Xero	—	—	—	✅
MYOB	—	—	—	✅

For complete coverage details, see our Accounting API page.

Common Pitfalls to Avoid

"Invalid department_id" errors: Always verify IDs exist by listing dimensions first. Departments can be archived or restricted to certain subsidiaries.

Xero's two-category limit: This is organization-wide, not per-transaction. Help customers plan their category usage upfront.

QuickBooks features not enabled: If tracking fails, check whether the customer has enabled Classes and Locations in their QuickBooks settings.

NetSuite subsidiary requirements: For OneWorld accounts, subsidiary is usually mandatory. Query subsidiaries and require selection if multiple exist.

Wrapping Up

Tracking dimensions are essential for meaningful financial reporting, but the implementation varies wildly across platforms. The key is building integrations that:

Discover available dimensions dynamically
Handle missing support gracefully
Validate requirements before submitting transactions
Cache dimension lists for performance

For the complete technical reference with curl examples and API details, see our Tracking Dimensions Developer Guide.

Building accounting integrations? Apideck's Unified Accounting API normalizes tracking dimensions across 25+ connectors, so you can write code once and support them all.

DEV Community: Kate Apideck

How to Integrate with the MYOB API

What is the MYOB Business API?

Why integrate with MYOB?

Registration and API keys

Authentication: the March 2025 changes

New granular scopes

Admin-only authorization

Company file GUID retrieval

Token lifecycle

Key API endpoints

Contacts

Sales

Purchases

General Ledger

Inventory

Request headers and versioning

Data mapping considerations

Invoice structure

Tax codes

Account mapping

Currency

Error handling and rate limits

Rate limiting

OData filtering

Deprecation: AccountRight Classic

Testing your integration

Unified API approach

Frequently asked questions

Can I access multiple company files with one integration?

Does MYOB support webhooks?

What happens when AccountRight releases a new version?

Can I email invoices through the API?

What's the difference between AccountRight and MYOB Business?

Next steps

How to Integrate with the Odoo API

How Odoo's API Works

Authentication

Core API Methods

search_read

create

write

unlink

execute_kw with custom methods

Accounting Module: Key Models

Invoices and Bills — account.move

Invoice Lines — account.move.line

Payments — account.payment

Chart of Accounts — account.account

Contacts — res.partner

Working with the JSON-RPC Interface

Working with the Native REST API (Odoo 17+)

Authentication

Reading Records (GET)

Creating Records (POST)

Calling Methods

The JSON-2 API (Odoo 19+)

Pagination and Performance

Handling Odoo Versions

Error Handling

Webhooks and Real-time Sync

Using a Unified API Instead

Wrapping Up

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

The full picture: types of financial statements

Why the gaps exist

Real use cases that depend on clean financial statement data

Building it yourself vs. using a unified API

What to evaluate in a financial statement API provider

Where this is heading

How to Integrate With the Pennylane API

What the API covers

Authentication

Setting up a sandbox

Making your first request

Working with invoices

Pagination and filtering

Tracking changes

Rate limits

Key differences from v1

`search_read`

`create`

`write`

`unlink`

`execute_kw` with custom methods

Invoices and Bills — `account.move`

Invoice Lines — `account.move.line`

Payments — `account.payment`

Chart of Accounts — `account.account`

Contacts — `res.partner`