Clavem

Grace periods for expired licenses: the four layers and how they stack

Four separate mechanisms can keep an expired license working: Stripe's retries, a server-side margin, the offline token window and your own app policy. They overlap, and a device that is offline can lock out a customer who has already paid, unless you show it as needs-network rather than expired.

Four layers, not one

People say “grace period” as if there were one. A license has up to four, and they run at different levels.

Layer Who sets it Typical length What it covers
1. Stripe retries Stripe, configurable by you Up to 8 retries within 2 weeks by default A failed renewal payment
2. Server margin The license service 3 days after the paid period (Clavem) A renewal that settles late
3. Offline token window The signed token 14 days after issue (refresh_by) A device with no network
4. App policy You Whatever you decide Goodwill, support cases, slow customers

Each layer protects against a different problem. The trouble starts when they are confused, so this article takes them in turn and then stacks them.

Layer 1: Stripe’s retry window

When a renewal fails, Stripe marks the subscription past_due and retries. For new accounts the default is up to 8 retries within 2 weeks. During that window Clavem treats a past_due subscription as entitled, so the license stays valid. When retries end, Stripe’s failed-payment setting decides whether the subscription is canceled, marked unpaid or left past due. The detail is in failed subscription payments. This layer is a payment recovery tool, and the license only follows it.

Layer 2: the server margin

Clavem sets a subscription license’s expires_at to the end of the paid period plus three days. The margin handles a renewal that settles a day or two late, for example a bank transfer that clears slowly. It does not lengthen a cancellation. When a customer cancels, Stripe sends customer.subscription.deleted at the end of the paid period and the license expires then, not three days later.

The server evaluates expiry whenever the license is read. There is no scheduled job, so the answer changes the moment the date passes, and it changes back when invoice.paid arrives.

Layer 3: the offline token window

Every activate and validate response carries a signed token. Its payload has two clocks:

  • exp, present for licenses that expire. For a subscription this already includes the three days of margin.
  • refresh_by, set to the issue time plus 14 days. After it, the app should validate online again.

An offline app is licensed only while both hold: exp is in the future and refresh_by is in the future. The shorter of the two ends first. For a monthly subscription, exp usually ends first.

The offline trap

Here is a timeline of a monthly subscriber with a laptop that goes offline. Dates are in 2027, UTC.

When What happens Server Device
9 Jan 12:00 Device validates, then goes offline Valid until 13 Jan 12:00 Token: exp 13 Jan 12:00, refresh_by 23 Jan 12:00
10 Jan 12:00 Renewal is paid Valid until 13 Feb 12:00 Unaware, still offline
12 Jan 12:00 Licensed
13 Jan 12:01 Valid exp has passed: not licensed
15 Jan Device reconnects and validates Valid, new token with exp 13 Feb Licensed again

The customer paid on time and was locked out for two days, because the device’s token was issued before the renewal. The server never said the license had expired. The device simply had nothing newer. If your app labels that state “expired”, the customer will insist they paid, and they will be right.

The fix is wording and flow. Treat a token that has run out while offline as needs-network, not expired. Reserve “expired” for a server answer of valid: false with status expired. Clavem’s quickstart flow already does this: it returns licensed, invalid, needs-network or unlicensed, and offline failures map to needs-network.

Layer 4: your own grace

Your app can be more generous than the token. Add a grace period after exp that applies only when the device is offline and the last good token has just run out. I ran this logic against test tokens signed with a throwaway key:

const DAY = 86400;
function offlineState(claims, now, graceDays) {
  if (!claims || claims.v !== 1 || claims.pid !== PRODUCT_ID || claims.valid !== true) return 'needs-network';
  if (claims.refresh_by <= now) return 'needs-network';
  if (claims.exp === undefined || claims.exp > now) return 'licensed';
  return claims.exp + graceDays * DAY > now ? 'grace' : 'needs-network';
}

Results with claims from verified tokens:

Token Grace 0 days Grace 7 days
Valid, no exp licensed licensed
exp 10 seconds ago needs-network grace
Signed for an expired license (valid: false) needs-network needs-network
Past refresh_by needs-network needs-network

Two rules are visible here. A token that says valid: false never gets grace, because the server has already answered. And grace never extends past refresh_by: after that the device must go online. In the grace state, show a banner that says when paid features will stop and why, and keep trying to validate in the background.

Online, there is no app-level grace

When the app is online, the server’s answer wins. If validation says valid: false, show it, because your own grace would contradict the server and the customer’s invoice. If you want to be generous with a particular customer, change the server’s answer instead.

Clock changes

A customer can move the system clock back to stretch any of these windows. If that matters to you, store the highest iat you have seen from a verified token and treat a system clock earlier than it as stale. The same stored value helps in the opposite case, when a laptop’s clock is wrong by days after a battery failure and every token looks expired or not yet issued. Show a message that names the clock as the problem instead of a license error, because “your license has expired” is the wrong diagnosis and will cost you a support thread.

Extending one customer

A support gesture does not need code. In the dashboard, or with the management API, move expires_at forward:

curl -X PATCH https://clavem.io/v1/admin/licenses/412 \
  -H "Authorization: Bearer sk_clavem_..." \
  -H "Content-Type: application/json" \
  -d '{ "expires_at": "2027-02-15T00:00:00Z" }'

Clavem’s API documentation says that moving the date into the future, or to null, revives an expired license. The customer’s next validation returns a valid token. Licenses created by hand or imported have no Stripe subscription, so Stripe events never change them and a manual date sticks. For a subscription license, treat a manual date as a short-term gesture, because later subscription events from Stripe can move the date again.

Choosing a policy

License type Layers that apply Suggested app policy
Perpetual 3 only Trust a valid token indefinitely when offline, refresh when online
Annual license, one-time purchase 2 does not apply, 3 and 4 do Seven days of app grace is usually enough
Monthly subscription 1, 2, 3 and 4 Three days of server margin, plus a short app grace for offline users
Business contract Negotiated Extend expires_at by hand when the invoice is late

A perpetual license needs no grace period, because it does not expire. Do not add one to feel safe.

Doing this with Clavem

The server margin is built in and the token carries exp and refresh_by. Your app supplies layer 4. Verify the token as shown on the offline verification page, and keep the states in the check function apart so the customer never sees “expired” for a device that is only offline.

Questions

How long is the grace period on a Clavem subscription license?

A subscription license expires at the end of the paid period plus three days. That is the margin built into the expiry date. Stripe's own retry window for a failed payment is separate and can be up to two weeks by default.

Why does an offline device say the license expired after the customer paid?

The device holds a token whose exp time has passed, and it cannot learn about the renewal until it reaches the network. Show that state as needs-network with a connect prompt, not as expired.

Can I give one customer extra time?

Yes. Move the license's expiry date forward with the management API or in the dashboard. Moving it into the future revives an expired license.

Sources

  1. Stripe, Smart Retries default of 8 retries within 2 weeks (as of November 2026)