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
- Stripe Billing, how subscriptions work and subscription statuses (as of November 2026)
- Stripe, automate payment retries with Smart Retries (as of November 2026)
- Stripe, test clocks for subscription lifecycle tests (as of November 2026)
- Stripe pricing for Switzerland, including Billing (as of November 2026)