Subscriptions

Subscriptions in Metering & Billing create relationships between customers and their pricing model.. They are the bridge between your customers, their usage data, and how that usage translates into billable amounts.

Subscriptions automate the billing lifecycle by:

  • Tracking usage through meters
  • Applying pricing logic from plans or custom configurations
  • Generating invoices based on billing cadences
  • Enforcing entitlements to control feature access

Subscriptions can be created from predefined plans or fully customized at creation time to accommodate unique customer requirements. This flexibility supports everything from self-serve sign-ups to enterprise contract negotiations.

Subscriptions follow a billing cycle determined by their related rate card, anchored to one of the following:

  • The subscription start date, either the creation date or a specified future date.
  • The first day of the month, with usage prorated for the partial initial period.

To add a subscription to a customer, navigate to Metering & Billing > Billing, click your customer, and then click the Subscriptions tab in the Konnect UI.

Active customer subscriptions can be enhanced with add-ons, which allow you to make changes to a customer’s entitlements without changing the plan directly.

Change plans

Changing a plan switches a customer to a completely different plan. This is equivalent to canceling the current subscription and starting a new one on the new plan, but without any interruption in service.

To change a customer’s plan:

  1. In the Konnect sidebar, click Metering & Billing.
  2. In the Metering & Billing sidebar, click Billing.
  3. Click the customer whose subscription you want to change.
  4. Click the Subscription tab.
  5. Click Manage.
  6. Select the new plan.
  7. Click Next.
  8. Select when the plan change should be effective At the end of the billing period or Immediately.
    • At the end of the billing period: Select for downgrades to avoid disrupting the customer’s current service period.
    • Immediately: Select for upgrades so the customer gets access to the new plan right away.
  9. Click Save Changes.

Cancel a subscription

Canceling a subscription ends it and stops future invoices from being generated. You can cancel immediately or at the end of the current billing period.

To cancel a subscription:

  1. In the Konnect sidebar, click Metering & Billing.
  2. In the Metering & Billing sidebar, click Billing.
  3. Click the customer whose subscription you want to cancel.
  4. Click the Subscriptions tab.
  5. Click Cancel Subscription.
  6. Select when the plan change should be effective At the end of the billing period or Immediately.
    • At the end of the billing period: Select for downgrades to avoid disrupting the customer’s current service period.
    • Immediately: Select for upgrades so the customer gets access to the new plan right away.
  7. Click Save Changes.

Plan migration

Plans in Metering & Billing are versioned. When you publish a new version of a plan, existing subscriptions remain on the previous version until explicitly migrated. This is known as grandfathering, customers keep their existing pricing until you choose to migrate them.

Migrating a subscription to a new plan version allows you to:

  • Apply new pricing to existing customers
  • Transition customers to improved plan structures
  • Deprecate old plan versions
  • Standardize customers on current offerings

You can migrate customers selectively, migrating enterprise customers first and rolling out changes to self-serve customers later, for example.

To migrate a subscription to a new plan version:

  1. In the Konnect sidebar, click Metering & Billing.
  2. In the Metering & Billing sidebar, click Billing.
  3. Click the customer whose subscription you want to migrate.
  4. Click the Subscriptions tab.
  5. Click Manage.
  6. Click Migrate.
  7. Click Next.
  8. Choose when the migration should be effective: At the end of the billing period or Immediately.
  9. Click Save.

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!