Bexio API Integration Challenges: ID-Based Data, Swiss VAT Rules, Immutable Invoices & Marketplace Auth
- Lennart Svensson
- 5 days ago
- 4 min read
Bexio is one of the leading cloud accounting platforms in Switzerland, widely used by SMEs for invoicing, bookkeeping, payroll, and VAT reporting. The system is deeply aligned with Swiss accounting standards and local tax regulations, making it a central tool in the daily financial operations of many Swiss companies.
For software vendors operating in the Swiss market, integrating with bexio is often essential to automate invoice synchronization, contact management, payment reconciliation, and tax-compliant financial data exchange. In this article, you will learn where engineering teams typically run into friction when building a direct bexio integration and how Maesn abstracts these complexities. We will show how reference mapping, VAT logic, authentication flows, and lifecycle constraints can be handled in a scalable way, so your product stays accounting-agnostic and ready to expand beyond Switzerland.
Key Takeaways
Bexio is ID-driven. You must resolve internal IDs (salutation, country, VAT, accounts) before creating objects, which means extra API calls and mapping logic.
Swiss VAT is different. Reverse charge (“Bezugssteuer”) and tenant-specific VAT codes require correct tax + account combinations or the API will reject your request.
Invoice states are strict. Once booked, invoices become immutable. Corrections require credit notes. Sync must be lifecycle-aware.
OAuth + OIDC are both required. OAuth for API access. OpenID Connect if you want Marketplace listing — two auth layers, not one.
Marketplace affects commercial setting. Revenue sharing and formal partner requirements influence your pricing, provisioning, and product setup.
Maesn abstracts the complexity. Unified ID handling, tax mapping, lifecycle normalization, and centralized authentication keep your product ERP-agnostic and scalable.
ID-Based Reference Data: Creating Objects Requires Lookup & Mapping Logic
In the bexio API, you cannot simply send readable values like "Mr." or "CH" when creating contacts or invoices. Instead, you must provide internal numeric IDs such as salutation_id, country_id, VAT IDs, account IDs, and others.
This means you need additional API calls to fetch reference data, implement local caching, and build mapping logic from human-readable values to bexio’s internal identifiers. Many teams underestimate this effort and end up building a reference synchronization layer instead of focusing on their actual product features.
Maesn removes most of this ID resolution complexity in a structured way.
For static reference values such as salutation or country, you simply send the semantic value and Maesn handles the internal ID mapping per tenant automatically.
For tenant-specific objects like VAT codes, your customers configure the mapping between their bexio VAT IDs (via the GET /taxRates endpoint) and your product’s tax categories during onboarding. This setup ensures flexibility without hardcoding assumptions.
Our bexio documentation and team guide you clearly on which mappings are required per endpoint, so you always know what needs to be configured and what is abstracted away.
Swiss VAT & Reverse Charge (“Bezugssteuer”) Logic Is Structurally Different
Switzerland is not part of the EU VAT system. Reverse charge is handled as Bezugssteuer, often requiring specific VAT codes and accounting postings — not just vat=0. VAT codes are tenant-configured and strictly validated in bexio. The wrong combination of VAT, account or customer type can cause hard API failures or incorrect bookkeeping. If you already support EU tax logic, you cannot simply reuse it.
Maesn abstracts tax intent (domestic, export, reverse charge) and maps it correctly to Swiss VAT configuration without you embedding country-specific branches.
Invoice Lifecycle Constraints: Booked Means Immutable
In bexio, invoices move through strict accounting states (Draft → Sent → Booked → Paid → Credited). Once booked, core fields become immutable and corrections require credit notes. Many integrations fail by attempting updates on already booked invoices or by ignoring partial payments and linked accounting entries. You need lifecycle-aware sync logic and clear system-of-record rules.
OAuth 2.0 for API + OpenID Connect for Marketplace: Two Auth Layers to for a Bexio Integration
For API access, bexio uses OAuth 2.0. That already requires secure token storage, automatic refresh handling, multi-tenant isolation and re-auth flows. But if you want to be listed in the bexio Marketplace, you must also implement OpenID Connect (OIDC) for SSO login via bexio. That means two auth layers, additional identity validation and more operational complexity.
Maesn unified authentication across all accounting systems so you don’t have to worry about OAuth + OIDC.
Marketplace Business Model: Billing & Revenue Sharing Can Affect Your Margins
If you become a bexio Marketplace Partner, revenue sharing and service fees may apply depending on the partnership model. This does not only impact finance - it can influence your pricing strategy, subscription setup, and go-to-market decisions. Before committing to the Marketplace route, make sure you understand how billing flows and fee structures affect your business model. For more details, see the official bexio Marketplace video or get in touch our team.
Marketplace Partner Requirements: Technical + Product Readiness Is Mandatory
Bexio does not list every integration automatically. To become a Marketplace Partner, there are formal requirements:
You have at least 10 bexio customers (SMEs or fiduciaries) in your client base.
Your app has at least 20 active users who use it regularly.
You have a clearly defined target audience.
Your app provides a user-friendly integration for bexio users.
You ensure multilingualism (DE, FR, IT, EN): Your app is available in at least two languages, and for the marketplace application, you provide content in all four languages.
You commit to developing an integration with the bexio API and OpenID Connect.
You provide customer support for bexio users of your app and integration.
You sign the marketplace partner agreement.
Maesn accelerates readiness by providing a stable, standardized integration layer and supports you in your partnership process with bexio.
