repository·main·Indexed 21 days ago
https://github.com/getpaykit/paykitAn embedded billing framework for TypeScript that allows developers to manage subscriptions, usage-based billing, and entitlements directly in their code and database. PayKit abstracts provider complexities (such as Stripe) using a code-first approach with functions like feature(), plan(), and createPayKit(). It includes a CLI for initialization, database migrations, and plan synchronization, as well as a type-safe client for managing subscriptions and customer portals in the browser.
PayKit is a TypeScript-first, server-side payments orchestration framework designed for modern SaaS. It acts as an orchestration layer between your application and payment providers.
Key responsibilities:
Important distinction: PayKit does not process payments. It does not move money or run the actual checkout/vaulting logic; it coordinates the providers that do those tasks.
The web application is a T3 Stack project bootstrapped with create-t3-app. It utilizes the following core technologies:
PayKit handles plan changes differently depending on whether the target plan is more expensive or less expensive than the current plan:
Upgrades happen immediately. The old plan ends and the new plan starts right away. Prorated amounts are handled based on your provider settings.
Downgrades are scheduled. The current plan remains active until the end of the current billing period. PayKit stores the target plan as a scheduled change and transitions the customer once the period ends via a provider webhook.
To cancel a paid subscription, simply call subscribe() with the ID of your default free plan. This follows the downgrade pattern: the paid plan stays active until the end of the period, then automatically switches to free.
PayKit uses specific fonts and content rules:
--font-sans and --font-mono.text-xs, text-sm, text-base). Use arbitrary values only for sub-scale sizes.PayKit skills follow the Agent Skills specification. They are compatible with any coding agent that supports this standard, including:
To ensure your application can switch providers via configuration without requiring code rewrites, avoid using provider-specific identifiers in your core business logic. Instead, rely exclusively on PayKit's unified abstractions:
on handlers will not execute multiple times for the same event, preventing duplicate side effects in your application.If a customer has a pending change (like a scheduled downgrade or cancellation), you can use subscribe() to modify or cancel that pending state:
subscribe() with a different lower-priced plan will replace the existing scheduled target. Only one downgrade can be pending per group at a time.// Scenario 1: Resuming a subscription
// Customer is on "pro" with a pending downgrade to "free"
await paykit.subscribe({ customerId: "user_123", planId: "pro" });
// Scheduled downgrade is cleared. Customer stays on "pro".
// Scenario 2: Changing a scheduled target
// Customer is on "ultra" with a pending downgrade to "free"
await paykit.subscribe({ customerId: "user_123", planId: "pro" });
// Scheduled target changes from "free" to "pro".A group is a collection of plans that are mutually exclusive. A customer can only have one active plan per group at any given time.
Usage Patterns:
base group containing free, pro, and ultra plans.addons group for one-off upgrades.seats group for per-user pricing.Important Rules:
default: true must belong to a group.default: true.default plan without creating a formal subscription record until they subscribe.When checking metered features, the balance object provides the following properties:
limit: The total units allowed for the current period.remaining: The number of units left before the limit is reached.resetAt: The timestamp indicating when the balance will reset.unlimited: A boolean indicating if the plan grants unlimited usage of this feature.