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.