If you bill your customers through OpenMeter on Kong Konnect Metering & Billing, connecting Kintsugi lets you track your sales tax exposure and prepare filings from your usage-based invoices, without changing how you bill.

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

Before You Begin

Make sure you have the following ready:

• an active Kong Konnect organization with Metering & Billing enabled

• a Konnect user with the Metering & Billing Admin role, so you can create a token with the right access

• the region your Konnect organization runs in: us, eu, au, me, or in

• an active Kintsugi account

• somewhere safe to store your personal access token while you complete setup
  

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

Step 1: Create a Personal Access Token in Kong Konnect

1. Log in to Kong Konnect with a user that has the Metering & Billing Admin role.

2. Under Accounts, go to Personal Access Tokens, and click + Generate Token.

   

3. Create a new token.
   

   1. Give it a name you will recognize later, for example Kintsugi Integration.

   2. Select a token expiration period.

   3. Click Generate to proceed.
      

4. Copy the token value right away and store it somewhere safe.
   

Heads up: Konnect shows the token value only once. If you lose it, create a new token. Kintsugi also never displays your saved token, so keep your own copy until setup is complete.

Step 2: Confirm Your Konnect Region

Each Konnect organization lives in one region. Kintsugi needs to know which one so it reads from the right place.

If you are not sure which region you use, check with your Konnect administrator. Choosing the wrong region is the most common reason a connection is rejected.

Step 3: Connect OpenMeter in Kintsugi

1. Log in to Kintsugi.

2. Click Data Sources.

   

3. Under the Integrations section, click Browse Integrations.

   

4. Select the OpenMeter integration card and click Connect.

   

5. Complete the fields in the connection form:
   

   1. Region: the region you confirmed in Step 2

   2. Personal Access Token: the token you copied in Step 1

   3. Label (optional): a name for this connection, for example the business or Konnect organization it belongs to

   4. Click Connect.

Kintsugi checks your token and region 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 what each error means.

Once connected, the OpenMeter card on your Data Sources page shows your label as its title. If you left the label blank, it shows your Konnect organization name instead.

Step 4: Wait for the Initial Sync to Finish

Kintsugi begins importing your Konnect data right away. While that runs, the integration status shows Syncing.

Kintsugi imports the following:

• customers, including their billing address

• issued invoices, including every invoice line

• products, created from your invoice lines

How long this takes depends on how much history is in your Konnect organization.

To check that the sync is working, go to the Customers, Transactions, or Products page, open the Source filter, and select OpenMeter.

Once the sync is complete, the OpenMeter status updates to Read-Only, confirming that your OpenMeter data is live in Kintsugi.

Step 5: Complete Your Setup Tasks

A. Review Product Categories

Kintsugi creates products from your invoice lines, and these products arrive uncategorized. Usage lines that share the same feature key become one product. Lines without a feature key, such as flat fees, each become their own product. 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

Konnect sends a billing address for each customer but no shipping address, so complete billing addresses matter. Kintsugi still imports a customer when the city or postal code is missing, and flags it 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. Manage Tax Exemptions

Keep two things in mind for customers imported from Konnect:

• Customer tax IDs are not imported. Konnect does not provide a tax ID for customers, so the tax ID field stays blank on every customer that comes from Konnect. A blank tax ID does not make a customer exempt or taxable.

• Exemption status is not imported. Konnect does not track sales tax exemptions, so add an exemption certificate in Kintsugi for any customer who should not be charged sales tax.

For detailed instructions, 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 OpenMeter card on your Data Sources page shows Read-Only instead of Syncing

• your issued Konnect invoices appear in Kintsugi as transactions

• invoice numbers in Kintsugi match the invoice numbers in Konnect
  

What Kintsugi Syncs from OpenMeter

How invoice statuses map

If an invoice that was already imported is later removed from Konnect, Kintsugi cancels the matching transaction on the next sync.

What is not synced

• credit notes and refunds

• a separate product catalog (products come only from invoice lines)

• customer tax IDs and shipping addresses

Each sync rereads your customers and invoices, updating existing records in place, so nothing is duplicated within the OpenMeter connection.

Troubleshooting

"Token rejected - check the token and region."

Either the token is wrong or expired, or it does not belong to the region you selected. Confirm your region in Step 2, then paste the token again. If it still fails, create a new token in Konnect.

"No Metering & Billing customers in this region."

The token works, but Kintsugi found no Metering & Billing customers in that region. Double-check that you selected the region where your Konnect organization actually bills customers.

"Token needs Metering & Billing read access."

The token was created by a user without access to Metering & Billing. Have a user with the Metering & Billing Admin role create a new token, then reconnect.

The connection worked before and now shows an error

Your token was probably revoked or expired in Konnect. Create a new token, then open the OpenMeter connection in Kintsugi and choose Re-authorize. Your region and label are already filled in, so you only need to paste the new token.

Some invoices are missing

Kintsugi imports issued invoices only. Invoices still in Draft in Konnect appear after they are issued and the next sync runs.

The same sales appear twice in Kintsugi

This can happen when your Konnect invoices are also sent to Stripe and Stripe is connected to Kintsugi, so each sale is imported once from each source. Reach out to our team through the chat bubble and we will help you sort out which source to keep.

You use OpenMeter Cloud or self-hosted OpenMeter

These versions are not supported by this integration. Only Kong Konnect Metering & Billing can be connected.

FAQs

Q: Is my Konnect data safe?

A: Yes. Kintsugi reads only what it needs to track your tax exposure, and it writes nothing back to Konnect. Your token is stored securely and is never displayed again after you save it.

Q: Will connecting OpenMeter change my invoices?

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

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

A: Yes. If your Konnect invoice lines include tax, Kintsugi imports that amount. Invoices without tax import with a tax amount of zero.

Q: How are discounts handled?

A: Kintsugi imports each line's amount from Konnect as it appears before discounts. Discounts are not imported as a separate field at this time.

Q: Can I connect more than one Konnect organization or region?

A: Reach out to us if you need more than one Konnect organization or region.

Q: Can I disconnect OpenMeter later?

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

Q: Can Kintsugi calculate tax inside Konnect?

A: Not at this time. The OpenMeter integration is read-only and supports data sync, exposure tracking, and filing preparation.

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.