Get started with prepaid credits

This feature is currently in Beta and should not be used in a production environment.
TL;DR

To set up a prepaid billing model for a customer using credits, you need to:

  1. Create a credits-only plan
  2. Create a customer
  3. Start a subscription
  4. Grant prepaid credits
  5. Monitor the credit ledger

Metered usage automatically draws down from the grant balance.

Prerequisites

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

  1. The following Konnect items are required to complete this tutorial:
    • Personal access token (PAT): Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.
  2. Set the personal access token as an environment variable:

    export KONNECT_TOKEN='YOUR KONNECT TOKEN'

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

You need a configured meter, such as API Gateway requests or AI Gateway tokens.

Create a credits-only plan

To charge customers via prepaid credits, define a plan with the credit_only settlement mode. All usage settles against credits. If a customer runs out of credits, uncovered usage creates a negative credit balance on the ledger rather than generating an overage invoice.

  1. In the Konnect sidebar, click Metering & Billing.
  2. Click Product Catalog.
  3. Click the Plans tab and create a new plan.
  4. In the Billing section, configure the Currency (for example, USD) and set the Settlement mode to Credits only.
  5. Click Add Rate Card and select the feature you want to price.
  6. Configure a Usage based pricing model and set your price per unit.
  7. Save the rate card and click Publish Plan.

Create a customer

Customers represent the individuals or organizations that subscribe to plans and consume your metered features.

  1. In the Konnect sidebar, click Metering & Billing.
  2. In the Metering & Billing sidebar, click Billing.
  3. Click Create Customer.
  4. Enter the customer’s Name.
  5. Map the customer to a Consumer, Application, or Subject to ensure their usage is attributed correctly.
  6. Click Save.

Start a subscription

Subscriptions link customers to a pricing model and track their usage against rate cards.

  1. On the customer’s details page, click the Subscriptions tab.
  2. Add a new subscription and select the credits-only plan you created.
  3. Choose the start date and finalize the subscription.

Grant prepaid credits

Prepaid credits burn down as the customer incurs usage. Issue a grant directly to the customer’s balance.

  1. On the customer’s page, click the Credits tab.
  2. Click Grant Credits and select New credit grant.
  3. In the Grant section, enter the Credit amount.
  4. In the Charge section, select Promotional / Free as the charge type.
  5. Set the Credit availability to Available immediately on grant.
  6. Optionally, expand Policies to set a Credit draw-down order to control consumption priority if this customer has multiple grants.
  7. Click Next to review the Grant Summary.
  8. Click Grant credits to finalize.

A funded movement is recorded in the customer’s transaction history and their settled balance increases immediately.

Monitor the credit ledger

After the grant is issued, the customer’s available balance reflects the new credits. Because this customer is on a credit_only plan, metered usage automatically deducts from this balance.

  1. On the customer’s page, click the Credits tab.
  2. Click Transaction History.

You’ll see:

  • A funded movement with a positive amount for the grant you issued.
  • consumed movements with negative amounts as usage charges are applied.
  • The running balance before and after each movement.

For more on movement types, pagination, and corrections, see Credit transaction history.

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!