← All articles

Blog

Odoo External API: JSON-RPC, XML-RPC and JSON-2 Compared

How to integrate Odoo with other systems via its external API: XML-RPC, JSON-RPC and the newer JSON-2, plus plan limits, API keys and migration advice.

7 min read
  • mid
  • odoo

If you want Odoo to exchange data with a webshop, a BI tool, a warehouse system or an internal app, you will use its external API. The short answer for 2026: build new integrations on the JSON-2 API (introduced in Odoo 19), and plan to move older XML-RPC and JSON-RPC integrations off the legacy endpoints before they are removed. The old endpoints still work today, but they are officially deprecated.

This guide covers what each API is, what it costs you in plan terms, how authentication works, and how to avoid the common integration mistakes.

The three APIs, in plain terms

Odoo exposes its models (customers, sales orders, invoices, stock moves) to outside programs. Over the years that has happened in three flavors.

APIEndpointStatus
XML-RPC/xmlrpc/2/common and /xmlrpc/2/objectDeprecated since Odoo 19
JSON-RPC/jsonrpcDeprecated since Odoo 19
JSON-2/json/2/model/methodCurrent, new in Odoo 19

All three give you the same underlying capability: read, create, update and delete records, and call model methods such as search_read, create, write and unlink. What changes is the wire format, the authentication, and how errors come back.

Odoo’s 20.0 documentation on the legacy RPC API marks the /xmlrpc, /xmlrpc/2 and /jsonrpc endpoints as deprecated since 19.0 and points to the External JSON-2 API as the replacement. Note that this deprecation concerns the generic external endpoints; custom controllers a developer writes with JSON-RPC routes are a separate matter.

Check your plan first

Before writing any code, confirm you are allowed to use the API. Odoo’s documentation states that access to data via the external API is only available on Custom Odoo pricing plans. In practice that means:

  • Odoo Online: you need the Custom plan. The One App Free and Standard plans do not include external API access.
  • Odoo.sh and on-premise: this plan restriction is tied to Odoo’s hosted pricing plans, so confirm your own contract terms with Odoo or your partner.

A surprising number of “the API doesn’t work” tickets come down to this. If authentication fails on an Online database, check the plan before debugging your code. Pricing and plan names change, so verify on Odoo’s current pricing page.

How authentication works

For the legacy XML-RPC route, you need four things: the server URL, the database name, a username and a password or API key. Since Odoo 14, an API key can replace the password in scripts, and the docs note that keys are shown only once and cannot be recovered if lost. On Odoo Online, users have no local password by default, so an administrator sets one or, better, you use an API key.

The legacy flow has two steps. You call authenticate on the common endpoint to get a user ID, then pass that ID with the credentials on every call to the object endpoint through execute_kw.

JSON-2 simplifies this. Per the JSON-2 documentation:

  • You send a POST request to /json/2/ followed by the model and method.
  • The API key goes in an Authorization: bearer header.
  • An optional X-Odoo-Database header names the database when the host serves several.
  • Arguments go in a JSON body as named fields, with ids and context as fixed fields.
  • Success returns HTTP 200 with the method’s JSON-serialized result.

Here is the shape of a call that lists a few customers:

curl -X POST https://your-odoo.example.com/json/2/res.partner/search_read \
  -H "Authorization: bearer YOUR_API_KEY" \
  -H "X-Odoo-Database: your_database" \
  -H "Content-Type: application/json" \
  -d '{"domain": [["is_company", "=", true]], "fields": ["name", "email"], "limit": 5}'

The same call under the legacy API needed the two-step login and positional arguments inside execute_kw. The named-argument style of JSON-2 is easier to read and to debug.

Each database also serves a /doc page where you can browse models and methods and try requests, according to a Dutch integrator’s summary of the 19 changes. Treat it as the fastest way to discover field names for your own customizations.

Why the move to JSON-2 matters

Three practical differences:

  1. Real HTTP status codes. Errors come back as 4xx or 5xx responses with a JSON error object, rather than a fault wrapped in a 200 response. Monitoring and retry logic become much simpler.
  2. Standard tooling. Any HTTP client works. No XML-RPC library is needed, which matters for no-code tools and modern front ends.
  3. A removal date. The deprecation is not just cosmetic. According to the 20.0 docs, the common and object services are scheduled for removal in Odoo 22 (fall 2028) and in Odoo Online 21.1 (winter 2027); the Dutch integrator’s summary says the same. The db service was already removed in Odoo 20 (fall 2026) and Online 19.1. Confirm the exact dates in Odoo’s own documentation before you commit to a timeline, since schedules can change.

If you are on Odoo 17 or 18 today, the legacy endpoints are your only option, and that is fine. Just keep the integration code isolated in one small module so the switch is a contained change at upgrade time.

Designing an integration that holds up

The API is the easy part. These are the decisions that determine whether an integration survives its first year.

Use a dedicated integration user. Create one technical user and one API key per integration. Give each only the access rights it needs. When a key leaks or a vendor relationship ends, you revoke one key and nothing else breaks. Never use an administrator’s personal key in a production connector.

Respect access rights and record rules. The API acts as the user who owns the key, so Odoo’s normal security applies. This is a feature, but it also explains why a call can work for an admin and fail for the integration user.

Make writes idempotent. Networks fail. If your webshop pushes an order and the response times out, you must be able to retry without creating a duplicate. Store the external order ID on the Odoo record, for example in a custom field or the ref, and search for it before creating.

Batch and filter on the server. Pull only what changed, using a domain filter on write_date and a limit, rather than downloading every record on a schedule. Pulling full tables hourly is the classic way to slow down a production database.

Log and alert. Record every failed call with the payload and the HTTP status. A silent integration failure usually surfaces weeks later as a reconciliation problem in finance.

Prefer events for time-sensitive flows. The external API is a request-response interface. For real-time needs, Odoo’s automated actions can call a webhook when a record changes, so the other system does not have to poll.

Build, buy or use a connector?

Not every integration needs custom code. A rough guide:

  • Standard connector exists and is maintained (common e-commerce platforms, payment providers, shipping carriers): use it, but check that it supports your Odoo version and who maintains it.
  • Low volume, simple mapping: a small script or an integration platform calling JSON-2 is usually enough.
  • High volume, complex rules, or business-critical: a purpose-built service with queueing, retries and monitoring is worth the cost.

Whichever you choose, ask one question about any connector: does it use the deprecated endpoints? A connector built on XML-RPC may be fine today and need work at your next major upgrade.

A migration checklist for existing integrations

If you already have XML-RPC or JSON-RPC integrations, a sensible order of work is:

  1. Inventory. List every system that talks to Odoo, including forgotten scripts and third-party tools. Server logs showing requests to /xmlrpc will find the stragglers.
  2. Separate credentials. Move each integration to its own user and API key.
  3. Rewrite calls to JSON-2. The method names stay the same; the transport, authentication and argument style change.
  4. Handle errors by HTTP status. Update your retry and alerting logic.
  5. Test against a staging copy of the database before cutting over.
  6. Do it with an upgrade. Combine the migration with your next version upgrade rather than waiting for a deadline.

Where we can help

If you are planning an Odoo integration, or you have inherited a tangle of scripts that nobody wants to touch, we are happy to look at it with you. We can review what you have, tell you what is worth keeping, and sketch an approach, with no charge for the first conversation. Reach out through our contact page whenever it suits you.


Sources: Odoo 18 documentation, External API; Odoo 20 documentation, External RPC API (deprecated); Odoo 20 documentation, External JSON-2 API; Xyphen IT, Odoo 19 XML-RPC deprecated. Plan limits, endpoints and removal dates change between releases; verify against Odoo’s current documentation and pricing before you build.