Introduction
Odoo provides API capabilities that allow businesses to connect their ERP with eCommerce platforms, CRM systems, payment gateways, shipping providers and other third-party applications. External systems can securely access permitted Odoo records, exchange information and execute supported business operations.
For example, an eCommerce platform can check product availability, create an Odoo quotation and receive delivery updates without spreadsheet transfers.
But which Odoo API should developers use? How does authentication work? What is the difference between the JSON-2 API, legacy XML-RPC services, custom controllers and webhooks?
This guide explains how Odoo API integration works, demonstrates practical API requests and covers the security, transaction and data-mapping decisions needed for a reliable connection.
What Is Odoo API Integration?
Odoo API integration connects Odoo models and business processes with an external application. The external system sends a request, Odoo authenticates the caller, checks its permissions, executes an allowed model method and returns a result.
An integration can read or update records such as:
- customers and vendors in res.partner
- product variants in product.product
- quotations and orders in sale.order
- delivery operations in stock.picking
- invoices and credit notes in account.move.
The objective is not to copy every record. Define which application owns each value: a store may own checkout while Odoo owns stock, fulfilment and accounting.
How Odoo API Integration Works
A typical integration contains five parts:
- Trigger: A webhook, scheduled job or user action starts the process.
- Authentication: The calling application presents valid credentials or an API key.
- Mapping: External identifiers and values are mapped to Odoo models and fields.
- Business operation: Odoo reads, creates or updates records and may run a method such as action_confirm.
- Result handling: The connector stores the response, retries safe failures and sends unresolved exceptions to a review queue.
For a store order, the connector checks the external ID, matches the customer and products, creates a quotation and uses Odoo's sales logic to confirm it. Delivery details then return to the store. The ORM applies model logic, permissions and validations that direct database changes would bypass.
Types of Odoo APIs
Odoo JSON-2 API
The external Odoo JSON-2 API was introduced in Odoo 19. It accepts HTTP POST requests at:
/json/2/<model>/<method>
The model and method appear in the URL, while named arguments are sent as a JSON object. Authentication uses an API key in the Authorization: bearer header. The models, fields and methods exposed by a particular database can be reviewed on that database's /doc page.
On Odoo-hosted subscriptions, external API access is available with the Custom plan and is not available on the One App Free or Standard plans. Deployment, edition and licensing requirements should be checked for self-hosted environments.
Although people commonly search for an Odoo REST API, JSON-2 is method-oriented rather than a conventional resource-based REST interface. For example, a client calls res.partner/search_read; it does not send a GET request to a customer resource URL.
XML-RPC and JSON-RPC
Many integrations built for earlier Odoo versions use the external XML-RPC or JSON-RPC services. In Odoo 19, the /xmlrpc, /xmlrpc/2 and /jsonrpc external RPC endpoints are deprecated.
Odoo schedules the external common and object services for removal in Odoo 22, expected in fall 2028, and Odoo Online 21.1, expected in winter 2027. The legacy database service was removed in Odoo 20 and Odoo Online 19.1. Existing connectors should therefore be inventoried and given a migration plan instead of waiting for the final upgrade window.
This deprecation notice concerns the legacy external RPC services. It does not automatically apply to every custom controller using Odoo's JSON-RPC route type.
Custom Controllers and Webhooks
A custom module can expose a purpose-built HTTP controller when an external application should call one controlled operation rather than several models.
Webhooks let a provider or marketplace notify Odoo about an event. The receiving route must verify the sender, validate the payload and prevent duplicates.
External services may describe their interfaces as REST APIs. Those third-party APIs should not be confused with Odoo's native JSON-2 endpoint or with a custom controller developed inside Odoo.
How to Connect to Odoo Using JSON-2
1. Create a dedicated integration user
Create a dedicated bot user with only the permissions required by the connector.
JSON-2 uses the normal Odoo security model. Access control lists, record rules, field permissions and active-company context still apply. An API key does not bypass them.
2. Generate and protect the API key
Generate a key from Preferences → Account Security → New API Key. Store it in a secret manager or protected environment variable, never in source code, browser JavaScript or request logs.
Odoo 19 limits manually generated JSON-2 keys to three months, so production integrations need tested key rotation.
3. Send the required headers
A JSON-2 request normally includes:
Authorization: bearer YOUR_API_KEY Content-Type: application/json; charset=utf-8 User-Agent: your-connector-name/1.0
Use X-Odoo-Database when the server hosts multiple databases and the hostname or database filter does not identify the database unambiguously.
4. Check the database documentation
Open /doc on the target database to confirm its models, methods, parameters and fields. Installed apps and custom modules change the API surface.
Odoo API Example: Read Customers
The following request finds up to five companies whose names contain “Deco”:
POST /json/2/res.partner/search_read HTTP/1.1
Host: mycompany.example.com
X-Odoo-Database: mycompany
Authorization: bearer YOUR_API_KEY
Content-Type: application/json; charset=utf-8
User-Agent: commerce-connector/1.0
{
"domain": [
["name", "ilike", "%deco%"],
["is_company", "=", true]
],
"fields": ["name", "email", "ref"],
"limit": 5,
"order": "id asc"
}
A successful response contains the serialized method result:
[
{
"id": 25,
"name": "Deco Addict",
"email": "orders@example.com",
"ref": "SHOP-CUST-8842"
}
]
Request only required fields and use limit, offset and a stable order for large datasets.
Odoo API Example: Create a Record
The create method can create a customer using named arguments. Confirm the method signature in /doc before implementing it against a customized database.
POST /json/2/res.partner/create HTTP/1.1
Host: mycompany.example.com
Authorization: bearer YOUR_API_KEY
Content-Type: application/json
{
"vals_list": [
{
"name": "Northwind Retail",
"email": "orders@northwind.example",
"ref": "SHOP-CUST-8842",
"is_company": true
}
]
}
Search by a stable external reference before creation. A dedicated ID field or mapping model with a uniqueness constraint is safer than matching by name or email.
Calling Odoo Business Methods
Creating and confirming an order are different operations. Do not write state directly when Odoo provides a method that applies its validations.
For example, after creating and validating a sale.order, the connector can invoke its confirmation method:
POST /json/2/sale.order/action_confirm HTTP/1.1
Host: mycompany.example.com
Authorization: bearer YOUR_API_KEY
Content-Type: application/json
{
"ids": [87]
}
action_confirm applies the installed version's sales logic. Depending on the configuration, that can include confirming order lines and starting downstream delivery or procurement processes.
Important: One Transaction per JSON-2 Call
Every JSON-2 request runs in its own SQL transaction. Odoo commits a successful call and rolls back a failed call. Multiple JSON-2 requests cannot be chained into one database transaction.
If one request creates an order and a second confirms it, another transaction could modify the data between calls. Payments, reservations and stock require particular care.
When several dependent actions must either all succeed or all fail, expose or call one server-side method that performs the complete operation in a single transaction. search_read follows the same principle by combining the search and read operations in one method.
End-to-End Example: eCommerce Order to Odoo
Imagine a Shopify or WooCommerce store using Odoo for inventory, fulfilment and accounting.
1. Receive and verify the event
The store sends an order webhook. The connector verifies its signature, records the external order ID and rejects an invalid or already processed event.
2. Match customers and products
The integration searches res.partner using an external customer mapping. It matches order items to product.product using an agreed SKU or platform identifier. Missing or duplicate matches are sent for review instead of creating an incorrect order.
3. Create the quotation
The connector maps the customer, company, currency, pricelist, taxes, delivery address and order lines into sale.order. It stores the platform order ID so retries remain idempotent.
4. Confirm through Odoo logic
The connector calls the appropriate business method after validation. It does not manually force the order or delivery state. If creation and confirmation must be atomic, a dedicated module can expose one controlled server-side method.
5. Return fulfilment updates
The connector reads relevant stock.picking records and returns tracking and delivery status. It must represent partial deliveries, cancellations and backorders accurately.
6. Reconcile exceptions
Failed matches, tax differences and rejected requests belong in a visible queue with the external ID, Odoo record, error and retry history.
Odoo API Integration Best Practices
Use least-privilege access
Grant only the required models, companies and operations. Test with the bot user, not an administrator.
Design for multi-company context
Confirm active and allowed companies. Incorrect context can select the wrong warehouse, pricelist, fiscal position or journal.
Make operations idempotent
Store a unique external reference and check it before creating a record. Retrying the same webhook must not create another order, payment or refund.
Use business methods
Call supported methods such as action_confirm instead of writing workflow states directly. Business methods apply validation and related Odoo behavior.
Control pagination and synchronization
Use limited pages, explicit ordering and a checkpoint. Incremental exports can use write_date with overlapping windows and deduplication.
Handle errors visibly
JSON-2 returns 4xx or 5xx errors with a JSON error object. Log sanitized details and a correlation ID without exposing credentials or tracebacks.
Test upgrades and customizations
Before an upgrade, recheck /doc, rerun contract tests and test complete business workflows.
Common Integration Challenges and Solutions
| Challenge | Odoo-specific solution |
|---|---|
| Access error | Check bot-user groups, record rules, fields and active company |
| Duplicate records | Use unique platform IDs and idempotent processing |
| Wrong product | Map variants through product.product, not only product names |
| Incorrect workflow state | Invoke business methods instead of writing state |
| Large synchronization | Select fields, paginate and use incremental checkpoints |
| Partial multi-call process | Use one server-side method for dependent operations |
| Upgrade failure | Review version changes, dynamic /doc output and regression tests |
| Expired API key | Monitor expiry and rotate keys without downtime |
Connector vs Custom API Integration
| Approach | Suitable when | Important checks |
|---|---|---|
| Ready-made connector | Platform and workflow are standard | Supported Odoo versions, field coverage, queues and maintenance |
| Direct JSON-2 integration | Two systems need focused model operations | Security, transactions, mapping and upgrade compatibility |
| Custom controller/module | External system needs one controlled business contract | Authentication, validation, tests and long-term ownership |
| Middleware | Several systems need transformation or orchestration | Monitoring, licensing, data ownership and operating cost |
A connector is usually faster when its supported workflow matches the requirement. Custom development is justified when the business needs special mapping, approvals, transaction boundaries or platform behavior that a standard connector cannot provide safely.
How Browseinfo Helps with Odoo API Integration
Browseinfo can define data ownership, select a suitable method and implement a connector or custom module, including authentication, mapping, webhooks, error queues and testing.
The objective should be a supportable business process not simply a demonstration that two endpoints can exchange JSON.
Frequently Asked Questions
1. What is Odoo API integration?
It connects Odoo with external applications so they can exchange permitted data and execute supported Odoo operations without repeated manual entry.
2. Does Odoo have a REST API?
Odoo 19 introduced the HTTP-based JSON-2 API. It is commonly discussed as an Odoo REST API, but it calls model methods and is not a conventional resource-oriented REST interface. Custom modules can provide purpose-built HTTP routes when required.
3. How does Odoo API authentication work?
JSON-2 uses an API key as a bearer token. Requests execute with the linked user's access rights, record rules, field permissions and company access.
4. Are XML-RPC and JSON-RPC still supported?
They are deprecated external APIs. The common and object services are scheduled for removal in Odoo 22 and Odoo Online 21.1. Existing connectors should be reviewed and migrated in advance.
5. Can an API create and confirm an Odoo sales order?
Yes, if the user has the required permissions and the database exposes the required methods. Create the quotation with valid customer and product data, then use Odoo's business logic to confirm it. Use one custom server-side method when dependent steps must share a transaction.
6. Can Odoo integrate with Shopify or WooCommerce?
Yes. A connector or custom integration can synchronize customers, products, orders, stock and fulfilment updates. The exact scope depends on the platform APIs, Odoo version and business rules.
7. How do you prevent duplicate orders?
Store a unique external order ID, enforce uniqueness where appropriate and make retries idempotent. Never depend only on the customer's name, timestamp or order total.
Conclusion
A dependable Odoo third-party integration requires more than sending successful HTTP requests. It needs correct authentication, Odoo model knowledge, stable external identifiers, suitable business methods, transaction-aware design and visible error handling.
For Odoo 19 and later projects, evaluate JSON-2 first and review existing legacy RPC connectors before their scheduled removal. Use the database's /doc page, restrict the integration user and test complete processes such as ordering, fulfilment, refunds and reconciliation.
If your project involves custom workflows or several external applications, explore Browseinfo's Odoo Integration Services to plan a secure and maintainable connection.
