Stripe

WorkOS provides two powerful Stripe integrations that help you manage billing and access control for your B2B application:

• Stripe Entitlements: Automatically provision access tokens with subscription-based entitlements from Stripe
• Stripe Seat Sync: Automatically sync organization member counts to Stripe billing meters for usage-based billing

Both features use Stripe Connect to connect your WorkOS account to your Stripe account, allowing WorkOS to manage these integrations on your behalf.

To use either Stripe Entitlements or Stripe Seat Sync, you’ll first need to connect your WorkOS account to Stripe using Stripe Connect.

Navigate to the Authentication section of the WorkOS Dashboard and click Add-ons.

From that page, find the Stripe Add-on and click Enable.

This will open a Dialog to pick the Stripe features you would like to use. When clicking Continue you’ll be directed to Stripe where you can approve the connection. Once that’s complete, close the tab.

In the connection dialog, you can choose which features to enable:

• Use Stripe entitlements: Include entitlement data in access tokens
• Sync organization seat counts: Send member counts to Stripe billing meters
• Use payment outcomes in Radar: Allow WorkOS Radar to read payment and fraud outcomes to identify trustworthy users

If you decide to disconnect your Stripe account later or toggle features on and off, you can do so from the same section. Click the Manage button to disable features or disconnect entirely.

To use Stripe entitlements or seat sync, you’ll need to set the Stripe customer ID on each WorkOS organization.

Once you have a WorkOS organization ID and a Stripe customer ID, you can set the Stripe customer ID for the organization. One way to handle this is to create a Stripe customer and then set the created Stripe customer ID on the WorkOS organization. This can be done via the WorkOS API or SDK. Here’s an example using the SDK:

// Create the Stripe customer (using the Stripe SDK)
const customer = await stripe.customers.create({
  email: user.email,
  name: organization.name,
  metadata: {
    organizationId: organization.id,
  },
});

// Tell WorkOS which Stripe customer ID to use for the organization
await workos.organizations.updateOrganization({
  organization: organization.id,
  stripeCustomerId: customer.id,
});

Entitlements are a way to provision an account in your application with specific features or functionality based on the subscription plan a user is on. For example, you might have an “Enterprise” plan that allows users to access certain features like Audit Logs, and a “Basic” plan that does not.

The WorkOS Entitlements integration makes it easy to get Stripe’s entitlement information into your application without needing to listen to Stripe webhooks or explicitly track them in your application.

The access token will now include the entitlements claim, containing the user’s entitlements. You can use this information to gate access to features in your application.

Entitlements will show up in the access token the next time the user logs in or the session is refreshed. You can manually refresh the session after the user has completed their subscription purchase. Here’s an example in Express:

app.get('/api/entitlements', async (req, res) => {
  // load the original session
  const session = workos.userManagement.loadSealedSession({
    cookiePassword: process.env.WORKOS_COOKIE_PASSWORD,
    sessionData: req.cookies['wos-session'],
  });

  const { sealedSession, entitlements } = await session.refresh();

  // set the updated refresh session data in a cookie
  res.cookie('wos-session', sealedSession, {
    httpOnly: true,
    sameSite: 'lax',
    secure: true,
  });

  // return the entitlements to the client
  res.json({
    entitlements,
  });
});

Stripe Seat Sync automatically sends active organization member counts to Stripe as billing meter events under Usage-based billing, enabling usage-based billing based on the number of seats (members) in each organization.

When Stripe Seat Sync is enabled:

• WorkOS creates a billing meter in your Stripe account called “User Seat Count” with the event name workos_seat_count
• Whenever a member is added, removed, deactivated, or activated from an organization, WorkOS automatically sends a meter event to Stripe with the updated seat count
• You can use this meter in Stripe to create usage-based pricing based on the number of active seats

The meter uses Stripe’s “last” aggregation method, which means Stripe will bill based on the most recent seat count reported during each billing period.

Once enabled, WorkOS will automatically send meter events to Stripe whenever organization memberships change. You can:

• View the meter events in your Stripe Dashboard under Billing → Meters
• Create pricing models that bill based on the workos_seat_count meter
• Use the meter in subscription items to charge customers based on their current seat count

The meter event includes:

• Event name: workos_seat_count
• Customer ID: The Stripe customer ID associated with the organization
• Value: The current number of active members in the organization

No additional code is required in your application – WorkOS handles all meter event reporting automatically as members join or leave organizations.

When connecting your Stripe account, you can optionally allow WorkOS Radar to use payment outcomes from the connected account as trust signals. This option is off by default and is configured per environment.

When enabled, WorkOS periodically reads payment and fraud outcomes from the connected Stripe account – successful payments, refunds, disputes, and early fraud warnings – and matches them to users in your environment. Successful payments are recorded as positive signals that help Radar identify trustworthy users, while fraudulent disputes and early fraud warnings are recorded as fraud signals.

WorkOS matches each payment to a user by checking, in order: a workos_user_id key in the Stripe customer’s metadata, the organization associated with the Stripe customer ID (when the organization has a single member), and an exact match on the Stripe customer’s email address. For the most reliable matching, set a workos_user_id metadata key containing the WorkOS user ID on your Stripe customers.

You can enable or disable this option at any time by clicking the Manage button in the same Add-ons section. Disabling it stops WorkOS from reading new payment data; previously recorded signals are retained.