How to connect Odoo Accounting to API2Cart?

This guide shows you how to connect Odoo Accounting to API2Cart. Odoo does not use OAuth: API2Cart signs in to your Odoo database over its JSON-RPC interface with the login of an Odoo user and an API key generated for that user, so there is no app to register and no token to refresh. Everything API2Cart can do is then limited by the access rights of that user, exactly as if the user worked in Odoo.

The connection needs four values — odoo_url, odoo_database, odoo_login and odoo_api_key. Steps 1–4 below show where each one comes from, Step 5 adds the connection, and the table in Step 2 lists the access rights every API2Cart method needs.

What you need to connect Odoo Accounting to API2Cart

• Odoo 17.0 or newer — Community or Enterprise, hosted on Odoo Online, Odoo.sh or your own server. API2Cart rejects older versions when the connection is added.
• The Invoicing or Accounting app installed in the database. It holds the contacts, products, accounts, taxes, invoices, bills and payments that the API2Cart methods work with. Sales orders, their shipments and purchase orders additionally need the Sales, Inventory and Purchase apps.
• An Odoo user for API2Cart with the access rights from Step 2. A dedicated user is recommended: its rights are easy to review, and its API key can be revoked without affecting anyone else.
• The external API enabled for your database. On your own server and on Odoo.sh it is always available. On Odoo Online, Odoo offers it on the Custom pricing plan: according to the Odoo documentation, access to the external API is not available on One App Free or Standard plans.

With these in place, the connection comes down to four parameters:

• odoo_url — the address of the Odoo instance, for example https://mycompany.odoo.com (Step 4).
• odoo_database — the name of the database, for example mycompany (Step 4).
• odoo_login — the login of the Odoo user, usually an email address (Step 2).
• odoo_api_key — the API key generated for that user (Step 3).

Step 1: Check the Odoo version and the installed apps

To connect Odoo Accounting to API2Cart you need Odoo 17.0 or newer. If you are not sure which version runs on your instance, request it without signing in — Odoo answers this call for everyone:

curl -X POST 'https://mycompany.odoo.com/web/webclient/version_info' \
-H 'Content-Type: application/json' \
-d '{"jsonrpc": "2.0", "method": "call", "params": {}}'

The response carries the version in server_version, for example 19.0 on your own server or saas~19.4+e on Odoo Online. Then open Apps in Odoo and make sure that Invoicing (or Accounting in Odoo Enterprise) is installed, together with Sales, Inventory or Purchase if you plan to use the sales order, shipment or purchase order methods.

Step 2: Set the access rights of the Odoo user

Odoo validates every API call against the access rights of the user whose login and key API2Cart holds, so prepare this user before you connect Odoo to API2Cart. Create the user, or pick an existing one, under Settings > Users & Companies > Users, and set its access levels on the Access Rights tab according to the methods you need. The full mapping between API2Cart methods and Odoo access levels is in the table at the end of this guide; in short:

• Invoicing (Billing in Odoo 17) in the Invoicing / Accounting app covers every list method and every invoice, bill, credit note and payment method.
• Contact Creation is needed for contact.add, contact.update and contact.delete; the product creation right for item.add, item.update and item.delete.
• Administrator of the Invoicing / Accounting app is needed for account.add, account.update and account.delete.
• The Sales, Inventory and Purchase apps need their own User level for the sales order, shipment and purchase order methods.

Access levels add up, so one user can carry all of them. Giving the user the Administrator level of each app is the simplest option when you do not need to keep the rights minimal.

Two more things depend on the user. First, API2Cart works only with the companies the user may access: organization.list returns them, and the user's current company is the default one, so check the Companies allowed for the user on the user form of a multi-company database. Second, when a method needs a right the user does not have, Odoo rejects the call, and API2Cart returns its message, which names the missing access level, for example Odoo Error: You are not allowed to create 'Contact' (res.partner) records. This operation is allowed for the following groups: - Contact/Creation.

Step 3: Create an API key for the user

Sign in to Odoo as the user you prepared in Step 2 — the API key is created from the user's own profile and cannot be generated on another user's behalf. Open the user menu in the top right corner, choose Preferences (or My Profile), go to the Account Security tab (Security in Odoo 19) and click New API Key (Add API Key in Odoo 19). Odoo asks you to confirm your password, then to fill in the key details:

• Description — a name that tells what the key is for, for example API2Cart.
• Duration — Odoo 18 and newer only. For a regular user the longest allowed lifetime is set by the administrator and is 90 days by default; a user with the Settings level of the Administration access can also choose Persistent Key, which never expires. Keys created in Odoo 17 have no expiration date.

Odoo shows the key only once, right after it is generated, so copy it immediately and store it as you would store a password. If the key is lost, delete it in the same tab and create a new one.

The user password is accepted in place of the key as well, unless two-factor authentication is enabled for the user: then Odoo accepts only API keys from external applications. A key is still the better choice in every case, because it can be revoked separately from the password and does not change when the user changes it.

Step 4: Find the instance URL and the database name

On Odoo Online both values are visible in the address of your database: for https://mycompany.odoo.com the odoo_url is this address and the odoo_database is its subdomain, mycompany.

On Odoo.sh and on your own server, odoo_url is the root address at which Odoo answers — the page that shows the Odoo login form, without any path after the host. Specify the final address, usually the https:// one: API2Cart does not follow redirects and reports them as an error instead. The odoo_database is the name given to the database when it was created. If your server hosts several databases, Odoo lists their names in the database selector at sign-in; your Odoo administrator can also see them on the database manager page, /web/database/manager, when it is enabled on the server.

Step 5: Connect Odoo Accounting to API2Cart

Now add the connection in API2Cart — in the dashboard (Add Connection, Integration Type: Accounting, Integration: Odoo Accounting), or with the connection.add method of the Accounting API, where integration_id is Odoo. Both use the same parameter names, and all four are required:

curl -X POST 'https://api.api2cart.com/accounting/v1/connection.add.json' \
-H 'x-api-key: YOUR_API2CART_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
  "integration_id": "Odoo",
  "odoo_url": "https://mycompany.odoo.com",
  "odoo_database": "mycompany",
  "odoo_login": "[email protected]",
  "odoo_api_key": "YOUR_ODOO_API_KEY",
  "custom_label": "My Company Odoo"
}'

By default verify is true: before the connection is saved, API2Cart requests the Odoo version, signs in with the login and the key, checks that the Invoicing or Accounting app is installed and that the user may access at least one company, so a wrong value is reported right away (see Troubleshooting below). The custom_label parameter is optional and only sets a human-readable name for the connection. A successful call returns a connection_key, which every subsequent accounting API call for this connection must include:

{"return_code": 0, "return_message": "", "result": {"connection_key": "641d2038c10588df0f8258ac3ee93536"}}

Step 6: Verify the connection

Read the list of organizations with the new connection key:

curl 'https://api.api2cart.com/accounting/v1/organization.list.json?count=1' \
-H 'x-api-key: YOUR_API2CART_API_KEY' \
-H 'x-connection-key: YOUR_CONNECTION_KEY'

Every Odoo company the user may access is returned as one organization, and the current company of the user is marked as default. The sample below is shortened: the full response also carries the addresses, phone numbers and links of the company.

{
  "return_code": 0,
  "return_message": "",
  "result": {
    "total_count": 1,
    "organizations": [
      {
        "id": "1",
        "name": "My Company",
        "default": true,
        "legal_name": "My Company",
        "is_active": true,
        "country_code": "US",
        "tax_number": "US12-3456789",
        "currencies": [{"id": "USD", "name": "US Dollar", "iso3": "USD", "symbol_left": "$", "rate": 1, "default": true}],
        "timezone": "America/New_York",
        "fiscal_year_start_month": 1,
        "fiscal_year_end_day": 31
      }
    ]
  }
}

On a multi-company database, pass the id of the organization as organization_id in the requests that should work with another company; without it, API2Cart uses the default one. The currencies are shared by all companies, because Odoo keeps one currency list per database.

Renewing the API key

When the key expires or is revoked, Odoo stops accepting it, and API2Cart reports invalid credentials on the next call. Create a new key as in Step 3 and pass it with connection.update: send only odoo_api_key and keep the same connection_key, there is no need to connect Odoo to API2Cart again. The same method updates the login, the URL or the database name if they change. On Odoo 18 and newer, note the expiration date of the key when you create it, and renew it before that date to avoid an interruption.

How API2Cart uses your Odoo server

Odoo publishes no request limits for its external API, so the capacity of your server is the only limit. Keep in mind that one API2Cart request is not always one Odoo request: to build a unified response or to validate the input, API2Cart may call Odoo several times. For example, contact.add looks up the country and the state before it creates the contact, and bill.payment.add reads the bill before it registers the payment. Reference data such as currencies and countries is cached by API2Cart, so it is not requested again on every call.

A request that fails because the server is unreachable is attempted up to three times. If Odoo answers with HTTP 429, API2Cart waits for the time in the Retry-After header, if it is 30 seconds or less, and retries the request. A 5xx answer is reported as An internal error on Odoo side, please try again later. and should be retried on your side.

Table of Required Odoo Access Rights for API2Cart Methods

Below is the complete list of Odoo access levels that API2Cart methods need. Use it as a checklist before you connect Odoo Accounting to API2Cart. Read the table with these rules in mind:

• The levels are the names shown on the Access Rights tab of the user in Odoo 19; where Odoo 17 or 18 names a level differently, the older name is given in brackets.
• Every method also needs the Invoicing or Accounting app installed and at least one company the user may access, because that is what the connection check verifies.
• connection.list, connection.delete and connection.supported_integrations work entirely inside API2Cart and need no Odoo rights at all.

Troubleshooting After You Connect Odoo Accounting to API2Cart

Most problems show up right when you connect Odoo to API2Cart, because the credentials are checked before the connection is saved. They usually come down to one of these: