Create a Metering & Billing custom currency

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.

A custom currency is a unit of value that you define for your organization, such as tokens, API calls, or compute units. Because a custom currency isn’t real money, it needs a cost basis, which is a rate that converts one unit of the currency into a fiat amount for invoicing.

In this guide, you’ll create a custom currency, define its first cost basis, and then change its rate.

For background on how currencies and cost bases work, see Currencies.

Create a custom currency

In the Konnect sidebar, click Metering & Billing > Settings.
Click the Currencies tab.
Click Create Custom Currency.
In the General Information section, enter the following:
- Name: The display name of the currency, up to 256 characters.
- Code: The identifier for the currency, between 4 and 24 characters. It must be unique within your organization.
- Symbol: An optional short symbol shown alongside amounts, up to 8 characters.
In the Formatting section, enter the following:
- Precision: The number of decimal places, from 0 to 12.
- Decimal Mark: A single character that separates the whole and fractional parts of an amount, such as ..
- Thousand Separator: A single character that groups digits, such as ,.
In the Cost Basis section, define what one unit of your currency is worth:
- Enter the rate as a positive number.
- Select the fiat currency the rate converts into.
To price the same currency against more than one fiat currency, click Add cost basis and define another row. Each row must use a different fiat currency, because a currency can have only one active cost basis per fiat currency at a time.
Click Save.

Validate

In the Konnect sidebar, click Metering & Billing > Settings.
Click the Currencies tab and confirm that your new currency is listed.
Click the currency and confirm that the cost basis you defined is listed with the expected rate.

Change the rate

A cost basis can’t be edited in place. When you update a rate, Metering & Billing adds a new cost basis that takes effect immediately and ends the previous one.

On the currency’s page, in the Cost Basis section, open the actions menu of the active cost basis and click Update Rate.
Enter the new rate.
Click Save.

The new cost basis is listed with the status Active. Expand it to see the previous cost basis with the status Superseded, and confirm that its Effective To date matches the new cost basis’s Effective From date.

To price the currency against another fiat currency, click Add Cost Basis on the currency’s page instead.

Next steps

To charge in your custom currency, use it as the currency of a plan, or override a rate card in a fiat-currency plan to use it. For the rules that apply, see Where currency is set and the Product Catalog reference.

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 custom currency?

Custom currencies are immutable. After you create one, you can’t change its code, name, or formatting, and you can’t delete it. If you need different properties, create a new custom currency.