Add subscription quantity support

[Pascoooo]

Summary

• Add optional subscription quantity support to subscribe input and provider calls
• Pass quantity through Stripe checkout, create, update, and scheduled changes
• Sync subscription item quantity from provider/webhooks into the existing local subscription quantity column

Out of scope

• Checkout command idempotency keys
• Resuming open Checkout Sessions
• Automatic tax, Tax ID, or billing address collection
• App-specific organization or entitlement logic

Test Plan

• pnpm test:unit
• pnpm --filter paykitjs typecheck
• pnpm lint
• pnpm --filter paykitjs build

---

Summary by cubic

Add end-to-end subscription quantity support. Quantity flows from the subscribe API through Stripe Checkout/create/update/scheduled changes, and is stored and synced in the local subscription.

• New Features

  • Subscribe API accepts optional quantity (positive integer), default 1.
  • Stripe provider sends quantity to Checkout line items, direct create, update, and schedules; normalizes quantity on reads.
  • Same-plan quantity changes update the active subscription in place.
  • Webhooks, scheduled activations, and local writes persist and emit quantity.

• Migration

  • Provider interface now requires a quantity param for createSubscriptionCheckout, createSubscription, updateSubscription, and scheduleSubscriptionChange. Update custom providers/callers accordingly.
  • If using the public subscribe endpoint, no changes are required (quantity defaults to 1).

^{Written for commit e7a75e8. Summary will update on new commits.}

Summary by CodeRabbit

• New Features
  • Subscription flows now support selecting a quantity for plans.
  • Quantity is now carried through checkout, subscription updates, scheduled changes, and webhook-based syncs.
• Bug Fixes
  • Existing subscriptions now keep the correct quantity when changing between the same plan.
  • Subscription details and billing state now stay aligned with the selected quantity.
• Tests
  • Added coverage for quantity validation and for provider/database sync behavior.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
paykit	Skipped		Jun 27, 2026 10:34am

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 621954e4-a40a-4036-9e53-0580d5df1d66

📥 Commits

Reviewing files that changed from the base of the PR and between 0689e65 and e7a75e8.

📒 Files selected for processing (9)

• packages/paykit/src/providers/provider.ts
• packages/paykit/src/stripe/__tests__/stripe-provider.test.ts
• packages/paykit/src/stripe/stripe-provider.ts
• packages/paykit/src/subscription/__tests__/subscription.service.test.ts
• packages/paykit/src/subscription/__tests__/subscription.types.test.ts
• packages/paykit/src/subscription/subscription.api.ts
• packages/paykit/src/subscription/subscription.service.ts
• packages/paykit/src/subscription/subscription.types.ts
• packages/paykit/src/types/events.ts

---

📝 Walkthrough

Walkthrough

Subscription contracts, Stripe provider calls, and subscription-service flows now carry quantity through checkout, direct subscription changes, scheduled activation, webhook reconciliation, and stored subscription updates. Schema and service tests cover the new quantity handling.

Changes

Subscription quantity propagation

Layer / File(s)	Summary
Quantity contracts and validation packages/paykit/src/providers/provider.ts, packages/paykit/src/subscription/subscription.types.ts, packages/paykit/src/types/events.ts, packages/paykit/src/subscription/subscription.api.ts, packages/paykit/src/subscription/__tests__/subscription.types.test.ts	Provider subscription shapes, subscribe input, and normalized subscription output add quantity, the subscribe handler forwards it, and schema tests cover accepted and rejected values.
Stripe quantity propagation packages/paykit/src/stripe/stripe-provider.ts, packages/paykit/src/stripe/__tests__/stripe-provider.test.ts	Stripe checkout, subscription create/update, scheduling, and normalization now use quantity, with tests covering the propagated item quantities.
Same-plan quantity changes packages/paykit/src/subscription/subscription.service.ts	subscribeToPlan derives quantity in context, detects same-plan quantity changes, and routes them through handleQuantityChange or the existing same-plan sync path.
Provider-backed persistence packages/paykit/src/subscription/subscription.service.ts	Provider-backed creation, replacement, and checkout flows now pass quantity into provider calls and store it in inserted subscription rows.
Scheduled activation and reconciliation packages/paykit/src/subscription/subscription.service.ts, packages/paykit/src/subscription/__tests__/subscription.service.test.ts	Scheduled activation, webhook upserts, and billing-state sync now carry quantity into stored subscriptions, and tests assert the sync helpers write it.

Sequence Diagram(s)

sequenceDiagram
  participant subscribeToPlan
  participant handleQuantityChange
  participant PaymentProvider
  participant PayKitDatabase
  subscribeToPlan->>handleQuantityChange: same plan, different quantity
  handleQuantityChange->>PaymentProvider: updateSubscription(quantity)
  PaymentProvider-->>handleQuantityChange: updated subscription data
  handleQuantityChange->>PayKitDatabase: sync quantity and billing state
  handleQuantityChange-->>subscribeToPlan: subscribe result

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐇 I hopped through plans with quantity in tow,
Stripe and the database both learned to grow.
Same-plan changes danced with a tiny boop,
Webhooks and schedules stayed in the loop.
✨ A carrot to the code, and off I go!

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Pascoooo]

Superseded by #201 with a cleaner branch name.