Integrating roles with billing plans?
I'm building a resource portal, using Express.js and Kinde permissions to restrict access to content. Today, I am looking at building in billing functionality, but am unsure how I can tie various plans to user roles?
E.g. If someone subscribes to the "Subscriber" plan, how can Kinde add the "subscriber" role to the user. And if they change plan later ("Client" ), how can Kinde then change their role ("client")?
Is this something Kinde manages directly, or do I need to code for seperately, and use Kinde (Workflows?)?
6 Replies
Hi, I'm new to Kinde but I'm pretty sure if you use the 'Account API' you can check the billing entitlements of a user so you can figure out what plan they have as you can see here:
https://docs.kinde.com/kinde-apis/frontend/#tag/billing/get/account_api/v1/entitlements
Kinde docs
Kinde Account API
For managing the currently signed-in user, includes e.g their profile, roles, permissions, billing info and revoking tokens
Kinde separates plans (subscriptions) and roles (permissions). Plans control billing and what a user pays for; roles control what a user can access in your app.
Kinde does not automatically assign or update roles when a user subscribes or changes plan.
How plan changes work in Kinde:
* Self-serve portal – Users can change their own plan from the pricing table.
* Kinde UI – You can manually change a user’s or organisation’s plan from the Kinde dashboard.
* API – You can programmatically overwrite a subscription by creating a new one.
When a plan change happens, Kinde ensures:
* The customer’s subscription record is updated.
* Stripe (or your chosen payment processor) is synced automatically, with credits/bills applied.
To sync roles with plans:
1. Detect plan changes
* Use billing webhooks when a user subscribes, upgrades, or downgrades.
2. Map plans to roles
* Decide which plan corresponds to which role. For example:
* "Subscriber" plan → subscriber role
* "Client" plan → client role
3. Update roles in Kinde
* Call the Kinde Management API to assign or remove roles based on the new plan.
* Optionally, Workflows can automate this, but the plan-to-role mapping must be defined by you.
4. Enforce access in your app
* Your Express.js app checks the user’s roles (via SDK or ID token) to control access to resources.
Some Ref:
https://docs.kinde.com/manage-users/roles-and-permissions/default-user-roles/#assign-roles-to-a-user
https://docs.kinde.com/billing/manage-subscribers/upgrade-downgrade-methods/
https://docs.kinde.com/billing/manage-plans/add-manage-plan-groups/
https://docs.kinde.com/billing/get-started/connect-to-stripe/
Kinde docs
Subscription upgrade and downgrade methods
Guide to upgrading and downgrading customer subscriptions including self-serve portal, manual changes, and API methods.
Kinde docs
Add and manage plan groups
Guide to creating and managing plan groups in Kinde including B2B/B2C organization, default groups, and plan ordering.
Kinde docs
Step 2 Connect to Stripe and set policies
Step-by-step guide to connecting Kinde to Stripe for payment processing and setting up billing policies for cancellations and plan changes.
Kinde docs
Set default user roles
Guide to setting default user roles in Kinde including automatic role assignment for new users and organization-specific default configurations.
Thanks will look through this all. Appreciated
Afternoon, is there any support service Kinde provides that could help me with this implementation?
Even with the welcome help of Claude code I am struggling to understand how to trigger the webhook that will see a user register for a plan, (or change a plan later through the portal) which will then assign the associated role to the user.
It's been 3 days now trying everything, and I am about to throw my laptop across the room 😆 😆
I basically need help in understanding the API managament calls to see the events, and then update the user role appropriately.
You’re building a resource portal with Express.js and using Kinde permissions for access control, and now you’d like to tie billing plans to roles (e.g. Subscriber plan → subscriber role, Client plan → client role).
From your note, it sounds like you’re mainly looking for guidance on:
Webhooks – capturing events when a user subscribes to or changes a plan.
Event payloads – reading which plan a user moved to, and which user/org it belongs to.
Management API – updating the user’s role in Kinde based on those billing events.
Can you confirm this is what you’re trying to set up?
Also, could you let us know which Kinde plan your account is currently on?
That will help us check available features and guide you better.
Also please go through these videos regarding the billing setup
https://www.youtube.com/playlist?list=PLwLelKIQLwdx0B-3lV5XP-lUF_mt8GNPA
YouTube
Kinde Billing: Complete setup guide
Everything you need to launch and manage billing inside your SaaS product without duct-taping together multiple tools. This playlist walks you through every ...
I am currenty on the kinde free plan testing things, so perhaps some functionality is missing due to this?
I use an ExpressJS app hosted on Netlify. Authenticating with Kinde and gated content access using roles and permissions is working correctly. I am also able to generate a self-serve portal so the user can change their plan. I have setup billing, plans, and connected to stripe testing. This all works.
What I am now trying to configure is for the webhook to trigger a role change depending on the plan a user is subscribing to. I.e., the user changes from subscriber plan (plan_subscriber) to client (plan_client), and the client role (role_client) is assigned to them. This then allows the configured permissions (access:client) to be set, and thus provides them access to my gated client content.
What I am struggling to implement is flow for my M2M application, how to identify the user's current plan subscribed to, and then assign the appropriate role.
Configuration
Plans (name, key)
- Client, plan_client
- Subscriber, plan_subscriber
Roles (name, key)
- Client, role_client
- Subscriber, role_subscriber
Permissions (name, key)
- Client access, access:client
- Subscriber access, access:subscriber
Role Assigned Permissions
- role_client, [access:client,access:subscriber]
- role_subscribed, access:subscriber
Webook trigger events configured
- customer.plan_assigned
- customer.plan_changed
- customer.agreement_cancelled
Machine to machine (M2M) application authorized, scopes
- read:users
- update:users
- read:roles
- create:roles
- update:roles
- create:portal_url
Will be updating this, as possibly found a solution.
OK so I am running into problem with matching
user_id and customer_id
When a user registers for the first time and subscribes, I want the webhook customer.plan_assigned to assign the corresponding role of the plan. (See previous detailed post above).
Then similarly when the user changes their plan in the portal customer.plan_changed the same assigning of corresponding role of the plan.
However, the question and problem I have is how to resolve customer_id to user_id.
The webhook gives customer_id but I need the user_id to update role.
What is the recommended approach for mapping webhook billing events to specific users for role management purposes, and is there a way to configure webhooks to include the user_id field in the payload?
An explanation from Claude Code:
The webhook gives you customer_id (the billing entity who pays for subscriptions) but you need user_id (the actual person who should get updated permissions), and there's no API endpoint in Kinde to convert between them - this is because Kinde's billing system treats customers and users as separate entities (one customer can pay for multiple users in an organization), but their webhook only tells you which customer changed plans, not which specific user(s) should have their roles updated, leaving you with no direct way to know who to grant the new permissions to.I found https://discord.com/channels/1070212618549219328/1399377429306413176 in support, but this does not work? Did it work prior?
Problem Identified The current approach fails because the Kinde Management API does not support expand=billing on the /api/v1/users endpoint. This causes INVALID_EXPAND_VALUES errors. Root Cause - Webhooks provide customer_id but no user_id - No direct API endpoint exists to map customer_id to user_id - The user endpoints don't expose billing information - Only organization endpoints expose billing data