Skip to main content
odoo icon

Odoo Connector

Sourcenpm · v0.2.0API DocsAPI ChangelogConnector Changelog

Description​

Odoo is a suite of open source business apps that include CRM, eCommerce, accounting, inventory, project management, etc. This component allows querying and managing records in an Odoo database.

API Documentation​

This component was built using the Odoo External API Documentation, currently utilizing the JSON-2 API on Odoo 19.0.

Developer Note: Odoo Models​

An Odoo database tracks hundreds of types of records. A default installation of Odoo includes more than 800 unique record types (more when additional apps are installed).

Each type of record is called a model, and models have human-readable names and model names. For example, contacts in Odoo are called Contacts, and their model name is res.partner. To list all contacts in an Odoo installation, use the List Records action and provide it a model of res.partner.

A model has fields. Contacts for example has hundreds of fields related to a person: name, email, country_code, zip, etc.

For convenience, two utility actions are included in this component.

  • List Models lists all models in an Odoo installation, including their ID, name and model name.
  • List Model Fields lists all of the fields of a given model.

These two utility actions help identify the fields to set when using Create or Update records. Identify the name of the fields to set for a given model. Then, create an object, either in a code step or another action, and pass the results of that step in as a reference.

Connections​

API Key​

key: odooApiKey

To authenticate with Odoo, an API key is required. This component calls Odoo's JSON-2 HTTP API and requires Odoo 19.0 or later. Earlier versions, which only support the soon to be deprecated XML-RPC transport, are not supported.

Prerequisites​

  • An Odoo 19.0 or later instance (Odoo Online, Odoo.sh, or self-hosted)
  • An Odoo user account with permissions for the records the integration will manage
  • Developer mode enabled in Odoo (required to access the API Keys interface)

Setup Steps​

  1. Log in to the Odoo instance
  2. Click the user avatar in the top-right corner and select My Profile
  3. Open the Account Security tab
  4. Click New API Key and provide a descriptive name and expiration
  5. Copy the generated API key immediately (it is shown only once)

For more details, refer to the Odoo external API documentation.

Service Account Recommended

Generate the API key from a dedicated service-account user (not a specific employee's account) so the integration is not tied to an individual's access.

Configure the Connection​

Create a connection of type API Key and configure the following fields:

  • Odoo Base URL: Enter the URL used to log in to Odoo, for example https://example-company.odoo.com. Omit any trailing slash.
  • Server Port: Leave blank for default HTTP (80) or HTTPS (443). Set only when a self-hosted Odoo instance listens on a non-standard port.
  • Odoo Database Name: Click the user avatar in the top-right within Odoo and select My Databases to find the database name.
  • API Key: Enter the API key copied in the previous section.
InputNotesExample
API Key

The API key used to authenticate requests. In Odoo, open the profile menu, then Account Security, and create a new API Key. Requires Odoo 19.0 or later.

Odoo Base URL

The URL used to log in to the Odoo instance.

https://yourdomain.odoo.com
Odoo Database Name

The name of the Odoo database to connect to. Found in Odoo by clicking the user icon at the top-right and selecting 'My Databases'.

odoo_db
Server Port

The port to connect on. Leave blank to use the default HTTP (80) or HTTPS (443) port.

443

Basic Authentication (Deprecated)​

key: odooBasicAuth

The Basic Authentication (Deprecated) connection authenticates against Odoo's XML-RPC API with a username and password. It is maintained for backwards compatibility with integrations built against earlier versions of this component.

Deprecated

Odoo will drop XML-RPC support in 19.1 (mid-2026). Migrate existing integrations to the API Key connection before that release. New integrations should use the API Key connection instead.

Prerequisites​

  • An Odoo instance that still exposes the XML-RPC endpoint
  • An Odoo user account with permissions for the records the integration will manage

Configure the Connection​

Create a connection of type Basic Authentication (Deprecated) and configure the following fields:

  • Odoo Base URL: Enter the URL used to log in to Odoo, for example https://example-company.odoo.com. Omit any trailing slash.
  • Server Port: Leave blank for default HTTP (80) or HTTPS (443). Set only when a self-hosted Odoo instance listens on a non-standard port.
  • Odoo Database Name: Click the user avatar in the top-right within Odoo and select My Databases to find the database name.
  • Username: The username (typically the email address) used to log in to Odoo.
  • Password or API Key: The user's password, or an API key generated under Account Security → New API Key.
InputNotesExample
Odoo Base URL

The URL used to log in to the Odoo instance.

https://yourdomain.odoo.com
Odoo Database Name

The name of the Odoo database to connect to. Found in Odoo by clicking the user icon at the top-right and selecting 'My Databases'.

odoo_db
Password or API Key

The password or API key used to authenticate the user against the Odoo XML-RPC API.

Server Port

The port to connect on. Leave blank to use the default HTTP (80) or HTTPS (443) port.

443
Username

The username used to log in to the Odoo instance.

john.doe@example.com

Triggers​

New and Updated Records​

Retrieves existing and ongoing records for a specified Odoo model. Load history once, check for changes on a schedule, or both. | key: pollChangesTrigger

InputNotesExample
Connection

The Odoo connection to use.

Look-back Date

The date the initial sync starts from, in YYYY-MM-DD format. Cannot be a future date. Leave empty to start from the first recurrence with no backfill. When set, the initial sync seeds each record modified on or after this date once, ignoring the trigger's visibility filters.

2026-01-01
Model

The type of record to query. Use the 'List Models' action for a list of available models.

res.partner
Show New Records

When true, records whose create_date falls after the last poll are emitted in the created bucket.

true
Show Updated Records

When true, records whose write_date falls after the last poll but were created earlier are emitted in the updated bucket.

true

This trigger polls the Odoo External API for new and updated records of a specified model on a configured schedule.

How It Works​

  1. The trigger runs on the configured schedule
  2. It queries the selected model for records whose write_date is on or after the stored position and no later than one minute before the recurrence began, sorted oldest first (by write_date, then id), in pages of 200 records
  3. A fetched record is classified as created when its create_date is after the stored position, and otherwise as updated
  4. Outside an initial sync, Show New Records and Show Updated Records each gate one of the two result arrays. Turning either off empties that array, and both keys remain present in the payload
  5. The trigger stores its new position and reports no changes when both arrays are empty

The write_date comparison is inclusive because Odoo records write_date with one-second granularity. The trigger remembers which records it already delivered at the stored position and skips them, so a record is delivered again only when it is modified again. Records modified within the last minute are left for a later recurrence, so a record that is committed late with an earlier write_date is not skipped.

With batching off, each recurrence fetches at most 50 pages (10,000 records). When the cap is reached, the trigger keeps its place in the backlog and the next recurrence continues from there, so no record is skipped. The stored position moves forward only once the backlog is fully drained. With batching on, the platform requests one page at a time until the backlog is drained within the same run.

Initial Sync

An initial sync seeds a complete starting state rather than a change feed, so inputs that narrow which changes are reported would leave gaps in it: Show New Records and Show Updated Records are ignored while it runs, and are the only inputs it ignores. It begins on the first recurrence, when the trigger has no stored position and a Look-back Date (YYYY-MM-DD) is set, and seeds every record modified on or after 00:00:00 UTC on that date exactly once. Left empty, there is no sync and the trigger starts from its first recurrence.

A record modified while the sync drains is picked up at its new position in the sequence rather than deferred to the schedule. The first recurrence stores a position, and the first incremental recurrence resumes from exactly there. Nothing in the payload marks the handoff. If a backlog is larger than one recurrence reads (the 10,000-record cap with batching off), the sync continues on later recurrences from where it stopped, still ignoring Show New Records and Show Updated Records, until the backlog drains. A larger window therefore spans several recurrences when batching is off.

Model still applies throughout. The trigger has no page-size or field-selection input, so nothing else is suppressed.

Batching

Batching is enabled per flow on this trigger: each changed record is dispatched as its own execution, or grouped by the configured batch size. Batch size and batch concurrency can both be overridden per instance. Raising concurrency increases the request volume sent to Odoo.

To turn it on, select the flow's trigger, open the Flow control tab, and switch on Enable Batching. Under Batch Size, keep Trigger default or choose Custom batch size. Batch Concurrency is optional; leave it blank for no batch-level limit.

With batching off, a downstream step reads body.data.created and body.data.updated. With batching on, those fields do not exist: each execution receives one { "changeType": "created" | "updated", "record": <record> } item, or an array of them when the batch size is greater than 1. Any step reading the older shape must be updated before batching is enabled. Because batching is enabled per flow, the change is scoped to that flow rather than to the component or to other flows using the same trigger.

Batching splits the changed records across executions. It also lets the backlog drain within one run, one page per request, instead of across scheduled recurrences.

Returned Data​

With batching off, the trigger returns an object with two arrays: created for new records and updated for modified records. Each array contains the Odoo records of the selected model, with all fields returned by the API. Fields shown are representative. The full response object includes additional properties.

Example Response
{
  "data": {
    "created": [
      {
        "id": 14,
        "name": "Acme Corporation",
        "display_name": "Acme Corporation",
        "email": "billing@acme.example.com",
        "create_date": "2026-05-26 14:30:00",
        "write_date": "2026-05-26 14:30:00"
      }
    ],
    "updated": [
      {
        "id": 9,
        "name": "Fabrikam, Inc.",
        "display_name": "Fabrikam, Inc.",
        "email": "ap@fabrikam.example.com",
        "create_date": "2026-04-12 09:00:00",
        "write_date": "2026-05-26 15:45:00"
      }
    ]
  }
}

With batching on, each execution receives one item per changed record, or an array of items when the batch size is greater than 1.

Example Response (Batched)
{
  "changeType": "updated",
  "record": {
    "id": 9,
    "name": "Fabrikam, Inc.",
    "display_name": "Fabrikam, Inc.",
    "email": "ap@fabrikam.example.com",
    "create_date": "2026-04-12 09:00:00",
    "write_date": "2026-05-26 15:45:00"
  }
}
Example Payload for New and Updated Records⤓
Loading…

Data Sources​

Select Model​

A picklist of models in the Odoo database. | key: selectModel | type: picklist

InputNotesExample
Connection

The Odoo connection to use.

Model Search

Filter results to entries whose technical model identifier contains this case-insensitive search term.

res.partner
Name Search

Filter results to entries whose name contains this case-insensitive search term.

Partner
Example Payload for Select Model⤓
Loading…

Select Record​

A picklist of records in the Odoo database. | key: selectRecordById | type: picklist

InputNotesExample
Connection

The Odoo connection to use.

Model

The type of record to query. Use the 'List Models' action for a list of available models.

res.partner
Example Payload for Select Record⤓
Loading…

Actions​

Create Record​

Create a new record of a given type. | key: createRecord

InputNotesExample
Connection

The Odoo connection to use.

External ID

A unique identifier that maps this record to its counterpart in an external system. Use the 'module.name' format.

custom_partner.abc_123
Model

The type of record to query. Use the 'List Models' action for a list of available models.

res.partner
Parameters

The field names and values to set on the record. Must be a JSON object keyed by Odoo field name.

{
  "name": "John Doe",
  "email": "doe@example.com",
  "country_code": "US",
  "city": "New York",
  "zip": "10001"
}
Example Payload for Create Record⤓
Loading…

Delete Record By ID​

Delete a record by its numerical ID. | key: deleteRecordById

InputNotesExample
Connection

The Odoo connection to use.

Record ID

The numeric identifier of the target record assigned by Odoo.

25
Model

The type of record to query. Use the 'List Models' action for a list of available models.

res.partner
Example Payload for Delete Record By ID⤓
Loading…

Get Record by External ID​

Get a record by its external ID. | key: getRecordByExternalId

InputNotesExample
Connection

The Odoo connection to use.

External ID

A unique identifier that maps this record to its counterpart in an external system. Use the 'module.name' format.

custom_partner.abc_123
Example Payload for Get Record by External ID⤓
Loading…

Get Record By ID​

Fetch a record by its numerical ID. | key: getRecordById

InputNotesExample
Connection

The Odoo connection to use.

Record ID

The numeric identifier of the target record assigned by Odoo.

25
Model

The type of record to query. Use the 'List Models' action for a list of available models.

res.partner
Example Payload for Get Record By ID⤓
Loading…

List Model Fields​

List all fields for a given model. | key: listModelFields

InputNotesExample
Connection

The Odoo connection to use.

Model

The type of record to query. Use the 'List Models' action for a list of available models.

res.partner
Example Payload for List Model Fields⤓
Loading…

List Models​

Fetch a list of models installed in the Odoo database. | key: listModels

InputNotesExample
Connection

The Odoo connection to use.

Fetch All

When true, automatically fetches all pages of records. Overrides the Limit and Offset inputs.

false
Model Search

Filter results to entries whose technical model identifier contains this case-insensitive search term.

res.partner
Name Search

Filter results to entries whose name contains this case-insensitive search term.

Partner
Pagination

Page size and starting offset for paging through results.

Example Payload for List Models⤓
Loading…

List Records​

Fetch a list of records of a given type. | key: listRecords

InputNotesExample
Connection

The Odoo connection to use.

Fetch All

When true, automatically fetches all pages of records. Overrides the Limit and Offset inputs.

false
Model

The type of record to query. Use the 'List Models' action for a list of available models.

res.partner
Pagination

Page size and starting offset for paging through results.

If Odoo is expected to return lots of records, the integration can leverage pagination to process a small set of records at a time. See Odoo's External JSON-2 API reference for details on the limit and offset parameters used for pagination.

Example Payload for List Records⤓
Loading…

Raw Request (API Key)​

Send a raw HTTP request to the Odoo JSON-2 API. Requires the API Key connection. | key: rawHttpRequest

InputNotesExample
Connection

The Odoo connection to use.

Data

The HTTP body payload to send to the URL.

{"exampleKey": "Example Data"}
File Data

File Data to be sent as a multipart form upload.

[{key: "example.txt", value: "My File Contents"}]
File Data File Names

File names to apply to the file data inputs. Keys must match the file data keys above.

Form Data

The Form Data to be sent as a multipart form upload.

[{"key": "Example Key", "value": new Buffer("Hello World")}]
Header

A list of headers to send with the request.

User-Agent: curl/7.64.1
Max Retry Count

The maximum number of retries to attempt. Specify 0 for no retries.

0
Method

The HTTP method to use.

Query Parameter

A list of query parameters to send with the request. This is the portion at the end of the URL similar to ?key1=value1&key2=value2.

Response Type

The type of data you expect in the response. You can request json, text, or binary data.

json
Retry On All Errors

If true, retries on all erroneous responses regardless of type. This is helpful when retrying after HTTP 429 or other 3xx or 4xx errors. Otherwise, only retries on HTTP 5xx and network errors.

false
Retry Delay (ms)

The delay in milliseconds between retries. This is used when 'Use Exponential Backoff' is disabled.

0
Timeout

The maximum time that a client will await a response to its request

2000
URL

The path portion of the URL to call. The connection's base URL (for example, https://yourdomain.odoo.com) is prepended automatically. For example, to call https://yourdomain.odoo.com/json/2/res.partner/search_read, enter only /json/2/res.partner/search_read.

/json/2/res.partner/search_read
Use Exponential Backoff

Specifies whether to use a pre-defined exponential backoff strategy for retries. When enabled, 'Retry Delay (ms)' is ignored.

false

Raw Request (Basic Auth)​

Issue any execute_kw action against the Odoo XML-RPC API. Requires the Basic Authentication (Deprecated) connection. | key: rawRequest

InputNotesExample
Connection

The Odoo connection to use.

Method

The Odoo model method to invoke via execute_kw (for example, search_read, create, write).

search_read
Model

The type of record to query. Use the 'List Models' action for a list of available models.

res.partner
Parameters

A JSON array of positional arguments to pass to execute_kw. See the Odoo XML-RPC documentation for argument shapes.

[["read"]]

Set External ID​

Add an external ID to a record that does not have one. | key: setExternalId

InputNotesExample
Connection

The Odoo connection to use.

External ID

A unique identifier that maps this record to its counterpart in an external system. Use the 'module.name' format.

custom_partner.abc_123
Record ID

The numeric identifier of the target record assigned by Odoo.

25
Model

The type of record to query. Use the 'List Models' action for a list of available models.

res.partner
Example Payload for Set External ID⤓
Loading…

Update Record​

Update an existing record of a given type. | key: updateRecord

InputNotesExample
Connection

The Odoo connection to use.

Record ID

The numeric identifier of the target record assigned by Odoo.

25
Model

The type of record to query. Use the 'List Models' action for a list of available models.

res.partner
Parameters

The field names and values to set on the record. Must be a JSON object keyed by Odoo field name.

{
  "name": "John Doe",
  "email": "doe@example.com",
  "country_code": "US",
  "city": "New York",
  "zip": "10001"
}
Example Payload for Update Record⤓
Loading…

Changelog​

2026-11-05​

Updated spectral to 10.39.0

2026-11-04​

Published the component as an npm package, so code-native integrations can install it and call its actions, triggers and data sources from code with TypeScript types

2026-11-02​

Updated spectral to 10.34.1

2026-10-19​

  • Added an optional Look-back Date input to the New and Updated Records trigger for performing an initial sync of records. The initial sync begins on the first recurrence and backfills every record modified on or after the specified date, seeding each once and ignoring the visibility filters; recurrences after the sync completes are unaffected. Leave it empty to start from the first recurrence with no backfill
  • Added opt-in batching to the New and Updated Records trigger, dispatching each changed record individually or in configured batches so large backlogs drain in one recurrence; enabling it changes the shape a downstream step receives
  • Fixed the New and Updated Records trigger delivering some records twice or skipping a record modified while a large backlog was being read

2026-08-13​

Improved record polling and configuration-time support:

  • Corrected cursor advancement in the New and Updated Records polling trigger so records past the per-poll page cap are no longer skipped
  • Grouped the paging inputs on List Records and List Models into a Pagination structured object; Fetch All stays a top-level toggle
  • Added output schemas to the List Models, Create Record, Update Record, Delete Record By ID, and Set External ID actions for improved field mapping during configuration
  • Added inline action calling support across all actions for improved example output during configuration

2026-06-02​

Migration preparations for the soon to be deprecated XML-RPC API to Odoo's JSON-2 HTTP API (required for the Odoo 19.1 SaaS rollout in mid-2026)

  • Added the API Key connection that authenticates to Odoo's JSON-2 HTTP API using an API key
  • Added New and Updated Records polling trigger that filters Odoo records by write_date using the search_read domain (write_date >= last poll); records whose create_date is also after the last poll go to the created branch, while older records modified since the last poll go to updated. The model picker reuses the existing selectModel datasource so the trigger works against any Odoo model with create_date / write_date
  • The Basic Authentication (Deprecated) connection is maintained as a compatibility shim and will stop working when Odoo drops XML-RPC support in 19.1 (mid-2026); migrate existing integrations to the API Key connection before that release
  • The New and Updated Records polling trigger supports both the API Key and Basic Authentication (Deprecated) connections, matching the rest of the component

2026-05-20​

Applied automated security patches and code formatting updates

2026-04-30​

Updated spectral version

2025-10-21​

Added inline data sources for models and records to enhance data selection capabilities