Feat/multi item subscriptions

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+
+      - run: npm ci
+      - run: npm run build --if-present
+      - run: npm publish

apps/web/content/docs/database.mdx

@@ -47,6 +47,8 @@ PayKit creates tables prefixed with `paykit_`. The key ones are:
   PayKit owns these tables. Don't write to them directly. Use the PayKit API.
 </Callout>
 
+`paykit_subscription` rows can share one provider subscription: [combined checkout and add-ons](/docs/subscriptions#combined-checkout-add-ons) put a base plan and its add-ons on a single provider subscription, tracked as one row per plan. `paykit_product` records whether a plan is billed as a flat recurring price or [metered via Stripe usage-based billing](/docs/metered-usage#stripe-usage-based-billing).
+
 ## Migrations
 
 `paykitjs push` applies any pending migrations. Run it on initial setup and whenever you update your plan configuration.

apps/web/content/docs/entitlements.mdx

@@ -99,3 +99,7 @@ export async function POST(request: Request) {
 ```
 
 This pattern ensures you don't charge usage for failed requests, and you don't serve responses to customers who've hit their limit.
+
+<Callout type="info">
+  `report()` decrements a local quota — it never involves your payment provider. If you need Stripe to actually calculate a bill from usage, see [Stripe usage-based billing](/docs/metered-usage#stripe-usage-based-billing).
+</Callout>

apps/web/content/docs/metered-usage.mdx

@@ -146,3 +146,68 @@ export async function POST(request: Request) {
 <Callout type="info">
   If you just need on/off access without tracking usage, use `boolean` type instead. `check` still returns `allowed`, but there's no balance to track or reset.
 </Callout>
+
+## Stripe usage-based billing
+
+Everything above is a **local quota**: PayKit tracks a balance in your database and gates access with `check()`/`report()`. Stripe is never involved, and there's nothing to bill — the plan's price, if any, is a flat recurring fee.
+
+Stripe usage-based billing is a different thing: Stripe itself calculates a charge from usage you report, with no cap. Define it with a `meteredBy` price instead of a flat `amount`:
+
+```ts title="products.ts"
+const apiCalls = feature({ id: "api_calls", type: "metered" });
+
+export const usagePlan = plan({
+  id: "usage",
+  name: "API Usage",
+  group: "usage",
+  price: { meteredBy: apiCalls, unitAmount: 0.01, interval: "month" },
+});
+```
+
+When you sync this plan, PayKit creates a Stripe [Billing Meter](https://docs.stripe.com/billing/subscriptions/usage-based) and a metered Price for it automatically. Report usage with `reportUsage()` instead of `report()`:
+
+```ts
+await paykit.reportUsage({
+  customerId: userId,
+  featureId: "api_calls",
+  quantity: 1,
+});
+```
+
+Stripe aggregates reported usage and bills it on the customer's next invoice at `unitAmount` per unit. There's no local balance to check beforehand — `reportUsage()` fails only if the customer has no active subscription for a plan metered by that feature.
+
+<Callout type="warn">
+  Unlike `report()`, `reportUsage()` doesn't swallow failures — its entire purpose is the billing side effect, so a failed call throws. If you need at-least-once delivery, pass a stable `eventId`; PayKit forwards it as Stripe's `identifier`, which Stripe deduplicates on.
+</Callout>
+
+### Combining a quota with billed overage
+
+A single price can't be both a flat fee and metered overage in Stripe. To offer "some usage included, then billed per unit beyond that," compose two plans and combine them into one checkout with `addOnPlanIds`:
+
+```ts title="products.ts"
+export const pro = plan({
+  id: "pro",
+  name: "Pro",
+  group: "base",
+  price: { amount: 19, interval: "month" },
+  includes: [messages({ limit: 2_000, reset: "month" })], // included quota
+});
+
+export const overage = plan({
+  id: "overage",
+  name: "Extra Usage",
+  group: "usage",
+  price: { meteredBy: apiCalls, unitAmount: 0.01, interval: "month" }, // billed beyond it
+});
+```
+
+```ts
+await paykit.subscribe({
+  customerId: "user_123",
+  planId: "pro",
+  addOnPlanIds: ["overage"],
+  successUrl: "https://myapp.com/billing/success",
+});
+```
+
+Gate the included quota with `check()`/`report()` as usual. Once a customer exceeds it, call `reportUsage()` for the extra units instead — Stripe bills those separately at `unitAmount`.

apps/web/content/docs/plans-and-features.mdx

@@ -95,6 +95,38 @@ Groups let you model common billing patterns:
 
 Every plan that has `default: true` must belong to a group. Without a group, PayKit doesn't know which set of plans a customer is being placed into.
 
+### Combining groups in one checkout
+
+Groups are mutually exclusive within themselves, but a customer can hold one active plan per group at the same time — that's how a `base` plan and an `addons` plan coexist. Pass `addOnPlanIds` to `subscribe()` to combine a plan from each group into a single checkout, instead of running a separate checkout per group:
+
+```ts
+export const pro = plan({
+  id: "pro",
+  name: "Pro",
+  group: "base",
+  price: { amount: 19, interval: "month" },
+  includes: [messages({ limit: 2_000, reset: "month" })],
+});
+
+export const extraMessages = plan({
+  id: "extra_messages",
+  name: "Extra Messages",
+  group: "addons",
+  price: { amount: 5, interval: "month" },
+  includes: [messages({ limit: 500, reset: "month" })],
+});
+
+// One checkout, one payment, both plans active afterward.
+await paykit.subscribe({
+  customerId: "user_123",
+  planId: "pro",
+  addOnPlanIds: ["extra_messages"],
+  successUrl: "https://myapp.com/billing/success",
+});
+```
+
+The customer's `messages` balance pools across both plans — 2,000 from `pro` plus 500 from `extra_messages`, 2,500 total — since [entitlements](/docs/entitlements) aggregate every active subscription for a feature, not just one. See [Combined checkout](/docs/subscriptions#combined-checkout-add-ons) for the full behavior, constraints, and how to add or remove a single add-on later.
+
 ## Default plans
 
 The default plan is the fallback for a group. It's typically your free tier.
@@ -125,6 +157,25 @@ price: { amount: 19, interval: "month" }
 - `interval` can be `month` or `year`
 - `amount` is in dollars, max $999,999.99
 
+### Metered Stripe pricing
+
+For pay-as-you-go pricing where Stripe calculates the bill from reported usage, use `meteredBy` and `unitAmount` instead of `amount`:
+
+```ts
+const apiCalls = feature({ id: "api_calls", type: "metered" });
+
+export const usagePlan = plan({
+  id: "usage",
+  name: "API Usage",
+  group: "usage",
+  price: { meteredBy: apiCalls, unitAmount: 0.01, interval: "month" },
+});
+```
+
+`unitAmount` is the price per unit, charged for whatever quantity you report via `paykit.reportUsage()`. See [Stripe usage-based billing](/docs/metered-usage#stripe-usage-based-billing) for how reporting works and how this differs from the local metered quotas above.
+
+This is a separate concept from a `metered`-type feature's `limit`/`reset` — that's a local quota PayKit tracks and gates on for you, with no Stripe involvement. `meteredBy` prices are for genuine usage-based billing, where Stripe itself computes the charge. You can combine both: a licensed base plan with a local quota, plus a `meteredBy` add-on for usage beyond it, joined into one checkout via `addOnPlanIds`.
+
 ## Passing products to PayKit
 
 Pass your products array to `createPayKit`. You can import them directly or re-export them from a module object.

apps/web/content/docs/subscriptions.mdx

@@ -95,6 +95,71 @@ await paykit.subscribe({ customerId: "user_123", planId: "pro" });
 // Scheduled target changes from "free" to "pro".
 ```
 
+## Combined checkout (add-ons)
+
+Pass `addOnPlanIds` alongside `planId` to combine a base plan with one or more add-ons into a single checkout. The customer sees every line item on the same provider-hosted page and confirms one payment for all of them.
+
+<Tabs items={["Server", "Client"]}>
+  <Tab value="Server">
+    ```ts
+    const result = await paykit.subscribe({
+      customerId: "user_123",
+      planId: "pro",
+      addOnPlanIds: ["extra_messages"],
+      successUrl: "https://myapp.com/billing/success",
+      cancelUrl: "https://myapp.com/billing",
+    });
+
+    if (result.paymentUrl) {
+      // Redirect user to provider checkout — one page, both line items
+    }
+    ```
+  </Tab>
+  <Tab value="Client">
+    ```tsx
+    const { paymentUrl } = await paykitClient.subscribe({
+      planId: "pro",
+      addOnPlanIds: ["extra_messages"],
+      successUrl: "/billing/success",
+      cancelUrl: "/billing",
+    });
+
+    if (paymentUrl) {
+      window.location.href = paymentUrl;
+    }
+    ```
+  </Tab>
+</Tabs>
+
+Behind the scenes, this creates one provider subscription with one line item per plan. Every plan in the list — the base plan and every add-on — is tracked as its own subscription record, so [entitlements](/docs/entitlements) and renewals stay correct for each of them independently.
+
+A few constraints apply to combined checkout:
+
+- Every plan must be paid. Free plans can't be combined this way.
+- Each plan must belong to a different [group](/docs/plans-and-features#plan-groups). You can't combine two plans from the same group in one call.
+- None of the plans can already have an active subscription for that customer. To add or remove a single plan on an already-active subscription, use `addAddOn`/`removeAddOn` below instead.
+
+<Callout type="info">
+  Combined checkout is for new subscriptions. Upgrading or downgrading the base plan afterward works exactly like a normal `subscribe()` call — see [Upgrades](#upgrades) and [Downgrades](#downgrades) above — and leaves any add-ons on the subscription untouched.
+</Callout>
+
+## Managing add-ons
+
+Once a customer has an active subscription, `addAddOn` and `removeAddOn` attach or detach a single add-on plan without touching the rest of the subscription.
+
+```ts
+// Attach extra_messages to the customer's existing subscription.
+// Charges their saved card immediately, the same way an upgrade does.
+await paykit.addAddOn({ customerId: "user_123", planId: "extra_messages" });
+
+// Detach it again. Ends immediately — no need to wait for a webhook.
+await paykit.removeAddOn({ customerId: "user_123", planId: "extra_messages" });
+```
+
+`addAddOn` requires the customer to already have an active provider-backed subscription to attach to. If they have more than one — for example, they subscribed to two groups separately instead of combining them — pass `targetSubscriptionId` to say which one to attach to.
+
+`removeAddOn` fails with a clear error if the plan is the subscription's only remaining item — Stripe doesn't allow removing the last item from a subscription. Cancel the whole subscription with `subscribe()` to the group's default plan instead.
+
 ## Behavior summary
 
 | Scenario | Behavior |
@@ -114,6 +179,7 @@ await paykit.subscribe({ customerId: "user_123", planId: "pro" });
 |---|---|---|
 | `planId` | Yes | The target plan ID. Must be a valid plan from your config. |
 | `customerId` | Server only | The customer to subscribe. Not needed on the client (resolved from `identify`). |
+| `addOnPlanIds` | No | Additional plan IDs to combine with `planId` into one checkout. See [Combined checkout](#combined-checkout-add-ons). |
 | `successUrl` | Recommended | Where to redirect after successful checkout. |
 | `cancelUrl` | Recommended | Where to redirect if the customer cancels checkout. |
 | `forceCheckout` | No | Forces a checkout flow even if the customer already has a payment method. |

apps/web/content/docs/webhook-events.mdx

@@ -43,6 +43,10 @@ Payload shape:
 | `customerId` | `string` | Your internal customer identifier |
 | `subscriptions` | `Subscription[]` | The customer's updated subscriptions |
 
+<Callout type="info">
+  If the customer used [combined checkout or add-ons](/docs/subscriptions#combined-checkout-add-ons), `subscriptions` contains one entry per plan — the base plan and every add-on — even though they're billed together on a single provider subscription.
+</Callout>
+
 ## Wildcard handler
 
 `"*"` catches all PayKit events. Useful for logging or debugging.

e2e/core/addon/add-addon.test.ts

@@ -0,0 +1,86 @@
+import { eq } from "drizzle-orm";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { subscription } from "../../../packages/paykit/src/database/schema";
+import {
+  createTestCustomerWithPM,
+  createTestPayKit,
+  dumpStateOnFailure,
+  expectExactMeteredBalance,
+  expectProduct,
+  subscribeCustomer,
+  type TestPayKit,
+} from "../../test-utils";
+
+describe("add-addon: attaching an add-on to an already-active subscription", () => {
+  let t: TestPayKit;
+  let customerId: string;
+
+  beforeAll(async () => {
+    t = await createTestPayKit();
+    const customer = await createTestCustomerWithPM({
+      t,
+      customer: {
+        id: "test_add_addon",
+        email: "add-addon@test.com",
+        name: "Add Addon Test",
+      },
+    });
+    customerId = customer.customerId;
+
+    await subscribeCustomer({ t, customerId, planId: "pro" });
+  });
+
+  afterAll(async () => {
+    await t?.cleanup();
+  });
+
+  it("adding extra_messages attaches a second item to the same Stripe subscription", async () => {
+    try {
+      const result = await t.paykit.addAddOn({ customerId, planId: "extra_messages" });
+      expect(result.paymentUrl).toBeNull();
+
+      await expectProduct({
+        database: t.database,
+        customerId,
+        planId: "pro",
+        expected: { status: "active" },
+      });
+      await expectProduct({
+        database: t.database,
+        customerId,
+        planId: "extra_messages",
+        expected: { status: "active" },
+      });
+
+      const rows = await t.database
+        .select({
+          stripeSubscriptionId: subscription.stripeSubscriptionId,
+          stripeSubscriptionItemId: subscription.stripeSubscriptionItemId,
+        })
+        .from(subscription)
+        .where(eq(subscription.customerId, customerId));
+      const activeRows = rows.filter((row) => row.stripeSubscriptionId != null);
+
+      const distinctSubscriptionIds = new Set(activeRows.map((row) => row.stripeSubscriptionId));
+      expect(distinctSubscriptionIds.size).toBe(1);
+
+      const itemIds = activeRows
+        .map((row) => row.stripeSubscriptionItemId)
+        .filter((id): id is string => id != null);
+      expect(new Set(itemIds).size).toBe(itemIds.length);
+      expect(itemIds.length).toBeGreaterThanOrEqual(2);
+
+      await expectExactMeteredBalance({
+        paykit: t.paykit,
+        customerId,
+        featureId: "messages",
+        limit: 700,
+        remaining: 700,
+      });
+    } catch (error) {
+      await dumpStateOnFailure(t.database, t.dbPath);
+      throw error;
+    }
+  });
+});