Retrieve a user’s Stripe Connect account ID. This query only returns the ID if the user has completed Stripe Connect onboarding.
import { api } from "@/convex/_generated/api";
import { useQuery } from "convex/react";
const stripeConnectId = useQuery(api.users.getUsersStripeConnectId, {
userId: "user_2abc123def456"
});
Parameters
The Clerk user ID of the organizer whose Stripe Connect ID you want to retrieve.Example: "user_2abc123def456"
Response
Returns the Stripe Connect account ID as a string, or undefined if:
- No user exists with the given
userId
- The user has not connected their Stripe account
Example Response
Use Cases
Check if User Can Create Paid Events
function CreateEventButton({ userId }: { userId: string }) {
const stripeConnectId = useQuery(
api.users.getUsersStripeConnectId,
{ userId }
);
if (!stripeConnectId) {
return (
<div>
<p>Connect your Stripe account to create paid events</p>
<StripeConnectButton />
</div>
);
}
return <CreatePaidEventForm />;
}
Route Payment to Event Organizer
async function processTicketPurchase(
eventId: string,
buyerUserId: string
) {
// Get event details
const event = await ctx.db.get(eventId);
// Get organizer's Stripe Connect ID
const stripeConnectId = await ctx.runQuery(
api.users.getUsersStripeConnectId,
{ userId: event.userId }
);
if (!stripeConnectId) {
throw new Error("Organizer has not connected Stripe account");
}
// Create payment intent with connected account
const paymentIntent = await stripe.paymentIntents.create({
amount: event.price * 100,
currency: "usd",
transfer_data: {
destination: stripeConnectId,
},
});
}
Display Organizer Payment Status
function OrganizerDashboard({ userId }: { userId: string }) {
const stripeConnectId = useQuery(
api.users.getUsersStripeConnectId,
{ userId }
);
return (
<div>
<h2>Payment Settings</h2>
{stripeConnectId ? (
<div>
<CheckIcon /> Connected to Stripe
<p>Account ID: {stripeConnectId}</p>
<a href={`https://dashboard.stripe.com/${stripeConnectId}`}>
View Stripe Dashboard
</a>
</div>
) : (
<div>
<WarningIcon /> Not connected to Stripe
<p>Connect your account to receive payments</p>
<StripeConnectButton />
</div>
)}
</div>
);
}
Implementation Details
The query filters for users with a defined stripeConnectId:
const user = await ctx.db
.query("users")
.filter((q) => q.eq(q.field("userId"), args.userId))
.filter((q) => q.neq(q.field("stripeConnectId"), undefined))
.first();
return user?.stripeConnectId;
Why Use This Query?
While you could use getUserById and access the stripeConnectId field, this query:
- Returns only the ID: Reduces data transfer when you only need the Connect ID
- Filters for defined values: Only returns results if the user has completed Stripe onboarding
- Optimizes for payment flows: Purpose-built for payment routing logic
Stripe Connect Setup
Setting the Stripe Connect ID
The Stripe Connect ID is set through the updateOrCreateUserStripeConnectId mutation (internal use):
await ctx.runMutation(api.users.updateOrCreateUserStripeConnectId, {
userId: "user_2abc123def456",
stripeConnectId: "acct_1MZy3x2Abc123Def"
});
Stripe Connect Onboarding Flow
- User initiates Stripe Connect onboarding
- Complete Stripe’s account verification
- On success, call
updateOrCreateUserStripeConnectId with the account ID
- User can now create paid events
Error Handling
- Returns
undefined if user doesn’t exist or hasn’t connected Stripe
- Returns
undefined while loading (in React components)
- Throws error in
updateOrCreateUserStripeConnectId if user not found
Security Considerations
This query does not implement access control. In production:
- Only allow users to query their own Stripe Connect ID
- Implement authentication checks in your application layer
- Consider making this an authenticated query with identity checks
Notes
- Stripe Connect account IDs follow the format
acct_*
- Users must complete Stripe’s verification process before receiving payments
- The
stripeConnectId field is optional in the schema
- Platform fees can be configured in your Stripe payment intent creation