Stripe: Entitlements are not updated after Trial ends

Question

We use Stripe Payment Links and Entitlements to manage user payments and permissions in our application. Here’s how our system is set up:

1. We map Stripe customer IDs to our internal user IDs.
2. We store the entitlements of each user in a table.

Both of these tables are synced with Stripe webhooks. Additionally, we have some Payment Links set up with free trials.

Yesterday, I tested what happens when a trial expires:

• I created a Payment Link with a one-day free trial (in test mode).
• I successfully completed the payment process.
• The appropriate webhook events (entitlements.active_entitlement_summary.updated) were triggered, and the entitlements table was updated correctly.

However, 24 hours later, when the trial ended, I expected the entitlements to update accordingly, but they did not:

• Webhook events like customer.subscription.paused were triggered, but no entitlements.active_entitlement_summary.updated events were fired.
• As a result, the user's entitlements still showed as active, granting them access even though the trial had expired.

According to the Stripe documentation:

"During the lifecycle of a customer’s subscription, from activation, through upgrades, downgrades, and so on, Stripe updates the customer’s entitlements based on your mapped features. ... As long as a customer maintains an active subscription for a feature, they retain an active entitlement. Make sure you provision access in your system for any users entitled to this feature."

This behavior raises several questions:

1. Will the entitlements be updated at a later time, or is this expected behavior?
2. If not, what would the proper way to handle trials in my case be?
3. Should we expect entitlements.active_entitlement_summary.updated events to fire when a subscription is canceled, paused, or deleted?
4. If we need to sync the subscription status in a separate table anyways, does this not defeat the point of "Simplifing your billing integration"?

Any insights into how Stripe handles entitlements in these situations and the best practices for managing access control would be greatly appreciated! I already looked through the relevant docs and I found nothing about this behaviour.

Answer 1

We decided to listen to other webhooks and store the trial expiration data ourselves. The entitlements.active_entitlement_summary.updated webhook not triggering on trial expiration was confirmed as expected behavior by the Stripe Discord server:

I would assume this behaviour is 'expected' in that we don't remove an entitlement for a paused subscription

Alternatively, you can configure the payment link to terminate the subscription at the end of the trial, but this feature is only available through the Stripe API and not in the Stripe UI.