Overview
An API decision can look technical while determining business continuity, security exposure and operating cost for years. When Odoo becomes a system of record, integration leaders need more than an endpoint description. They need to know where the Odoo JSON-2 API fits, which controls it inherits and which risks remain outside the protocol.
Introduced in Odoo 19, JSON-2 is the strategic direction for new Odoo integration work. It gives external systems an HTTP interface to public Odoo model methods with JSON requests, named arguments and standard HTTP status behavior. Every operation still runs through Odoo’s business models, permissions and transaction rules.
This no-code guide translates the official Odoo documentation into architecture decisions. It covers capabilities, authentication, plan implications, transactions, Odoo data governance and migration from older APIs.
The executive decision in one view
The Odoo JSON-2 API is a strong default for a new supported integration against Odoo 19 or later. The decision still requires five checks before design approval.
| Leadership question | Decision test |
|---|---|
| Is the interface available? | Confirm the Odoo edition, hosting model, version and subscription plan before estimating delivery. |
| Who owns the connection? | Assign a dedicated integration identity with only the permissions and company access the interface requires. |
| What must be atomic? | Put each all-or-nothing business operation behind one Odoo method because separate API calls cannot share a transaction. |
| Who owns each field? | Define the source of truth, transformation rule, validation owner and reconciliation process. |
| How will the interface change? | Maintain a versioned contract, regression tests, monitoring and an upgrade review tied to the Odoo roadmap. |
These questions make the API part of the operating model.
What the Odoo JSON-2 API can do
JSON-2 exposes public Odoo model methods through a consistent route structure. External applications can search, read, create or update records. They can also invoke suitable business methods. Requests use named JSON arguments. Successful calls return the method result while failed calls use an HTTP error status with a serialized error object.
Odoo’s model layer represents the business system behind its user interface. Method availability therefore does not mean every method is appropriate for every integration. A callable operation may require context that a generic connector does not understand. Start with the business event and required outcome. Select the model and method afterward.
Odoo provides dynamic documentation for the active database at /doc. Installed applications, custom modules and version-specific changes determine the real interface. Use this documentation for discovery but maintain a reviewed contract for production consumers.
End-to-end Odoo integration flow
A reliable Odoo integration is a controlled journey from a business event to a reconciled outcome. The following architecture map keeps ownership visible from beginning to end.
| Stage | What happens | Control that leaders should require |
| 1. Business event | A sale, shipment, payment, customer change or scheduled extract creates demand for data exchange. | Named process owner and measurable service expectation. |
| 2. Intake | Middleware or an integration service receives the event and validates its shape. | Contract validation, duplicate detection and durable queueing where needed. |
| 3. Identity and routing | The service presents an API key and targets the correct Odoo database. | Managed secret, approved database mapping and separate nonproduction credentials. |
| 4. Authorization | Odoo applies the integration user’s access rights, record rules and field access. | Least-privilege role plus explicit multi-company tests. |
| 5. Business execution | Odoo runs the selected public model method with the supplied arguments and context. | Approved method catalogue and server-side orchestration for atomic workflows. |
| 6. Transaction outcome | Odoo commits a successful call or discards the failed call. | Idempotency design, bounded retries and clear permanent-error handling. |
| 7. Confirmation | The response returns to the integration layer and is correlated with the originating event. | Correlation ID, redacted logs and business-readable status. |
| 8. Reconciliation | Operations verify that both systems agree and exceptions reach an owner. | Control totals, exception queue, alert threshold and audit evidence. |
This flow shows why a direct point-to-point call can hide the controls that make an interface dependable.
Authentication is an identity design decision
Odoo JSON-2 API authentication uses an API key as a bearer token. The key belongs to an Odoo user. Odoo validates each operation against that user’s access rights, record rules and field access. The security model is user-centered.
Create a dedicated user for each meaningful trust boundary. A portal connector should not share an identity with a warehouse platform or finance feed. Separate identities reduce the blast radius of a leaked credential and allow one integration to be suspended without stopping another.
The operating standard should cover key creation, storage, rotation, revocation and incident response. Keep keys in a managed secrets service and never log the authorization header. Record the owners, purpose, environments and permitted companies for each credential. Test rotation before go-live.
Database routing and environment separation
The database is supplied through X-Odoo-Database only when multiple databases are available for one domain. In other deployments the domain or server configuration may resolve it. Document the actual routing rule.
Production, testing and development should use different addresses and API keys. Where one domain exposes several databases, allowlist the expected value and reject anything else. Monitoring should record a safe environment identifier.
Run contract tests against an environment close enough to production to reveal model, field, permission and method differences.
Access-plan implications belong in the business case
Odoo states that external API data access is available only on Custom pricing plans and not on One App Free or Standard plans. Subscription eligibility is therefore an architecture prerequisite.
Confirm entitlement before approving an estimate. A plan change may affect cost across licensed users rather than only the interface budget. Include subscription impact, platform, implementation, custom work, testing, monitoring, support and upgrades in the business case.
Validate the current agreement because plan names and policies can change. If external access is unavailable, revisit the plan, scope or approved deployment model.
Transaction behavior changes the solution shape
The most important technical constraint is also easy to miss: every JSON-2 call runs in its own SQL transaction. Odoo commits the transaction when the call succeeds and discards it when the call fails. Separate calls cannot be chained into one shared transaction.
If a system creates an order in one call and confirms it in another, the first change remains committed when the second call fails. A retry may duplicate data or meet an unexpected state. The business transaction does not match the call boundary.
When steps must succeed or fail together, expose one reviewed server-side business method that completes them in one call. When steps may settle at different times, use explicit states, idempotency keys, retry limits and compensation rules.
Idempotency, retries and reconciliation
Networks can fail after a request is sent but before its response arrives. The caller cannot assume that no Odoo change occurred.
Use a stable external identifier so repeated events are recognized. Decide whether a retry returns the prior outcome, updates a record or enters manual review. Retry transient failures with controlled backoff. Do not retry permanent errors until their cause changes.
Reconcile event counts, totals, states or checkpoints between systems. Route differences to an owner and retain evidence. Technical success means a response arrived. Business success means the intended transaction exists once with the right values and state.
Odoo data governance must precede field mapping
Each integrated data element needs a source of truth, owner, quality rule, retention expectation and permitted purpose. A customer email may belong to CRM while tax status belongs to finance. Writing in both directions without ownership rules creates silent conflict.
Build a contract that identifies the Odoo model and field, external equivalent, transformation, mandatory status, classification and validation response. Include custom fields and external IDs. Define deletion behavior and redaction for sensitive information.
A field, module, record rule or company configuration can change the effective interface without changing its URL. Review contract changes and keep regression tests aligned with supported scenarios.
Multi-company access needs scenario testing
An API call uses its user’s permissions and company context. This affects visibility, default values, fiscal behavior and allowed operations. Broad access may expose too much while narrow access may produce confusing empty results.
Create an access matrix by interface, company, model and operation. Test positive cases and deliberate denials. Confirm the company on created records and test relevant intercompany flows.
Do not solve access problems with administration rights. Correct the group, record rule, company assignment or design. Least privilege also helps prevent records from crossing legal-entity boundaries.
Performance and reporting architecture
Use the API for bounded operational exchanges rather than as a reporting database. Limit fields, filter at the source, page large results and batch where supported. Use queues to smooth bursts. Measure latency, failures, backlog age and call volume.
For Odoo reporting, decide whether users need live views, management reporting or cross-system history. Native Odoo reporting and spreadsheet capabilities may suit live analysis. A warehouse may be better for high-volume history. Preserve definitions, timestamps and company boundaries.
For Odoo AI integration services, provide an approved data product rather than unrestricted API access. Apply purpose limits, redaction, freshness rules and traceability.
Migration from XML-RPC or JSON-RPC
Odoo’s current version 19 documentation marks the older /xmlrpc, /xmlrpc/2 and /jsonrpc endpoints for removal in Odoo 22 and Odoo Online 21.1. JSON-2 is the replacement direction. Integration leaders should treat that as a portfolio migration program rather than a search-and-replace exercise.
Inventory interfaces, owners, schedules, credentials, methods, volumes and criticality. Retire unused connections. For each retained interface compare authentication, argument conventions, error handling and transaction assumptions. Check dynamic documentation for model changes.
Migrate in risk order. Low-impact reads can prove the platform. Revenue, inventory and payment flows need stronger testing and reconciliation. Run old and new paths together only when duplicate writes are prevented. Define cutover criteria and recovery steps. Then revoke legacy credentials and remove obsolete jobs.
Choosing the right delivery pattern
| Requirement | Preferred pattern | Reason |
| Real-time record exchange | JSON-2 through a managed integration service | Supports governed operational reads and writes with standard HTTP outcomes. |
| Multi-step all-or-nothing workflow | One purpose-built Odoo business method | Aligns the API boundary with one database transaction. |
| Large historical ERP migration | Controlled migration pipeline with staging and reconciliation | Separates transformation, validation and cutover controls from normal online traffic. |
| Enterprise analytics | Governed reporting layer or warehouse | Avoids turning the operational API into a bulk reporting engine. |
| AI-enabled process | Curated service with approved tools and data scope | Limits exposure and preserves traceability around AI actions. |
Choose the pattern during implementation architecture. Teams can combine Odoo integration services with ERP data migration services under one governance model. The Odoo API integration guide adds context while performance optimization services address scale. Govern dependencies within the wider Odoo implementation services plan.
Integration leader’s approval checklist
Before production use, require evidence that:
The version, hosting model and API entitlement are confirmed.
A business owner and technical owner are named.
The dedicated user has least-privilege access.
Secrets are stored, rotated and revoked through a documented process.
Every atomic business outcome fits within one API call.
External identifiers, duplicate handling and retry rules are defined.
Data ownership, transformations and retention are approved.
Performance tests reflect expected volume and peak bursts.
Monitoring covers latency, failures, backlog and reconciliation.
Upgrade tests and a legacy API migration date are in the roadmap.
Conclusion
The Odoo JSON-2 API modernizes the external interface but the protocol alone does not make an integration secure or scalable. Its value appears when leaders align identity, transactions, data ownership, performance and lifecycle governance around the business process.
The decisive rule is simple: one API call is one transaction. Build atomic operations around that boundary and use asynchronous states when work spans systems. Confirm the Custom-plan implication before committing the budget. Give each connection a dedicated identity.
For existing XML-RPC or JSON-RPC connections, begin with portfolio discovery and business criticality. A phased move with reconciliation and clear cutover gates reduces technical debt without avoidable operational risk.
Frequently Asked Questions
1. What is the Odoo JSON-2 API?
The Odoo JSON-2 API is Odoo 19’s external HTTP interface. Authorized systems call public model methods with named JSON arguments. It uses standard HTTP behavior and replaces legacy RPC interfaces.
2. Is the Odoo JSON-2 API available on every pricing plan?
No. Odoo’s official documentation states that external API data access is available on Custom pricing plans and not on One App Free or Standard plans. Confirm the target contract and deployment before estimating an integration because commercial terms can change.
3. How does Odoo JSON-2 API authentication work?
The client sends an API key as a bearer token. Odoo applies the associated user’s access rights, record rules and field access. Use a dedicated least-privilege identity.
4. Does one Odoo JSON-2 API call equal one transaction?
Yes. Odoo documents that each call runs in its own SQL transaction. A successful call is committed and a failed call is discarded. Separate calls cannot share one transaction so an all-or-nothing workflow should be performed by one approved server-side business method.
5. Must existing XML-RPC and JSON-RPC integrations migrate?
Yes if they must remain supported beyond the documented removal milestones. Odoo’s current version 19 documentation schedules legacy endpoints for removal in Odoo 22 and Odoo Online 21.1. Inventory each interface and migrate it according to business risk rather than translating every call mechanically.
6. How should multi-company access be governed?
Assign only the required companies to the integration user and document access by company, model and operation. Test allowed and denied scenarios as well as defaults on created records. Avoid administrator access because broad rights can hide company-routing defects and increase exposure.
7. Is JSON-2 suitable for reporting, AI and data migration?
It can support bounded data exchange for all three areas but it should not automatically become the entire architecture. Large migrations need staging and reconciliation. High-volume reporting may need a governed analytics layer. AI use requires curated data, purpose controls and traceability. Select the pattern from workload and governance needs rather than protocol availability.
