Odoo 19 JSON-2 API: Modern interfaces for e-commerce integrations
For new external integrations, the JSON-2 API is the current interface generation in Odoo 19. XML-RPC and JSON-RPC still exist, but according to Odoo, they are slated for replacement. Anyone building with these today is effectively already planning for a future migration of the integration layer.
This article describes the interface as a Odoo Connector It actually addresses: authentication, methods, error objects, idempotence in mass import and the interaction with the differing token models of Shopware and PlentyONE.
Protocol Shift: Why JSON-2 is the current standard
Odoo has the older endpoints /xmlrpc, /xmlrpc/2 and /jsonrpc Officially slated for removal – according to Odoo, for Odoo 22 (Autumn 2028) and Odoo Online 21.1 (Winter 2027). The JSON-2 API is its designated successor. For new developments, this means that while building on XML-RPC would still be technically possible, its architecture is already foreseeably outdated.
An important limitation that should be clarified before any target architecture decision is that the availability of the external API depends on the operating model and edition. According to Odoo, external API access for Odoo Online (SaaS) is only available in Custom plans – it is not enabled in the One App Free and Standard plans. For self-hosted instances (on-premises or Odoo.sh), the JSON-2 API is available starting with the Custom plans, and is always available in the Community Edition.
This leads to a clear requirement for a Shopware-Odoo integration: You need either the Community Edition or a Custom Plan. Anyone who only clarifies this question after the architectural decision risks having chosen an operating model that does not technically allow the planned integration.
Stateless Authentication
Authentication is completely stateless, using an API key transmitted as a bearer token in the HTTP header. An API key can be created via the Odoo account security settings; programmatic management is restricted to users with administrative privileges by default.
A verified example call against a self-hosted Odoo 19 instance:
curl -X POST "${ODOO_URL}/json/2/res.partner/search_read" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${ODOO_API_KEY}" \
-d '{"domain":[],"limit":1}'Next to Authorization and Content-Type Two other headers are relevant in practice: X-Odoo Database, required if a server hosts multiple databases and the dB filter does not evaluate the host header; and User-Agent, recommended by Odoo to differentiate between migration load and regular connector traffic on the server side in migration projects with multiple parallel processes.
Syntax, methods, and error handling
The JSON-2 API provides several key methods:
| method | function |
|---|---|
search_read | Searching and simultaneous reading, including pagination and complex filters (domains) |
read | Targeted extraction of specific data records based on their IDs |
write | Updating existing data records |
unlink | Permanent deletion of data records |
load | Batch import method from the CSV import mechanism, significantly more performant for large amounts of data than individual imports. create()-views |
A practical advantage of the JSON-2 API over older interfaces is that it returns true HTTP status codes (200 for success, 401 for failed authentication, 429 for rate limits), which significantly simplifies exception handling in the connector. In case of an error, the API also returns a JSON-serialized error object with the following fields: name (fully qualified name of the Python exception), message, arguments, context and debug. Particularly name It can be evaluated to differentiate between business errors such as validation violations and technical errors such as authentication problems – and to control the retry decision accordingly.
An example of this distinction in practice: If the API reports a validation error because a required field is missing, an automatic retry is pointless – the error will occur identically on the next attempt as long as the data isn't corrected. If, on the other hand, the API reports an authentication error, this could indicate an expired or invalid token, which can be resolved by logging in again. A connector that treats both cases the same – for example, by performing a blanket, repeated retry without differentiation – masks genuine data problems behind apparent technical glitches.
The load method: Performance and idempotence
For mass imports as part of an ERP migration, the load()-This method is the central building block. It processes multiple data sets within a single model call, thereby reducing the effort compared to many individual calls. create()-Calls noticeably increase the API and ORM overhead – the actual performance gain depends on the model, fields, constraints and data volume.
The real reason why load() The right choice for migrations lies not in performance, but in idempotence: load() accepts a column id, which does not refer to the numeric database ID, but to the external ID (XML ID) of the data record – a freely assignable, system-wide stable identifier in the form module.identifierOdoo includes these external IDs in its model. ir.model.data and maintains the mapping to the internal database ID there. A data record with an existing external ID is thus updated instead of duplicated upon repeated import – the basis for test migrations that can be repeated as often as desired.
Authentication in system comparison
For a Shopware-Odoo integration, it is relevant that all three systems involved use the same token format (Authorization: Bearer <Token>), but differ in token procurement:
- Odoo 19 (JSON-2): The API key is used directly as the bearer token, without any token exchange. The key does not expire automatically; no refresh logic is required in the connector.
- Shopware 6 (Admin API): Authentication via OAuth 2.0 client credentials flow; the resulting access token is only valid for 600 seconds. For longer extraction runs, the connector must proactively renew the token instead of waiting for the first 401 error.
- PlentyONE (REST API): Authentication is also via OAuth 2.0; the token is valid for 86,400 seconds (24 hours) – significantly less critical for individual runs, but relevant for budget-controlled extractions running over several days.
Dynamic runtime documentation
A practical advantage of the JSON-2 API for integration work: Every Odoo instance provides a JSON-2 API under the path [path missing in original text]. /doc Runtime-generated documentation is available. According to Odoo, the actually available models, fields, and methods are specific to each database and can be found precisely on that database. /docView page.
This is relevant because Odoo instances differ in their actual data model – depending on installed modules, activated functions, and individually created custom fields such as those used in migration projects. x_shopware_uuid-fields. A static, version-bound API documentation could not reflect these instance-specific differences.
In practice, this means that for a connector, the actual field structure of the target instance should be determined before productive use. /doc It is essential to check the documentation instead of relying solely on general documentation. This is especially true for custom fields that were added to the data model during a migration – they only appear in the instance-specific runtime documentation, not in the general Odoo core documentation.
JSON-2 as the basis for the Shopware-Odoo integration
The JSON-2 API forms the transport basis for the ongoing synchronization between Shopware and Odoo. Error handling and retry logic are intentionally handled by the calling client, not the API itself: JSON-2 does not perform automatic retry attempts. The specific implementation of this client-side error handling, event processing, and queue connection is shown below. Odoo Shopware 6 Connector.
The JSON-2 API is the technical foundation of the integration. Our overview shows how it fits into the overall architecture of an ERP migration. Migration from PlentyONE to Odoo.
Frequently Asked Questions about the Odoo JSON-2 API
Can we simply continue running an existing XML-RPC integration?
Technically, this is possible for a certain transition period, as the removal is only planned for later Odoo versions. However, for new developments, it is recommended to use the JSON-2 API directly to avoid having to plan for another migration of the integration layer in the short to medium term.
What happens if our chosen Odoo hosting model does not allow external API access?
Then the JSON-2 API will not be fully functional, which significantly complicates or even prevents Shopware integration. This requirement should therefore be checked before, not after, choosing a hosting model.
Is the JSON-2 API also suitable for very large datasets?
Yes, especially in combination with the batch-capable `load()` method, which processes multiple records per call. For mass migrations with hundreds of thousands of items, this is the recommended approach compared to individual `create()` calls.
We are unsure whether our planned Odoo hosting will even unlock the required API.
That’s the first question, not the last. Without external API access, the integration described here is technically impossible – this requirement therefore precedes every architectural decision, not follows it. But we can support you here as well. Our managed hosting servers offer the ideal conditions for Odoo.
Sources
The statements regarding the JSON-2 API, the /docThe endpoint and availability of external API access for each Odoo plan are based on the official Odoo documentation: External JSON-2 API as well as External RPC API. Note: Odoo has already postponed the removal date of the RPC interfaces once (originally Odoo 20/2026, currently Odoo 22/2028 or Online 21.1/2027) – this information should be checked against the live documentation before each publication.
Have your API architecture reviewed for your migration
We will clarify whether your chosen Odoo operating model and edition provide the JSON-2 API to the required extent and what the specific integration architecture should look like for your existing shop system as part of our [service/consultation/etc.]. free, non-binding e-commerce audits.
✔ Free ✔ No obligation ✔ Tested against real Odoo-19 instances ✔ Response within 24 hours
Christopher Einenkel
Christopher Einenkel is the strategic mind at HQ GmbH for advanced system integrations and complex API architectures. Whenever data synchronizations reach their limits or demanding enterprise systems such as Salesforce need to be connected to Shopify, he designs tailored, high-performance interface logic.
His track record includes the in-house development of proprietary enterprise solutions, including automated AI translation tools for product master data, seamless B2B procurement systems, as well as automated market evaluation and competitive monitoring solutions. In addition, he manages the technical implementation and API integration of digital software call center systems into existing CRM and ERP environments for our enterprise clients.
