---
name: bijection-convex-kinde-billing
description: "Evaluate and integrate the Kinde Billing component with Bijection."
---

# Kinde Billing

Add Kinde billing to your Convex app. Reactive subscriptions, checkout, self-serve portal, and feature gating.

This is an upstream package. It has not been adapted or qualified for Bijection.

- Package: convex-kinde-billing
- Source: https://github.com/sholajegede/convex-kinde-billing
- npm: https://www.npmjs.com/package/convex-kinde-billing
- Directory: https://bijection.com/components/convex-kinde-billing

Read the upstream README for setup, license, and compatibility before using it.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-kinde-billing. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


# Kinde Billing

## Instructions

Use Kinde Billing to reactive kinde billing integration for convex with automatic webhook handling, subscription state management, and feature gating. This Convex component integrates directly with your backend.

### Installation

```bash
npm install convex-kinde-billing
```

### Capabilities

- 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

## Examples

### 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.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Kinde Billing is not needed

## Troubleshooting

**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.

## Resources

- [npm package](https://www.npmjs.com/package/convex-kinde-billing)
- [GitHub repository](https://github.com/sholajegede/convex-kinde-billing)
- [Live demo](https://convex-kinde-billing-demo.vercel.app)
- [Convex Components Directory](https://www.convex.dev/components/convex-kinde-billing)
- [Convex documentation](https://docs.convex.dev)