/ /

Odoo Read-Only Integration Guide

Connect Odoo to Kintsugi to automate sales tax
Updated last month

If you run your accounting in Odoo, connecting it to Kintsugi lets you track your sales tax exposure, monitor nexus, and prepare filings from the invoices you already post in Odoo, without changing how you invoice.

What is a read-only integration? A read-only integration lets Kintsugi pull data from Odoo without writing anything back. Nothing in your invoicing process changes, no tax is added to your invoices, and your data stays exactly where it is.

Odoo Plan Requirement

Kintsugi connects through Odoo's External API. Odoo makes the External API available only on its Custom plan. If your database is on the One App Free or Standard plan, upgrade before you start.


Before You Begin

Make sure you have the following ready:

  • an Odoo database with the Accounting or Invoicing app installed, where you post your customer invoices

  • an Odoo plan that includes External API access

  • an Odoo user with access to your accounting records, such as the Billing Administrator or Accounting access rights. We recommend a dedicated integration user, so the connection keeps working if a team member leaves.

  • an active Kintsugi account

  • somewhere safe to store your API key while you complete setup

You will collect four details from Odoo: your base URL, database name, username, and API key. Steps 1 to 4 show where to find each one.


Step-by-Step Guide for Odoo Read-Only Integration

Step 1: Find Your Odoo Base URL

Your base URL is the web address you use to sign in to Odoo, without anything after the domain.

  • Odoo Online: https://yourcompany.odoo.com

  • Odoo.sh or self-hosted: the address of your Odoo server, for example https://odoo.yourcompany.com

Copy only the part up to the domain. For example, if your browser shows https://yourcompany.odoo.com/odoo/accounting, use https://yourcompany.odoo.com.

Heads up: The URL must start with https:// and must be reachable from the internet. Kintsugi cannot connect to a local or private network address.


Step 2: Find Your Database Name

  • Odoo Online: your database name is usually the first part of your URL. For https://yourcompany.odoo.com, the database name is yourcompany.

  • Odoo.sh or self-hosted: one server can host several databases, so the name may differ from your URL. Ask your Odoo administrator or hosting partner to confirm the exact database name.

Enter the database name exactly as it appears in Odoo, including capitalization.


Step 3: Confirm Your Username

Your username is the login email of the Odoo user you are connecting with, the same email you type on the Odoo sign-in page.

Use the same user in Step 4 to create the API key. The key only works with the user who created it.


Step 4: Create an API Key in Odoo

An API key lets Kintsugi sign in as your Odoo user without using your password.

  1. Sign in to Odoo as the user from Step 3.

  2. Click your profile avatar in the top right corner, then click My Preferences (shown as My Profile in some versions).

  3. Open the Account Security tab, then click New API Key.

  4. Confirm your Odoo password when prompted.

  5. Enter a clear description, for example Kintsugi Integration, then click Generate Key.

  6. Copy the key right away and store it somewhere safe.

Heads up: Odoo shows the API key only once. If you lose it, delete it under Account Security and create a new one. If you do not see the New API Key button, activate developer mode first (Settings, then scroll down and click Activate the developer mode) and try again.

Step 5: Connect Odoo in Kintsugi

  1. Log in to Kintsugi.

  2. Click Data Sources.

    image.png
     

  3. Under the Integrations section, click Browse Integrations.

    image.png

  4. Find the Odoo integration card and click Connect.

image.png

  1. Complete the fields in the Connect Odoo form:

    1. Odoo base URL: the URL from Step 1

    2. Database name: the database name from Step 2

    3. Username: the login email from Step 3

    4. API key or password: the API key you copied in Step 4

    5. Import start date (optional): the earliest invoice date you want Kintsugi to import. Kintsugi does not import invoices or credit notes dated before January 1, 2019.

    6. HMAC secret: leave this blank. It is only used for the Odoo tax engine integration.

    7. Click Connect.

image.png

Kintsugi checks your details with Odoo before saving the connection. If something is wrong, nothing is stored, and you can correct the details and try again. See the Troubleshooting section below for common fixes.

Step 6: Wait for the Initial Sync to Finish

Kintsugi begins importing your Odoo data as soon as the connection is saved. While that runs, the integration status shows Syncing.

Kintsugi imports the following:

  • customers, including their address, email, phone, and tax ID

  • products

  • customer invoices and receipts, including every product line

  • credit notes

How long this takes depends on how much history is in your Odoo database. To check your data, go to the Customers, Transactions, or Products tab, use the Source filter, and select Odoo.

Once the sync is complete, the Odoo status updates to Read-Only, confirming that your Odoo data is live in Kintsugi. After that, Kintsugi keeps importing new and updated records automatically.

Step 7: Complete Your Setup Tasks

A. Review Product Categories

Your Odoo products arrive uncategorized. Review them so tax is calculated correctly. Kintsugi Intelligence suggests a category and subcategory for each one.

To review products:

  1. Click Review on the pending task notification.

  2. Approve the AI-generated suggestions in bulk or individually.

For detailed instructions, see Updating Product Category and Subcategory.

B. Update Invalid and Blank Addresses

Kintsugi uses the billing and shipping addresses on your Odoo invoices to determine where tax applies. Any customer or invoice with a missing or invalid address is flagged for you to fix.

To correct Invalid Addresses:

  1. Click Bulk Cleanup to update multiple addresses at once, or

  2. Correct invalid addresses individually as needed.

    For more information, see How to Update Invalid Addresses in the Kintsugi App.

And, to edit Blank Addresses:

  1. Click Add Addresses on the pending task list.

  2. Edit blank addresses individually as needed.

    To learn more, see How to Update Blank Addresses in the Kintsugi App.

C. Review Tax Exemptions

Kintsugi imports customer exemptions from Odoo fiscal positions. If a customer's default fiscal position has a Tax Mapping that removes sales tax (replaces it with no tax or a 0% tax), Kintsugi marks that customer as exempt.

Kintsugi looks only at the Tax Mapping, not the fiscal position name. A fiscal position named "Exempt" or "Resale" that does not remove tax does not create an exemption.

For any other exempt customers, add their exemption certificates in Kintsugi. See How to Import a Single Exemption Certificate and How to Bulk Upload Exemption Certificates.


How to Confirm the Integration Works

You will know the connection is healthy when all of the following are true:

  • the Odoo card on your Data Sources page shows Read-Only instead of Syncing

  • your posted Odoo invoices appear in Kintsugi as transactions

  • invoice numbers in Kintsugi match the invoice numbers in Odoo (for example, INV/2026/00006)


What Kintsugi Syncs from Odoo

Odoo record

Appears in Kintsugi as

Notes

Customers

Customers, with name, email, phone, address, and tax ID

Only contacts used in sales. The Odoo Tax ID field imports as the customer tax ID.

Products

Products, with name, SKU, and description

Active products only. The Odoo Internal Reference imports as the SKU.

Customer invoices and receipts

Transactions

Each product line imports as a line item. Section and note lines are skipped.

Credit notes

Credit notes

Linked to the original invoice when created with Credit Note from that invoice.

Line discounts (Disc.%)

Line item discounts

Discounts are applied once, so your taxable amount matches Odoo.

Tax already on invoices

Imported tax

Works whether your prices are set as tax included or tax excluded.

How invoice statuses map

Odoo invoice status

In Kintsugi

Draft

Pending

Posted

Committed

Cancelled

Cancelled

How payment statuses map

Odoo payment status

In Kintsugi

Not Paid, In Payment, Blocked

Unpaid

Partially Paid

Partially paid

Paid, Reversed

Paid

Kintsugi treats In Payment as unpaid because Odoo has registered the payment but not yet matched it to a bank transaction.

What is not synced

  • vendor bills and other purchase records

  • journal entries that are not customer invoices

  • payments, including store credit applied as a payment (this does not change the tax on the original invoice)

  • extra invoice and delivery addresses saved under a customer contact (the addresses on each invoice are still imported with that transaction)

One Odoo database with several companies

Kintsugi does not yet let you pick a single company within a database. If your Odoo database holds more than one company, invoices from every company sync into the same Kintsugi organization.


Troubleshooting

The connection is rejected when you click Connect

Check each field: the base URL starts with https:// and has nothing after the domain, the database name matches exactly, the username is the user's login email, and the API key was created by that same user. If it still fails, create a new API key and paste it again.

Your Odoo server is on a private network

Kintsugi can only reach an Odoo server with a public https:// address. Ask your IT team or hosting partner to make the server reachable, then connect again.

The connection worked before and now shows an error

The API key may have been deleted, or the Odoo user may have been archived or lost access. Create a new API key for an active user with accounting access, then update the Odoo connection in Kintsugi.

Some invoices are missing

Check the import start date on your connection. Invoices dated before that date, or before January 1, 2019, are not imported.

An exempt customer is not marked exempt

Open the customer in Odoo and check Sales & Purchase > Fiscal Position. The fiscal position must include a Tax Mapping that removes sales tax. Also make sure the connected Odoo user can view fiscal positions. If the mapping cannot be read, customers still sync but are not marked exempt.


FAQs

Q: Is my Odoo data safe?

A: Yes. Kintsugi reads only what it needs to track your tax exposure, and it writes nothing back to Odoo. Your API key is stored securely and encrypted.

Q: Will connecting Odoo change my invoices?

A: No. A read-only connection never writes to Odoo, and no tax is added to your invoices.

Q: Should I use my password or an API key?

A: Use an API key. It gives the same access as your password but can be removed at any time without changing how you sign in to Odoo.

Q: Does Kintsugi import tax that is already on my Odoo invoices?

A: Yes. Kintsugi imports the tax charged on each invoice line, whether your prices are set as tax included or tax excluded. Kintsugi then calculates your liability separately on the untaxed amount.

Q: How are discounts handled?

A: Line discounts (Disc.%) on invoices import as discounts, and Kintsugi subtracts them only once, so your taxable amount matches Odoo.

Q: Does this work with Odoo Online?

A: Yes. The read-only integration works with Odoo Online, Odoo.sh, and self-hosted Odoo, as long as your plan includes External API access.

Q: Can I disconnect Odoo later?

A: Yes. Open the connection menu on the Odoo card in Data Sources and choose Disconnect. Syncing stops right away.

Q: Can Kintsugi calculate tax inside Odoo?

A: Yes, with the separate Odoo tax engine integration, which uses the Kintsugi Tax addon. It is available for Odoo.sh and self-hosted Odoo, not Odoo Online. Complete this read-only setup first.


Need Help?

We are always here to help. If you cannot find the answer you are looking for, reach out using the chat bubble in the bottom right corner of your screen.

Was this article helpful?