feat(paykit): pass customer details to subscription checkout

[almeidazs]

Summary

This updates subscription checkout so providers can receive customer identity data when a checkout session is created.

Concretely:

• createSubscriptionCheckout() now accepts an optional customer object with email and name
• the core subscribe flow loads the PayKit customer once and forwards those fields into checkout providers
• Stripe forwards customer_email to Checkout
• Polar forwards both customerEmail and customerName

This closes a gap for providers that need customer details to initialize checkout cleanly.

Closes #131

Example

New provider contract:

createSubscriptionCheckout(data: {
  customer?: {
    email?: string;
    name?: string;
  };
  providerCustomerId: string;
  providerProduct: Record<string, string>;
  successUrl: string;
  cancelUrl?: string;
  metadata?: Record<string, string>;
}): Promise<{ paymentUrl: string; providerCheckoutSessionId: string }>;

Example payload passed from the subscribe flow:

await ctx.provider.createSubscriptionCheckout({
  customer: {
    email: "billing@example.com",
    name: "Billing User",
  },
  providerCustomerId: "cus_123",
  providerProduct: { priceId: "price_123" },
  successUrl: "https://app.example.com/billing/success",
  cancelUrl: "https://app.example.com/billing/cancel",
  metadata: {
    paykit_customer_id: "customer_123",
    paykit_intent: "subscribe",
    paykit_plan_id: "pro",
    paykit_product_internal_id: "product_internal_123",
  },
});

Breaking change

Yes, for custom provider adapters.

PaymentProvider.createSubscriptionCheckout() now accepts one additional optional field:

• customer?: { email?: string; name?: string }

First-party providers in this repo have been updated. External adapters implementing the provider interface will need to update their method signature, even if they ignore the new field.

Tests

• bun run typecheck --filter=paykitjs --filter=@paykitjs/stripe --filter=@paykitjs/polar
• node ./node_modules/vitest/vitest.mjs run --config vitest.unit.config.ts packages/paykit/src/subscription/__tests__/subscription.service.test.ts packages/stripe/src/__tests__/stripe.test.ts

Summary by CodeRabbit

• New Features

  • Subscription checkout now captures and utilizes customer information (email and name) during payment processing, enabling better customer identification with payment providers.

• Tests

  • Added test coverage for customer data handling in subscription workflows.

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
paykit	Skipped		May 18, 2026 0:39am

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 1091f580-666b-45f1-b663-b4d5c8034443

📥 Commits

Reviewing files that changed from the base of the PR and between 55a0bda and 1f71d20.

📒 Files selected for processing (6)

• packages/paykit/src/providers/provider.ts
• packages/paykit/src/subscription/__tests__/subscription.service.test.ts
• packages/paykit/src/subscription/subscription.service.ts
• packages/polar/src/polar-provider.ts
• packages/stripe/src/__tests__/stripe.test.ts
• packages/stripe/src/stripe-provider.ts

---

📝 Walkthrough

Walkthrough

Customer email and name are now passed through the subscription checkout flow. The provider interface accepts optional customer details, the subscription service loads and forwards them, and Stripe and Polar implementations transmit customer email to their checkout endpoints.

Changes

Customer Details in Subscription Checkout

Layer / File(s)	Summary
Provider contract extension packages/paykit/src/providers/provider.ts	ProviderCheckoutCustomer interface introduced with optional email and name fields; createSubscriptionCheckout updated to accept customer?: ProviderCheckoutCustomer.
Subscription service customer flow packages/paykit/src/subscription/subscription.service.ts	loadSubscribeContext fetches customer record, passes it to upsertProviderCustomer, and extends returned context with customer object containing email and name; subscribeToPlan forwards this customer to createSubscriptionCheckout.
Stripe and Polar provider implementations packages/stripe/src/stripe-provider.ts, packages/polar/src/polar-provider.ts	Stripe sets customer_email in Checkout Session parameters; Polar includes customerEmail and customerName in checkout creation request.
Subscription and provider test coverage packages/paykit/src/subscription/__tests__/subscription.service.test.ts, packages/stripe/src/__tests__/stripe.test.ts	Test suite mocks dependencies, validates customer record loading and context propagation in subscription service, and verifies customer email is forwarded to provider checkout methods.

---

🎯 2 (Simple) | ⏱️ ~12 minutes

---

🐰 A customer hops from sign-up to checkout,
With email and name now passed all throughout,
Stripe and Polar smile with glee,
Compliance requirements met happily!
✨ The checkout flow bounces secure.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.67% 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 and specifically describes the main change: adding customer details (email, name) to the subscription checkout flow across the provider interface and implementations.
Linked Issues check	✅ Passed	The PR successfully implements the requested feature from #131: optional customer object with email and name fields added to createSubscriptionCheckout signature, with updates to Stripe and Polar providers and comprehensive tests.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the feature: provider interface updates, core subscription service modifications, provider implementations, and corresponding tests. No unrelated alterations detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

---

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 and usage tips.}