Currencies

Every monetary amount in Konnect Metering & Billing has a currency. Metering & Billing supports two kinds of currency: fiat currencies and custom currencies.

• Fiat currencies are the currencies defined by the ISO 4217 standard.
• Custom currencies are units of value that you define yourself, such as LLM credits or tokens, so you can price and grant things that aren’t money.

Invoices are always issued in a fiat currency. A custom currency becomes billable only once you give it a cost basis, which is an explicit rate against a fiat currency.

A fiat currency is identified by its three-letter ISO 4217 code, such as USD, EUR, or JPY. Metering & Billing accepts any code defined by the standard.

The standard supplies each currency’s display name, symbol, precision, decimal mark, and thousands separator, so you don’t configure any of these. For example, USD uses two decimal places and JPY uses none.

Only a fiat currency can be invoiced and settled through a payment provider.

A custom currency is a unit of value that you define for your organization. Use one when you price in something other than money, such as LLM provider credits, tokens, or compute units.

Unlike a fiat currency, a custom currency has no standard definition, so you supply its display properties yourself. A custom currency also has no intrinsic value until you attach a cost basis to it.

A custom currency has the following properties:

Note: A custom currency is immutable. After you create one, you can’t change its properties or delete it. Its cost bases are separate resources that you can keep adding to over time.

A cost basis is a rate that converts one unit of a custom currency into an amount of a fiat currency. It’s the only conversion mechanism in Metering & Billing. There is no automatic foreign exchange, and no conversion between two fiat currencies or between two custom currencies.

Each cost basis records the following:

Cost bases are append-only. To change a rate, add a new cost basis for the same fiat currency. Metering & Billing ends the cost basis that’s active at the new cost basis’s effective date by setting its effective-to date to that time. After that time passes, the Konnect UI shows the earlier cost basis as Superseded. The rate of the superseded cost basis doesn’t change, so the historical rates stay intact.

A single custom currency can carry cost bases against several fiat currencies at once. For any one fiat currency, only one cost basis is active at a time, and its successive cost bases cover consecutive time windows.

Metering & Billing derives the currency of an invoice from the plan, the customer, and any rate card overrides. The following diagram follows a charge’s currency from the product catalog to the invoice:

 
flowchart TB
    subgraph define["1. Define"]
        direction LR
        plan["Plan
Currency: fiat or custom
Settlement mode"]
        rate-card["Rate card
Inherits the plan currency,
or overrides a fiat plan's
currency to a custom one"]
        plan --> rate-card
    end

    subgraph subscribe["2. Subscribe"]
        direction LR
        customer["Customer
Currency: fiat"]
        subscription["Subscription
Fixes the invoice currency:
the plan's, if it's fiat
the customer's, if it's custom"]
        customer --> subscription
    end

    subgraph settle["3. Settle each charge"]
        direction LR
        credits["Credit balance
In the charge's currency"]
        cost-basis["Cost basis
Converts the custom
currency into the
invoice currency"]
    end

    invoice["4. Invoice
In the invoice currency
Always fiat, rounded
to its precision"]

    define --> subscribe
    subscribe -->|"Charges draw on credits first"| credits
    credits -->|"credit_only: settled here"| done(["No invoice line
A shortfall becomes
a negative balance"])
    credits -->|"credit_then_invoice:
remaining custom amount"| cost-basis
    credits -->|"credit_then_invoice:
remaining fiat amount"| invoice
    cost-basis --> invoice
  

The following table describes where each currency value comes from:

Rate card overrides

A rate card can override the currency it inherits, within these rules:

• If the plan or add-on uses a fiat currency, you can override a rate card to a custom currency.
• You can’t override one fiat currency with another fiat currency, because a plan can hold only one fiat currency.
• You can’t override a rate card that already inherits a custom currency.
• The override must differ from the currency it replaces.
• The custom currency needs a cost basis that’s active against the plan’s fiat currency, unless the plan uses the credit_only settlement mode.

Metering & Billing rounds every monetary amount to the precision of its currency, rounding halves away from zero.

Rounding applies at each stage of the calculation, including the invoice total. Metering & Billing rounds individual line items, pricing tiers, and discount or commitment adjustments to the currency’s precision, and then rounds the resulting totals again. For a custom-currency amount, Metering & Billing converts the amount through its cost basis and rounds the result to the precision of the fiat currency.

Keep the following constraints in mind when you plan your product catalog:

• An invoice covers a single currency. If a customer is migrated between currencies, they can have one gathering invoice per currency.
• A subscription’s invoice currency is fixed for the life of the subscription.
• There is no exchange rate between fiat currencies. To sell in several fiat currencies, create one plan per currency, or price a plan in a custom currency that has a cost basis for each fiat currency you sell in.
• A custom currency is immutable and can’t be deleted after you create it.
• Custom currencies are only available through the v3 API. The v1 API rejects resources that use a custom currency.

The following errors are specific to currency configuration:

Creating a custom currency with a code that already exists in your organization returns a conflict error instead of a validation error.