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.
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.
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.
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.
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.
An API key lets Kintsugi sign in as your Odoo user without using your password.
Sign in to Odoo as the user from Step 3.
Click your profile avatar in the top right corner, then click My Preferences (shown as My Profile in some versions).
Open the Account Security tab, then click New API Key.
Confirm your Odoo password when prompted.
Enter a clear description, for example Kintsugi Integration, then click Generate Key.
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.
Log in to Kintsugi.
Click Data Sources.
Under the Integrations section, click Browse Integrations.
Find the Odoo integration card and click Connect.
Complete the fields in the Connect Odoo form:
Odoo base URL: the URL from Step 1
Database name: the database name from Step 2
Username: the login email from Step 3
API key or password: the API key you copied in Step 4
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.
HMAC secret: leave this blank. It is only used for the Odoo tax engine integration.
Click Connect.
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.
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.
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:
Click Review on the pending task notification.
Approve the AI-generated suggestions in bulk or individually.
For detailed instructions, see Updating Product Category and Subcategory.
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:
Click Bulk Cleanup to update multiple addresses at once, or
Correct invalid addresses individually as needed.
For more information, see How to Update Invalid Addresses in the Kintsugi App.
And, to edit Blank Addresses:
Click Add Addresses on the pending task list.
Edit blank addresses individually as needed.
To learn more, see How to Update Blank Addresses in the Kintsugi App.
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.
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)
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. |
Odoo invoice status | In Kintsugi |
|---|---|
Draft | Pending |
Posted | Committed |
Cancelled | Cancelled |
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.
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.
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.
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.
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.