Kinde Billing

Reactive Kinde billing integration for Convex with automatic webhook handling, subscription state management, and feature gating.

Installation

npm install convex-kinde-billing

About Kinde Billing

Kinde Billing integrates Kinde's subscription billing with Convex through webhook handling and reactive queries. It automatically syncs subscription state, plan assignments, and billing events from Kinde webhooks into your Convex database. Provides feature gating functions like hasActivePlan() and hasFeature(), plus checkout URL generation and self-serve billing portal access.

Benefits

Automatically sync Kinde billing webhooks to reactive Convex queries without writing webhook handlers
Gate features and routes with real-time subscription status using hasActivePlan() and hasFeature() methods
Generate hosted checkout URLs and self-serve billing portal links with simple API calls
Query billing events, usage records, and subscription data directly from Convex functions

Use cases

how to add Kinde billing to Convex app

Install convex-kinde-billing, mount the webhook handler in convex/http.ts, and register the webhook URL in Kinde. The component automatically syncs billing events to Convex and provides reactive queries for subscription status.

Convex feature gating based on subscription

Use kindeBilling.hasActivePlan() or kindeBilling.hasFeature() in Convex queries and mutations to gate features by subscription status. These methods return reactive boolean values that update automatically when billing changes.

Kinde hosted checkout integration Convex

Call kindeBilling.getCheckoutUrl() with your client ID, redirect URI, and plan key to generate a Kinde-hosted checkout URL. After payment, webhooks automatically update your Convex billing state.

self-serve billing portal Kinde Convex

Use kindeBilling.getPortalUrl() with the user's access token to generate one-time billing portal links. The component also provides a React ManageBillingButton component for drop-in portal access.

Frequently asked questions

How does convex-kinde-billing sync billing data?

The convex-kinde-billing component receives Kinde webhook events through a mounted HTTP handler and automatically stores subscription status, billing events, and usage records in Convex. This data becomes available through reactive queries that update in real-time when billing changes occur.

What billing events does this component handle?

The convex-kinde-billing component handles all 8 Kinde billing webhook events including customer.plan_assigned, customer.agreement_created, customer.subscription_updated, customer.payment_succeeded, and customer.subscription_cancelled. Each event updates the corresponding Convex database records automatically.

Can I query metered usage data with this component?

Yes, convex-kinde-billing stores and provides access to metered usage records through the getUsage() method. You can query usage by customer ID and meter ID, with results returned in real-time as new usage events arrive via webhooks.

How do I gate features by subscription plan?

Use kindeBilling.hasActivePlan() to check if a customer has any active subscription, or kindeBilling.hasFeature() to check for specific plan features. Both methods work in Convex queries and mutations and automatically update when subscription status changes through webhook events.