FeaturesBilling

Integration

End-to-end billing integration checklist for web apps.

What It Does

Documents the app-level files and runtime wiring needed for billing to operate correctly.

When To Use

First-time billing activation in an app.

Prerequisites

Provider credentials available.

Operational Note

Validate credentials, secrets, and runtime environment values before promoting changes to production.

How To Use

Add env vars.

Stripe example:

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_xxx
STRIPE_SECRET_KEY=sk_live_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx

Configure billing.

Set billingConfig in app config (provider, products, currency, etc.).

Initialize filters.

apps/dashboard/hooks/use-filters.ts should call:

useBillingFilters({ billingConfig });

Add webhook route.

apps/dashboard/app/api/billing/webhook/route.ts:

import { createBillingWebhookHandler } from '@kit/billing/server';
import { billingConfig } from '~/config/billing.config';
 
export const POST = createBillingWebhookHandler(billingConfig);

Validate settings page.

Confirm billing page renders in settings (injected by billing settings filter).

Filter API

Billing integration is operational only when client, cross-env, and server filter wiring are all initialized.

Filter	Parameters	Return	Registered By (package file)	Initialized In (app entrypoint)	Environment
`get_settings_ui_config`	`{ clientTrpc: TrpcClientWithQuery<Router<unknown>> }`	`ReturnType<typeof parseUISettingConfig>`	`kit/billing/core/src/www/filters/use-filters/use-settings-filters.tsx`	`apps/dashboard/hooks/use-filters.ts` (`useBillingFilters`)	`client`
`cross_env_get_translations`	`{ language: string; namespace: string }`	`Record<string, string> \| null`	`kit/billing/core/src/www/filters/cross-env-filters.ts`	`apps/dashboard/lib/init-cross-env-filters.ts`	`cross-env`
`cross_env_get_namespaces`	`{}`	`string[]`	`kit/billing/core/src/www/filters/cross-env-filters.ts`	`apps/dashboard/lib/init-cross-env-filters.ts`	`cross-env`
`server_get_billing_entities`	`{}`	`Record<string, new (db: AppClient) => AbstractBillingEntity>`	`kit/organization/src/www/filters/server-filters.ts`	`apps/dashboard/lib/init-server-filters.ts` (`initOrgServerFilters`)	`server`

Init Checklist

apps/dashboard/hooks/use-filters.ts must call useBillingFilters({ billingConfig }).
apps/dashboard/lib/init-cross-env-filters.ts must call initBillingFilters().
apps/dashboard/lib/init-server-filters.ts must call initOrgServerFilters({ orgConfig }).

MCP Context


capability: billing_integration
entrypoints:
  - apps/dashboard/config/billing.config*.ts
  - apps/dashboard/hooks/use-filters.ts
  - apps/dashboard/lib/init-cross-env-filters.ts
  - apps/dashboard/lib/init-server-filters.ts
  - kit/billing/core/src/www/filters/use-filters/use-settings-filters.tsx
  - kit/billing/core/src/www/filters/cross-env-filters.ts
  - kit/organization/src/www/filters/server-filters.ts
  - apps/dashboard/app/api/billing/webhook/route.ts
inputs:
  - provider_keys
  - product_catalog
outputs:
  - checkout_and_subscription_workflow
constraints:
  - webhook endpoint must be configured in provider dashboard
side_effects:
  - updates subscription and wallet state

Agent Recipe

Add env vars + config.
Wire filters + webhook.
Perform end-to-end checkout and webhook validation.

Troubleshooting

400 webhook errors usually mean invalid webhook secret.
Checkout UI errors usually indicate missing publishable key.

Billing

Subscriptions, checkout, invoices, and wallet flows with @kit/billing.

User Settings

Billing account, invoices, and subscriptions inside settings.

How is this guide?

Last updated on 3/27/2026