feat(paykit): 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
• Add a changeset for paykitjs

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 CodeRabbit

• New Features

  • Subscription flows now support item quantity across checkout, subscription creation, updates, and scheduled changes.
  • Quantity is accepted in subscribe requests, validated as a positive integer, and carried through to provider and local records.

• Bug Fixes

  • Quantity is now normalized and preserved consistently, including during billing sync and scheduled activations.

• Tests

  • Added unit and end-to-end Stripe provider coverage to confirm quantity is forwarded and reflected correctly (including schedule phase changes).

[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:35am

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 524b7302-27c4-4747-9276-87d05dfca4bd

📥 Commits

Reviewing files that changed from the base of the PR and between 08d878b and f741c69.

📒 Files selected for processing (10)

• .changeset/subscription-quantity.md
• 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

 _____________________________________________________________
< 🥕 I brought carrots. You brought corner cases. Let's party. >
 -------------------------------------------------------------
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

📝 Walkthrough

Walkthrough

Subscription quantity now flows from the subscribe request schema into provider contracts, Stripe checkout and subscription calls, and subscription sync/update paths. The API, webhook, and billing-state handlers now carry quantity into stored subscription records.

Changes

Subscription quantity propagation

Layer / File(s)	Summary
Quantity contracts packages/paykit/src/providers/provider.ts, packages/paykit/src/subscription/subscription.types.ts, packages/paykit/src/types/events.ts, packages/paykit/src/subscription/__tests__/subscription.types.test.ts, .changeset/subscription-quantity.md	ProviderSubscription, NormalizedSubscription, and SubscribeBody now carry quantity, and the subscribe body schema tests cover optional and positive-integer 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, and schedule-change payloads now use quantity, and the Stripe tests assert the passed quantities and normalized results.
Subscribe routing and scheduled activation packages/paykit/src/subscription/subscription.api.ts, packages/paykit/src/subscription/subscription.service.ts	The subscribe handler passes quantity into subscribeToPlan, the service loads quantity into subscribe context, compares quantities for same-plan changes, and threads quantity through scheduled activation, webhook activation, provider calls, and provider-backed target creation.
Quantity sync and persistence packages/paykit/src/subscription/subscription.service.ts, packages/paykit/src/subscription/__tests__/subscription.service.test.ts	insertSubscriptionRecord, activateScheduledSubscription, syncSubscriptionFromProvider, and syncSubscriptionBillingState now persist quantity conditionally, and service tests assert quantity is forwarded into the update builders.

Sequence Diagram(s)

sequenceDiagram
  participant subscription.api.ts as subscription.api.ts
  participant subscribeToPlan as subscribeToPlan
  participant stripe-provider.ts as stripe-provider.ts
  participant PayKitDatabase as PayKitDatabase

  subscription.api.ts as subscription.api.ts->>subscribeToPlan: pass ctx.input.quantity
  subscribeToPlan->>stripe-provider.ts as stripe-provider.ts: create/update subscription with quantity
  stripe-provider.ts as stripe-provider.ts-->>subscribeToPlan: normalized subscription quantity
  subscribeToPlan->>PayKitDatabase: sync subscription record and billing state

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

A bunny hopped through checkout light,
With quantity tucked in snug and right.
Stripe rang bells and records grew,
The database hummed, “quantity too!”
🐇✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 32.14% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding subscription quantity support in paykit.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ 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.}

[vercel]

@Pascoooo is attempting to deploy a commit to the maxktz Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/paykit/src/stripe/stripe-provider.ts`:
- Line 192: The Stripe subscription mapping in stripe-provider.ts is defaulting
quantity to 1 when firstItem is missing, which can overwrite the stored local
quantity during syncSubscriptionFromProvider(...). Update the
subscription-to-local mapping logic so quantity is only set when
subscription.items.data[0] exists and has an explicit quantity, and otherwise
leave it undefined; use the existing firstItem handling in the provider sync
path to locate the change.

In `@packages/paykit/src/subscription/subscription.service.ts`:
- Around line 49-52: The same-plan quantity branch in subscription.service’s
subscription flow currently jumps straight to handleQuantityChange, which can
skip clearing or resuming pending same-plan provider changes first. Update the
same-plan path so quantity-only changes either go through
handleSamePlanSubscribe or explicitly resume/cancel any pending schedule before
calling handleQuantityChange, and make sure the same fix is applied anywhere the
same logic is duplicated in the broader subscription update flow.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 263f070f-8549-4752-9e43-b9e2837ed844

📥 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

[cubic-dev-ai]

1 issue found and verified against the latest diff

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>