Odoo 20 Integration Upgrade: Migrating from RPC to JSON-2

Introduction

An Odoo upgrade can become complicated when external applications depend on legacy APIs.

eCommerce platforms may create sales orders, shipping systems may update deliveries, mobile applications may retrieve customer information and third-party reporting tools may read Odoo data. If these systems rely on older XML-RPC or JSON-RPC services, an Odoo 20 upgrade is an important opportunity to review the entire integration architecture.

The good news is that not every legacy RPC integration breaks immediately in Odoo 20.

The important change is that Odoo has removed the db service in Odoo 20, while the common and object services remain available for now but have a published retirement path. Odoo's External JSON-2 API is the modern replacement.

This creates a migration window for businesses to move from legacy RPC integrations to a more modern, secure, testable and maintainable API architecture.

What Is Changing in Odoo 20?

Odoo's current documentation states that the external XML-RPC and JSON-RPC APIs are deprecated, with JSON-2 acting as their replacement.

However, the retirement is happening in stages:

The db service was removed in Odoo 20. The common and object services are currently scheduled for removal in Odoo 22. This means most integrations using execute or execute_kw may continue to work during an Odoo 20 upgrade, but they should still be included in the migration roadmap.

This distinction is critical for upgrade planning.

Odoo 20 is not necessarily an immediate “rewrite every integration” release. It is the right time to start the migration before the remaining RPC services reach their removal deadline.

Why Should Businesses Migrate From RPC to JSON-2?

Legacy integrations can continue working during a transition period, but maintaining an API that has a defined retirement path creates future technical debt.

A planned migration provides an opportunity to:

• inventory existing integrations

• remove obsolete API calls

• improve authentication

• reduce excessive permissions

• standardize error handling

• improve retry logic

• review custom methods

• test business workflows

• improve monitoring

• prepare for future Odoo versions

The objective should not be to migrate APIs simply because the technology is newer.

The objective is to build an integration architecture that can be maintained through future Odoo upgrades.

1. Start With an Odoo Integration Call Inventory

Before changing code, identify every application that communicates with Odoo.

Do not search only for xmlrpc or jsonrpc.

Review:

• External applications

• Custom connectors

• Mobile applications

• eCommerce integrations

• Shipping integrations

• Payment systems

• Marketplace connectors

• Reporting tools

• Scheduled scripts

• Middleware

• Automation platforms

• Custom integrations

For every integration, record:

This becomes your Odoo API migration inventory.

2. Identify the RPC Services You Actually Use

The first technical distinction to make is whether your integration uses the db, common, or object service.

The db service handles database-management operations such as creating, duplicating, dropping, backing up, restoring and listing databases. It was removed in Odoo 20.

The common service provides functions such as:

• version()

• login()

• authenticate()

The object service provides methods such as:

• execute()

• execute_kw()

The latter services remain available in Odoo 20 but have a future removal path.

This means your migration priority should be based on actual API usage, not simply whether a project contains an XML-RPC library.

3. Understand How JSON-2 Works

JSON-2 exposes Odoo model methods through the /json/2 endpoint.

A request follows this structure:

POST /json/2/<model>/<method>

For example:

POST /json/2/res.partner/search_read

The request uses a Bearer API key through the Authorization header.

The request body contains JSON parameters such as:

• ids

• context

• method-specific arguments

Odoo's documentation also notes that the actual models, fields and methods available are specific to each database and can be reviewed through the database's /doc page.

This makes JSON-2 migration more than an endpoint replacement.

The integration needs to be redesigned around the new request and authentication model.

4. Review Authentication and API Keys

One of the biggest changes is authentication.

Legacy RPC integrations commonly use:

Database + User ID + Password

JSON-2 uses:

Bearer API Key

Odoo allows API keys to be created through:

Preferences → Account Security → New API Key

Keys have a description and expiration date and Odoo recommends secure storage, short lifetimes where appropriate and regular rotation. Manually created keys cannot have a duration longer than three months.

For automated integrations, consider using dedicated integration or bot users.

This makes it easier to:

• restrict permissions

• identify API activity

• revoke credentials

• rotate keys

• separate services

• reduce the impact of credential compromise

Never migrate a legacy integration to JSON-2 by simply giving it administrator-level access.

5. Map Every RPC Method to JSON-2

Create a method-mapping worksheet.

For each existing RPC call, document:

Legacy

model → method → arguments → response

Then map it to:

JSON-2

/json/2/model/method → named JSON arguments → response

For example:

One important difference is that JSON-2 does not support positional method arguments. Arguments are provided by name in the JSON request body.

Therefore, simply replacing the RPC URL will not complete the migration.

6. Review Custom Odoo Methods

Many Browseinfo-style integrations and enterprise connectors use custom Odoo methods rather than only generic ORM calls.

For example:

sync_marketplace_order()
calculate_shipping_rate()
create_external_invoice()
action_confirm_delivery()

Every custom method should be reviewed.

Check:

• Does the method still exist?

• Has its signature changed?

• Does it accept named arguments correctly?

• Does it enforce business rules?

• Does it return the expected response?

• Does it work with the integration user's permissions?

• Does it depend on another custom module?

This is where an Odoo 20 upgrade and API migration overlap.

The integration may be technically compatible while the underlying custom module is not.

7. Test Odoo Permissions

Authentication and authorization are different.

A valid API key only proves that the request can authenticate.

The user still needs appropriate Odoo permissions.

JSON-2 operations are evaluated against Odoo's standard:

• Access rights

• Record rules

• Field access

Odoo recommends dedicated bot users for long-running automated integrations so that only the required permissions are granted.

Test each integration with its real production-equivalent user.

Verify:

• Read permissions

• Create permissions

• Write permissions

• Delete permissions

• Field access

• Multi-company access

• Record rules

• Restricted business data

A successful administrator test does not prove that the integration is production-ready.

8. Design for Transaction Boundaries

JSON-2 introduces an important architectural consideration: each API call runs in its own SQL transaction.

A successful call commits its transaction, while an error rolls it back.

This means multiple consecutive API calls cannot be treated as one atomic transaction.

For example:

Create Order
      ↓
Create Delivery
      ↓
Register Payment

If each operation is performed through a separate API call, another transaction could modify data between those calls.

Odoo recommends using a single server-side method when several related operations must remain atomic.

For critical workflows, consider creating a dedicated Odoo method that performs the complete business operation in one transaction.

This can be safer than making several independent API calls from the external application.

9. Build Retry and Idempotency Controls

An API migration is also an opportunity to improve integration reliability.

External calls can fail because of:

• Network timeouts

• Temporary server errors

• Connection failures

• Validation errors

• Authentication failures

• Duplicate requests

Do not automatically retry every failed write operation.

For example, blindly retrying an order-creation request could potentially create duplicate transactions if the first request succeeded but the response was lost.

Use appropriate safeguards such as:

• External reference IDs

• Duplicate detection

• Idempotent operations

• Request tracking

• Controlled retry policies

• Reconciliation procedures

Separate:

Safe-to-retry errors

from:

Requires-investigation errors

10. Test the Complete Business Workflow

API testing should go beyond checking whether a request returns HTTP 200.

For example, test:

External Order

↓

JSON-2 Request

↓

Customer Validation

↓

Sales Order

↓

Inventory

↓

Delivery

↓

External Status

Also test failure scenarios:

• Invalid customer

• Missing product

• Insufficient stock

• Duplicate order

• Permission failure

• Invalid field

• Validation error

• Timeout

• Partial failure

The goal is to prove that the complete business process works not simply that the endpoint responds.

11. Consider Controlled Dual-Running

For business-critical integrations, a controlled migration is safer than an immediate production replacement.

A practical approach can be:

Legacy RPC → Production

JSON-2 → Development / Staging

After successful validation:

JSON-2 → Production

For read-only integrations, controlled parallel comparison can sometimes be useful.

For write operations, avoid allowing both old and new integrations to create production transactions simultaneously unless duplicate prevention and reconciliation are explicitly designed.

The migration strategy should depend on the business criticality of the integration.

12. Prepare a Rollback Strategy

Every API migration should have a documented rollback plan.

Define:

• Previous integration version

• New integration version

• Configuration changes

• API credentials

• Deployment procedure

• Rollback trigger

• Responsible owner

• Transaction reconciliation process

Rollback should not simply mean restoring old code.

You also need to determine what happened to transactions processed after the new integration was enabled.

A practical sequence might be:

Deploy JSON-2

↓

Monitor

↓

Issue Detected

↓

Disable New Integration

↓

Reconcile Transactions

↓

Restore Previous Version

This makes rollback a business continuity procedure rather than just a software deployment action.

13. Review Multi-Database Architecture

Some Odoo environments host multiple databases.

In those cases, JSON-2 may require the X-Odoo-Database header when the target database cannot be determined from the host configuration.

Review:

• Host configuration

• Reverse proxy

• Database filters

• Database routing

• X-Odoo-Database usage

Do not assume that database selection works the same way as it did in the legacy integration. Odoo documents the header requirements as part of the JSON-2 API configuration.

14. Use Database-Specific API Documentation

Odoo's /doc endpoint provides documentation for the models, fields and methods available in a specific database.

This is particularly useful for customized Odoo environments.

Before migrating an integration, verify:

• Model availability

• Method availability

• Method parameters

• Custom methods

• Custom fields

• Expected behavior

This can prevent a common migration mistake: developing against generic Odoo documentation while the production database contains significant customizations.

Odoo 20 RPC-to-JSON-2 Migration Worksheet

Use this worksheet for every external call:

This turns a broad migration project into a manageable call-by-call exercise.

Odoo 20 Integration Migration Checklist

Discovery

• Inventory every external integration

• Identify XML-RPC and JSON-RPC usage

• Identify db, common and object service usage

• Identify custom Odoo methods

• Identify critical write operations

Authentication

• Create dedicated integration users

• Generate API keys

• Store keys securely

• Define key expiration and rotation

• Remove obsolete credentials

Development

• Map legacy methods to JSON-2

• Convert positional arguments to named arguments

• Update authentication

• Update endpoints

• Review custom methods

• Improve error handling

• Implement safe retry logic

Security

• Apply least-privilege access

• Test record rules

• Test field access

• Test multi-company behavior

• Avoid administrator credentials

• Define key-revocation procedures

Testing

• Test read operations

• Test create operations

• Test update operations

• Test validation failures

• Test duplicate requests

• Test network failures

• Test permission failures

• Reconcile transactions

Deployment

• Define cutover strategy

• Consider controlled dual-running

• Monitor production behavior

• Define rollback criteria

• Reconcile transactions

• Retire legacy RPC dependencies according to the migration plan

Common Odoo 20 RPC-to-JSON-2 Migration Mistakes

Migrating Only the Endpoint

Changing an RPC URL to /json/2 does not complete the migration. Authentication, request structure, method arguments and error handling must also change.

Treating Odoo 20 as an Immediate RPC Shutdown

The db service is removed in Odoo 20, but the common and object services remain available until their planned removal. The migration should therefore be prioritized based on actual API usage.

Using Administrator Credentials

Highly privileged credentials increase the potential impact of a compromised integration. Use dedicated users with only the permissions required.

Ignoring Transaction Boundaries

Multiple JSON-2 calls do not automatically execute as one transaction. Critical multi-step operations may require a dedicated server-side method.

Testing Only Successful Requests

Real integrations fail because of permissions, validation, duplicates, timeouts and unexpected data. These scenarios must be tested before production.

Ignoring Custom Modules

Custom models and methods can represent a significant part of an Odoo integration. Review them as part of the upgrade.

Migrating Without a Rollback Plan

An integration migration can create real transactions. Code rollback without transaction reconciliation can leave Odoo and external systems inconsistent.

How Browseinfo Can Help With Odoo 20 Integration Migration

An API migration is not only a development task. It requires understanding the business processes, existing integrations, security model, custom modules, data flows and operational risks.

Browseinfo can help businesses audit legacy Odoo integrations, create API call inventories, map RPC methods to JSON-2, review authentication and permissions, test custom integrations, improve error handling and plan controlled production migration.

This approach can also be combined with broader Odoo implementation, Odoo integration, Odoo customization, Odoo upgrade and API integration services to create a more sustainable ERP architecture.

Frequently Asked Questions

1. What is JSON-2 in Odoo 20?

JSON-2 is Odoo's modern external API for accessing models and methods through HTTP. It uses /json/2/<model>/<method> endpoints and Bearer API-key authentication.

2. Are XML-RPC and JSON-RPC completely removed in Odoo 20?

No. The db service was removed in Odoo 20, while the common and object services remain available but are scheduled for removal in Odoo 22.

3. Do existing execute_kw integrations need immediate migration?

Not necessarily for Odoo 20, because the object service remains available during the transition. However, businesses should begin migrating these integrations before the planned Odoo 22 removal.

4. How does JSON-2 authentication work?

JSON-2 uses an API key supplied as a Bearer token in the Authorization header. Odoo recommends secure key storage, expiration, rotation and dedicated users for automated integrations.

5. Can JSON-2 use Odoo access rights and record rules?

Yes. JSON-2 operations are subject to Odoo's standard access rights, record rules and field-level access controls for the authenticated user.

6. Does JSON-2 support positional arguments?

No. JSON-2 uses named arguments in the JSON request body, so legacy RPC calls using positional arguments need to be mapped during migration.

7. Can multiple JSON-2 calls run in one transaction?

No. Each JSON-2 call runs in its own transaction, so related operations that must be atomic should be implemented in a single server-side method where appropriate.

8. Should businesses use a dedicated Odoo user for integrations?

Yes, dedicated bot or integration users are recommended for extended automated usage because they allow more precise permissions, auditing and credential management.

9. How should an Odoo 20 API migration be tested?

Test authentication, permissions, method mapping, successful transactions, validation errors, duplicate requests, timeouts, business rules, reconciliation and rollback before production cutover.

10. When should businesses start migrating from RPC to JSON-2?

The best time is during the Odoo 20 upgrade cycle, even when the existing common or object integration still works. Starting early provides time to test, run controlled migrations and avoid pressure before the planned Odoo 22 retirement.

Conclusion

Odoo 20 changes the timeline for external integrations, but it does not mean every legacy RPC integration suddenly stops working. The immediate change is the removal of the db service, while the common and object services remain available during a defined transition period.

For businesses, this is an opportunity to move beyond reactive API fixes. Inventory every integration, map every important method, review authentication and permissions, test business scenarios, improve retry and transaction handling and establish a controlled cutover and rollback strategy.

The goal should not simply be to make an existing connector work on Odoo 20. The goal is to build an integration architecture that is secure, maintainable, testable and ready for future Odoo releases.