Clavem

Subscription licenses with Stripe Billing: which event changes which license

A subscription license should be valid exactly while the Stripe subscription is in good standing. That takes six webhook events and a rule for each subscription status, plus a few edge cases around cancellations, trials and refunds that are easy to get wrong.

The rule

A subscription license is valid while its Stripe subscription is in good standing, plus a short margin so that a renewal that settles late does not lock out a customer. Everything else in this article is the detail behind that sentence: which Stripe status counts as “good standing”, which event tells you it changed, and what happens in the cases where the obvious rule gives the wrong answer.

From Stripe status to license state

Stripe’s subscription statuses, as of November 2026, are trialing, active, incomplete, incomplete_expired, past_due, unpaid, canceled and paused. This is how Clavem treats them:

Stripe subscription status License Why
trialing Valid Stripe says you can safely provision a trialing subscription
active Valid In good standing
past_due Valid while Stripe retries The renewal payment failed, and Stripe is retrying
incomplete No license yet The first payment has not completed
incomplete_expired Expired The first payment failed within 23 hours of creation
unpaid Expired Stripe has stopped attempting payment
canceled Expired The subscription ended
paused Expired Invoices are no longer being created

A license you disabled by hand stays disabled whatever Stripe says. Precedence in the License API is disabled, then expired, then active or inactive.

The six events

Clavem registers a webhook endpoint in your Stripe account for six events. Each one is processed once, by event id, so Stripe’s retries and your own replays are safe.

Event What happens to the license
checkout.session.completed If the session is paid, or needed no payment, and has an email: one license per mapped line item and unit, plus an order page and an email
checkout.session.async_payment_succeeded The same, for delayed methods such as bank debits
invoice.paid Moves the expiry to the end of the paid period plus three days, and revives an expired license
customer.subscription.updated Mirrors the status in the table above
customer.subscription.deleted Expires the license
charge.refunded A full refund of a one-time payment disables its licenses. A partial refund changes nothing

Because a Checkout Session for a trial needs no payment, checkout.session.completed fires and the license is issued at the start of the trial. A bank-debit purchase issues nothing until the payment actually settles and checkout.session.async_payment_succeeded arrives.

Expiry dates, worked through

Clavem stores an expires_at for a subscription license: the end of the paid period plus three days. The API evaluates expiry when it reads the license, so the status changes the moment the date passes. There is no scheduled job and no delay.

Take a monthly subscription bought on 10 December 2026 at 12:00 UTC. Assume Stripe’s default retry policy for new accounts, up to 8 retries within 2 weeks, and a failed-payment setting that cancels the subscription when the retries run out.

When Event License after the event
10 Dec 2026 checkout.session.completed Valid until 13 Jan 2027, 12:00 (period end 10 Jan, plus 3 days)
10 Jan 2027 invoice.paid for the renewal Valid until 13 Feb 2027, 12:00
10 Feb 2027 Renewal payment fails, status becomes past_due Still valid while Stripe retries
24 Feb 2027 The last retry fails and the subscription is canceled Expired at once
2 Mar 2027 Customer fixes the card and subscribes again A new subscription and a new license

The second row matters. If the renewal settles three days late, the customer never sees an expired license, because the margin absorbs it. The fourth row shows the limit of the margin: when Stripe gives up, the license expires when the status changes, not three days later.

A new subscription after a cancellation is a new purchase and issues a new license. The old key stays expired.

Cancellations and the margin

A customer who cancels at the end of the period keeps the license until that period ends. Stripe then sends customer.subscription.deleted, and the license expires. The three-day margin protects late payments. It does not extend a cancellation, so a cancelled license ends when the subscription does, not three days after.

Quantity, trials and plan changes

Quantity. A line item with quantity five issues five licenses, up to 100 per line item. Each has its own device limit, so a team can hand one key to each person. If you want one key with a higher limit instead, see seat-based licensing for teams.

Trials. A trial subscription is trialing, and the license is valid. If the trial ends without a payment method and your Stripe setting pauses the subscription, the status becomes paused and the license expires. Test this path, because it is the one a trial customer who forgets to add a card will hit.

Plan changes. Clavem maps a Stripe product or price to a Clavem product at purchase time. Of the six events, none moves an existing license to a different Clavem product. If a Stripe plan change should change what a customer can do, make that change by hand in the dashboard or with the management API, or use one product with a limit you adjust.

Edge cases

Situation What Clavem does What you do
Full refund of a subscription invoice Nothing Cancel the subscription, or disable the license
Subscription with a manually created license Nothing, the license has no Stripe subscription Extend the expiry by hand
Imported licenses Stripe events never change them Extend by hand, or re-issue through Stripe
Stripe pauses collection paused, the license expires Resume the subscription to restore access
Webhook delivery fails Clavem answers with an error so Stripe retries Check Developers, then Webhooks, in Stripe

Test with a test clock

You do not have to wait a month to test a renewal. In a Stripe sandbox, a test clock lets you advance simulated time and watch the subscription and its invoices change. Create a customer on a clock, attach 4242 4242 4242 4242, subscribe, and advance the clock past the period end. Then check the license in Clavem. For a failed renewal, Stripe’s testing documentation lists the card 4000 0000 0000 0341, which attaches to a customer successfully but fails when charged. Use it to watch the license through past_due and into expiry, and again to confirm that paying revives it.

What it costs on the Stripe side

Billing adds a charge to ordinary card fees. Stripe’s pay-as-you-go Billing price is 0.7% of Billing volume, as of November 2026 on the Swiss pricing page. For a $19 monthly plan with a domestic card, using 2.9% plus $0.30 for the card, the card fee is $0.85 and Billing adds $0.13, so about $0.98 per charge, or 5.2%. See payment fees for software sellers for other platforms.

Doing this with Clavem

Clavem does the mapping in the tables above for you: connect Stripe with a restricted key, map a Stripe product or price to a Clavem product, set its validity to follow the subscription, and the six events are handled. The detail for each is in the Stripe documentation. For the failure path, read failed subscription payments, and for the margin, grace periods for expired licenses.

Questions

Which Stripe events should end a subscription license?

A subscription update that moves the status to canceled, unpaid, paused or expired before the first payment, and the subscription deleted event. Keep access for trialing, active and past due while Stripe retries the payment.

Does refunding a subscription invoice revoke the license?

Not in Clavem. A full refund disables licenses from a one-time Checkout payment, but refunding a subscription invoice does not. Cancel the subscription, which expires the license, or disable the license yourself.

How many licenses does a quantity of five create?

Five. Clavem creates one license per unit, up to 100 per line item, and each license has its own device limit.

Sources

  1. Stripe Billing, how subscriptions work and subscription statuses (as of November 2026)
  2. Stripe, automate payment retries with Smart Retries (as of November 2026)
  3. Stripe, test clocks for subscription lifecycle tests (as of November 2026)
  4. Stripe pricing for Switzerland, including Billing (as of November 2026)