Odoo API Integration Guide: REST, XML-RPC, and When to Use Which

Almost every integration project I take on starts the same way: a client already has something connected to Odoo — usually built by a previous developer or a no-code tool — and it breaks in a way nobody can diagnose because nobody actually understands which of Odoo's several API mechanisms it's using, or why. So before the "how," it's worth being clear on what your actual options are.

Odoo's Three API Surfaces, and When Each One Is Right

XML-RPC is Odoo's original, most universally-supported API. It works with essentially any language that has an XML-RPC library, requires no special setup on the Odoo side, and is genuinely the right default for most server-to-server integrations, especially from older or less common tech stacks. The downside is verbosity — XML-RPC payloads are heavier than JSON, and debugging malformed XML is unpleasant.

JSON-RPC is functionally equivalent to XML-RPC but uses JSON payloads, which makes it noticeably easier to work with from most modern languages and easier to debug. If you're building a new integration from Python, Node, or most other modern stacks and don't have a specific reason to use XML-RPC, use JSON-RPC.

Custom REST controllers (@http.route with type='json' or type='http') are what you build when you need an endpoint shaped specifically for your integration — a Shopify webhook receiver, for instance, needs to accept Shopify's exact payload format and respond the way Shopify expects, which neither XML-RPC nor JSON-RPC does out of the box. This is the approach I used for the Shopify-Odoo integration architecture, and it's the right call whenever you're integrating with a third party that has its own fixed API contract you don't control.

Authentication: Where Most Integrations Get Sloppy

The default XML-RPC/JSON-RPC authentication pattern — username, password (or API key), and database name passed with every call — works, but I regularly see it implemented insecurely: credentials hardcoded in a script, no rotation plan, and a superuser-level API key used for an integration that only ever needs to touch one model.

What I actually recommend:

• Create a dedicated integration user with access rights scoped to exactly the models and operations the integration needs — never the admin/superuser account.
• Use API keys, not the account password, for any external service authentication (Odoo supports this natively under user preferences).
• Verify webhook signatures on any inbound endpoint you build (HMAC verification against a shared secret, as in the Shopify example) — an unauthenticated webhook receiver that can create sales orders or update stock is a real, exploitable liability, not a hypothetical one.

Sync Architecture: Polling vs. Webhooks vs. Event-Driven

For any integration involving more than trivial data volume, the architecture decision matters more than the API mechanism:

• Scheduled polling (an Odoo cron job checking an external system on an interval) is the simplest to build and debug, and it's the right choice when near-real-time sync isn't actually a business requirement — most reporting integrations fall here.
• Webhooks (the external system calls Odoo when something changes) give you real-time sync with much less wasted traffic than polling, but require the receiving endpoint to be resilient — retries, idempotency (handling the same webhook delivered twice without double-processing it), and fast response times so the sender doesn't time out.
• Event-driven / message queue architectures (a queue sitting between the two systems) are worth the added complexity once you're dealing with high transaction volume or multiple systems needing the same data — they decouple the systems so a slow or failing consumer doesn't block the producer.

Most small-to-mid-size integrations don't need the third option, and building it prematurely is wasted engineering effort. Start with the simplest architecture that satisfies the actual latency requirement, not the most impressive one.

Common Failure Modes I Actually See in Production

• No idempotency handling — a webhook fires twice (which happens more often than people expect) and creates a duplicate sales order or double-counts inventory.
• Synchronous processing inside a webhook handler — running heavy logic (multiple ORM writes, external API calls) directly in the HTTP request handler instead of enqueueing it, causing timeouts under load.
• No error visibility — a failed sync fails silently, and nobody notices until a customer complains that their order never arrived in the warehouse system. Every integration I build gets a visible failure log inside Odoo, not just a server log nobody checks.
• Field-level assumptions that break on edge cases — SKU formats, currency precision, or required fields that differ subtly between systems, usually only surfacing weeks after go-live on an unusual order.

Practical Recommendation

If you're integrating a well-known platform (Shopify, WooCommerce, a major accounting system), check for an existing, actively-maintained connector first — building custom REST controllers from scratch only pays off when your requirements genuinely diverge from what a pre-built connector offers, or when data volume demands an architecture a generic connector can't handle. When it does diverge, that's exactly the kind of custom Odoo development work worth scoping properly rather than duct-taping onto a no-code tool that will hit a wall at scale.

If you're planning an integration and want a second opinion on architecture before you start building, get in touch — the cheapest fix for most of the failure modes above is catching them at the design stage, not after go-live.