Entitlements sync between Stripe and your app

What are entitlements?

Entitlements are a feature management system that map product features to pricing plans.

If you offer customers multiple pricing plans, it's probable that those plan details are duplicated in your codebase. This coupling can make it impossible to manage pricing plans without involving an engineer.

Entitlements are an effective way to decouple the plan management from the code that allows feature access. If you're familiar with role-based access control (RBAC), think of pricing plans and entitlements like roles and permissions, respectively. Plans are (non-exclusive) collections of entitlements. And once customers select a pricing plan, they are entitled to its included features.

With entitlements, your codebase can check if a customer has access to a feature, regardless of the pricing plan they selected.

WorkOS now offers a one-click integration with Stripe’s Entitlements. Let's explore how they work and when to use them.

What’s hard about entitlements

Stripe does a lot of heavy lifting for you — managing billing, renewing subscriptions, and tracking corresponding entitlements. But it doesn't connect that data to your application.

At a minimum, an effective integration requires several pieces of functionality.

• Persisting customer entitlements: Applications need to retrieve customer entitlements from Stripe and persist them. While the process may appear straightforward, insufficient error handling can lead to issues, such as missed updates that result in stale or inconsistent data.
• Loading entitlements in the frontend: App frontends must load entitlements associated with each user. Querying for this data adds complexity, can introduce latency, and any errors need to be handled gracefully to avoid bad user experience.
• Keeping entitlements synchronized: When a customer completes a purchase they expect immediate access to a new feature so any updates to entitlements must be reflected promptly. Delays in fetching the latest data can lead to poor user experiences.

The additional code complexity and correct handling of synchronization make the process of managing entitlements a challenge.

With WorkOS Entitlements, we’ll handle the synchronization and surface entitlements directly in a user’s access token without the complexity.

WorkOS can handle Stripe Entitlements for you

Getting started with WorkOS Stripe Entitlements integration involves the following:

• Enable Entitlements in the WorkOS Dashboard and authorize WorkOS to connect to your Stripe account.
• Set the Stripe customer ID associated with each of your WorkOS organizations.

Entitlements are set at the organization level so the only code that’s required is to set the Stripe customer id on the WorkOS organization. Typically this is done after creating the Stripe customer and before redirecting the user to a Stripe billing page.

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

// Use the WorkOS SDK to set the Stripe customer ID for the organization
await workos.organizations.updateOrganization({
  organization: organization.id,
  stripeCustomerId: customer.id,
});

// redirect to the Stripe billing portal

Once in place, entitlements will automatically start flowing from Stripe to WorkOS. Each user in an organization will receive access tokens with the entitlements afforded by their organization’s subscription. Here’s what a partially decoded WorkOS access token looks like with the additional entitlements claim.

{
  iss: "https://api.workos.com",
  sub: "user_01JB0CQK1GTG9VDCG3KGQYKF9C",
  sid: "session_01JCHAE975HXQFCS7Y197TKDTP",
  jti: "01JCHAEE8XTFSKS4ZN2BYYWHWP",
  org_id: "org_01JB0CQY3ZHX4BNE4NDATJVEED",
  role: "admin",
  entitlements: ["audit-logs"],
  exp: 1731453504,
  iat: 1731453204
}

Best practices for working with entitlements

There are a couple of things to keep in mind as you take advantage of WorkOS Entitlements in your own application.

Decouple billing from application code

Focus on the features being provided, rather than what plan a user has access to. By decoupling the billing logic from the app logic, it’s easy to add new subscription tiers, or modify existing ones, without having to change any application code.

It can be helpful to think once more about the analogy to RBAC systems. When gating sensitive actions with specific permissions, rather than the role that can perform it, it becomes much easier to add more roles when the need arises. You’ll see a similar separation of concerns with entitlements.

Keep entitlements up to date

Entitlements need to be synced as quickly as possible. If a user upgrades their subscription, they should get access to the new features. The WorkOS integration takes care of this for you, listening to updates from Stripe webhooks and storing it.

Since WorkOS Stripe Entitlements integration works by provisioning access tokens with entitlements, your app can also refresh the session to ensure the user’s access token is up to date. Revisiting the earlier example:

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, session: newSession } = await session.refresh();
  const { entitlements } = newSession;

  // 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,
  });
});

Ship what matters

This integration with Stripe Entitlements is just one more way that we help you ship what matters – high quality customer experiences that users love.

To get started, enable Stripe Entitlements in the WorkOS Dashboard and check out the docs to simplify plan management and feature access.