Paykit

Billing and entitlements for your product, declared in TypeScript and deployed with your stack.

Paykit is a billing library for TypeScript products. You declare your features, plans and prices in one file beside your stack. Paykit creates the payment provider’s products and prices at deploy, keeps each account’s balances in your database, and gives your handlers two calls: check and track.

It runs inside your deployment. A check is a local read, so a slow payment provider cannot block your product, and you do not run a second service to bill.

New to Paykit? Start with What is Paykit?.

A quick example

Declare a free plan and a paid one:

import { Paykit } from "@potion.run/paykit";

export const messages = Paykit.feature({ id: "messages", name: "Messages" });

export const free = Paykit.plan({
  id: "free",
  name: "Free",
  grants: [Paykit.planItem(messages, { included: 100 })],
});

export const pro = Paykit.plan({
  id: "pro",
  name: "Pro",
  price: { amount: 1900, currency: "usd", interval: "month" },
  grants: [Paykit.planItem(messages, { included: 2_000, overage: "bill" })],
});

export const catalog = { features: [messages], tiers: [free, pro] };

The deploy validates the catalog and records it in stack state:

import { Paykit } from "@potion.run/paykit";
import * as Alchemy from "alchemy";
import * as Effect from "effect/Effect";
import { catalog } from "./src/catalog.ts";

const billing = {
  catalog,
  providers: [Paykit.Manual()],
  store: Paykit.MemoryStore(),
};

export default Alchemy.Stack(
  "MyApp",
  { providers: Paykit.providers(), state: Alchemy.localState() },
  Effect.gen(function* () {
    const recorded = yield* Paykit.BillingStack("Billing", billing);

    return { tiers: recorded.tiers };
  }),
);

A request checks before the work and tracks after it:

const check = yield* Paykit.Check(account);
const { allowed } = yield* check({ featureId: "messages" });

if (!allowed) return refuse();

// do the work

const track = yield* Paykit.TrackUsage(account);
yield* track({ featureId: "messages", value: 1, idempotencyKey: requestId });

Where to start

Want to build? Getting started takes a catalog through deploy, a subscription, a check and a track. Then Build a billing page shows the customer their usage and the upgrade price.

Looking for a pricing model? Pricing models maps what you sell to the declaration: free plans, usage-based overage, credits, seats, packs, trials, add-ons and spend limits.

The docs