fix(backend): Add payer field to BillingSubscriptionItemWebhookEventJSON

[Wendrowiec13]

Description

This PR adds missing optional payer field to BillingSubscriptionItemWebhookEventJSON. It's missing in the type definition even though it's present in the event catalog and in both production and development webhook data.

Fixes (#7023)

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• New Features
  • Billing webhook events for subscription items now include optional payer information. Event payloads have been extended to provide additional payer details when available. This enhancement enables richer billing context and more sophisticated handling of subscription events throughout your integration workflows.

[changeset-bot]

🦋 Changeset detected

Latest commit: e65b95c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 11 packages

Name	Type
@clerk/backend	Minor
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/remix	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

@Wendrowiec13 is attempting to deploy a commit to the Clerk Production Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Walkthrough

A new optional payer field of type BillingPayerJSON is added to the BillingSubscriptionItemWebhookEventJSON interface in the Clerk backend package, extending webhook event payloads to optionally include payer information.

Changes

Cohort / File(s)	Change Summary
Changeset Documentation \.changeset/loud-rules-rescue\.md	New changeset file documenting a minor version bump for @clerk/backend package
Schema Extension packages/backend/src/api/resources/JSON\.ts	Added optional payer?: BillingPayerJSON field to BillingSubscriptionItemWebhookEventJSON interface

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related issues

• [@clerk/backend] BillingSubscriptionItemWebhookEventJSON missing the payer field #7023 — This PR directly addresses the missing payer field in billing webhook events as reported in the issue.

Poem

🐰 A payer field hops in today,
Webhooks now have more to say,
Billing events dance and play,
With richer data on display! 💳✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The pull request title "fix(backend): Add payer field to BillingSubscriptionItemWebhookEventJSON" directly and accurately describes the main change in the changeset. The title clearly identifies what was added (payer field), to what entity (BillingSubscriptionItemWebhookEventJSON), and in which package area (backend). It is concise, specific, and avoids vague language or noise, making it easy for a teammate scanning the git history to understand the primary purpose of this fix.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

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

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

packages/backend/src/api/resources/JSON.ts (1)

939-939: Consider adding JSDoc documentation for the new field.

While the interface itself has JSDoc comments, the new payer field lacks documentation. Adding a brief comment would improve API documentation clarity for developers consuming this webhook event type.

Apply this diff to add documentation:

+  /**
+   * Optional payer information associated with the subscription item.
+   */
   payer?: BillingPayerJSON;

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 79d9c5e and fc48271.

📒 Files selected for processing (2)

• .changeset/loud-rules-rescue.md (1 hunks)
• packages/backend/src/api/resources/JSON.ts (1 hunks)

🧰 Additional context used

📓 Path-based instructions (7)

.changeset/**

📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)

Automated releases must use Changesets.

Files:

• .changeset/loud-rules-rescue.md

**/*.{js,jsx,ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

**/*.{js,jsx,ts,tsx}: All code must pass ESLint checks with the project's configuration
Follow established naming conventions (PascalCase for components, camelCase for variables)
Maintain comprehensive JSDoc comments for public APIs
Use dynamic imports for optional features
All public APIs must be documented with JSDoc
Provide meaningful error messages to developers
Include error recovery suggestions where applicable
Log errors appropriately for debugging
Lazy load components and features when possible
Implement proper caching strategies
Use efficient data structures and algorithms
Profile and optimize critical paths
Validate all inputs and sanitize outputs
Implement proper logging with different levels

Files:

• packages/backend/src/api/resources/JSON.ts

**/*.{js,jsx,ts,tsx,json,css,scss,md,yaml,yml}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

Use Prettier for consistent code formatting

Files:

• packages/backend/src/api/resources/JSON.ts

packages/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

TypeScript is required for all packages

Files:

• packages/backend/src/api/resources/JSON.ts

packages/**/*.{ts,tsx,d.ts}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

Packages should export TypeScript types alongside runtime code

Files:

• packages/backend/src/api/resources/JSON.ts

**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

Use proper TypeScript error types

**/*.{ts,tsx}: Always define explicit return types for functions, especially public APIs
Use proper type annotations for variables and parameters where inference isn't clear
Avoid any type - prefer unknown when type is uncertain, then narrow with type guards
Use interface for object shapes that might be extended
Use type for unions, primitives, and computed types
Prefer readonly properties for immutable data structures
Use private for internal implementation details
Use protected for inheritance hierarchies
Use public explicitly for clarity in public APIs
Prefer readonly for properties that shouldn't change after construction
Prefer composition and interfaces over deep inheritance chains
Use mixins for shared behavior across unrelated classes
Implement dependency injection for loose coupling
Let TypeScript infer when types are obvious
Use const assertions for literal types: as const
Use satisfies operator for type checking without widening
Use mapped types for transforming object types
Use conditional types for type-level logic
Leverage template literal types for string manipulation
Use ES6 imports/exports consistently
Use default exports sparingly, prefer named exports
Use type-only imports: import type { ... } from ...
No any types without justification
Proper error handling with typed errors
Consistent use of readonly for immutable data
Proper generic constraints
No unused type parameters
Proper use of utility types instead of manual type construction
Type-only imports where possible
Proper tree-shaking friendly exports
No circular dependencies
Efficient type computations (avoid deep recursion)

Files:

• packages/backend/src/api/resources/JSON.ts

**/*.{js,ts,tsx,jsx}

📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)

Support multiple Clerk environment variables (CLERK_, NEXT_PUBLIC_CLERK_, etc.) for configuration.

Files:

• packages/backend/src/api/resources/JSON.ts

🧬 Code graph analysis (1)

packages/backend/src/api/resources/JSON.ts (1)

packages/types/src/json.ts (1)

• BillingPayerJSON (824-840)

🔇 Additional comments (2)

.changeset/loud-rules-rescue.md (1)

1-5: LGTM! Changeset is correctly formatted.

The changeset appropriately marks this as a minor version bump, which is correct for adding a new optional field to an existing interface. The description clearly communicates the change.

packages/backend/src/api/resources/JSON.ts (1)

939-939: Verify the optional nature of the payer field against actual webhook payloads.

The change correctly adds the payer field with the proper type reference. However, an inconsistency exists with other webhook event interfaces in this file:

• BillingSubscriptionItemWebhookEventJSON (Line 939): payer?: BillingPayerJSON (optional)
• BillingPaymentAttemptWebhookEventJSON (Line 963): payer: BillingPayerJSON (required)
• BillingSubscriptionWebhookEventJSON (Line 992): payer: BillingPayerJSON (required)

Confirm whether the payer field should be optional for subscription item webhooks based on actual webhook payload specifications. If it's always present, make it required for consistency with other webhook event types.

[wobsoriano]

Thanks ❤️ Great catch!