Create and apply Metering & Billing tax codes

Uses: Metering & Billing

Incompatible with

on-prem

Prerequisites

Kong Konnect

This tutorial requires a Konnect Plus account. If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.

Konnect roles

You need the Metering & Billing Admin role in Konnect to configure Metering & Billing.

Tax codes classify goods and services so that your payment provider can calculate tax correctly on invoices. Metering & Billing pre-provisions the most commonly used Stripe tax codes for every organization and sets two defaults at org creation time.

In this guide, you’ll:

Review your system-managed defaults
Create a custom tax code
Apply a tax code at the organization or rate-card level

For background on how tax codes work and how the fallback chain is evaluated, see Tax codes.

Review default organization tax codes

When your organization is created, Metering & Billing sets up two defaults: one for invoicing and one for credit grants. Review these before creating custom codes, as the pre-provisioned codes may already cover your needs.

In the Konnect sidebar, click Metering & Billing > Settings.
Click the Tax Codes tab.
Review the list of system-managed and user-created tax codes and the current defaults.
To change which code is the default, click the action menu on any row and select Set as Invoicing Default or Set as Credit Grant Default.

If the system-managed codes cover your needs, you can skip the next step and go directly to Apply a tax code to a rate card.

Create a tax code

If none of the system-managed codes match your product category, you can create a custom tax code:

In the Konnect sidebar, click Metering & Billing > Settings.
Click the Tax Codes tab.
Click Create tax code.
Enter a name, key, and optional description.
(Optional) Add one or more app mappings. For Stripe, the value must follow the txcd_XXXXXXXX format. You can browse available values in the Stripe Tax Code reference.
(Optional) Set the code as the Invoicing Default or Credit Grant Default.
Click Save.

Note: Only one tax code can be set as the default per category at a time. You can’t delete a default tax code. To delete it, first set a different code as the default, then delete the original.

Apply a tax code to a rate card

You can apply a tax code at two levels within your product catalog.

Apply a tax code on a plan or add-on rate card

This sets the tax code for a specific product or fee, overriding the organization default.

In the Konnect sidebar, click Metering & Billing > Product Catalog.
Click the Plans or Add-ons tab and select a plan or add-on.
Open or create a rate card.
In the Pricing Model configuration, expand Advanced Settings.
In the Tax Behavior dropdown, select the behavior you want to apply.
In the Tax Code dropdown, select your custom code.
Save the rate card.

Apply a tax code on a subscription rate card

This overrides the tax code for a specific customer’s subscription, without changing the underlying plan.

In the Konnect sidebar, click Metering & Billing > Billing.
Click a customer.
Click the Subscription tab.
Click Manage and expand Advanced Settings.
Enable Advanced Customization.
Click Next.
Edit or create a rate card.
In the Pricing Model configuration, expand Advanced Settings.
In the Tax Behavior dropdown, select the behavior you want to apply.
In the Tax Code dropdown, select your custom code.
Save the rate card.

Cleanup

Clean up Konnect environment

If you created a new control plane and want to conserve your free trial credits or avoid unnecessary charges, delete the new control plane used in this tutorial.

FAQs

Why can’t I edit or delete a tax code?

Edit and delete actions are only available for user-managed codes. System-managed codes are read-only and can’t be modified.