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 to enable one or both features:

• Use Stripe entitlements: Include entitlement data in access tokens
• Sync organization seat counts: Send member counts to Stripe billing meters

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 either of these features, 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.