Repository navigation
Correct billing and org references against clerk_go - #119
Merged
Merged
Conversation
subscriptionItem webhooks carry subscription_id, so the billing handler links items to their subscription and falls back to payer + plan slug. The item payload block now lists the fields Clerk sends. The org System Permissions catalog adds the API key, enterprise connection, and SSO bypass permissions, with the feature each needs. The clerk-webhooks event list drops subscriptionItem.created, which Clerk never sends, and adds subscriptionItem.expired. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Clerk grants the feature-gated permissions to org:admin by default, and other roles can be given them. The SSO bypass permission survives a plan downgrade. Also drop a repeated type-widening instruction. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A subscription can hold several items on the same plan over time, so subscription id plus plan slug can match more than one row. The handler now upserts by evt.data.id and stores subscription_id as the link. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
SarahSoutoul
approved these changes
Nov 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this solve? What changed?
While reviewing #118, I checked the billing and org references against clerk_go and found three claims that were wrong before #118. They're outside its diff, so they're fixed here. Nothing overlaps #118's changes, and the two merge cleanly in either order.
clerk-billing/references/billing-webhooks.md: The reference said subscriptionItem events can't be tied back to their subscription. They can.CommerceSubscriptionItemEventsetssubscription_idon every standalone event, and webhooks are always standalone. The webhook OpenAPI schema (BillingSubscriptionItemEventPayload.yml) documents it too. The handler now upserts item rows by their item id and storessubscription_idas the link to the subscription. The Payload Shape bullet and Key Rules line say the same.canceled_atandpast_due_at, which the webhook payload doesn't include. It now usesupdated_at. The item payload block lists the fields Clerk actually sends, and a note covers where@clerk/backend'sBillingSubscriptionItemWebhookEventJSONdiffers from the payload: it's missingsubscription_idandupdated_at, and it declarescanceled_at,past_due_at, andamount.clerk-orgs/references/roles-permissions.md: The catalog said its 8 slugs were the only System Permissions. clerk_go'spkg/constants/roles_and_permissions.goalso definesorg:sys_api_keys:read,org:sys_api_keys:manage,org:sys_entconns:manage, andorg:sys_entconns_sso_bypass:manage. Clerk creates each when its feature is on (API keys, self-serve SSO, SSO bypass) and grants them toorg:adminby default. The SSO bypass permission stays after a plan downgrade.org:sys_enterprise_connections:manageis the legacy key thatpkg/backfill/rename_entconns_permission_keyrenames, so the doc calls it out as legacy.clerk-webhooks/SKILL.md: The Subscription Item list hadsubscriptionItem.created, which isn't in clerk_go's event registry, and was missingsubscriptionItem.expired. It now matches the 10 events inpkg/events/event_types.go.@clerk/backend's types have the same drift:BillingSubscriptionItemWebhookEventlistssubscriptionItem.created, omitssubscriptionItem.expired, and the item JSON type lackssubscription_id. That's a clerk/javascript fix, not part of this PR.Deadline
Other resources
🤖 Generated with Claude Code