Skip to content
← All posts
· Delta1 Labs EntitlementsKeyright

Upgrading a license in place from trial to paid

When a customer converts a trial to paid or moves from Standard to Pro, the key string they already activated should not change. Here is how to upgrade a license server-side in Keyright — lifting the trial flag, extending expiry, adding entitlements — so the deployed SDK app picks up the new grant on its next ValidateAsync with zero re-activation friction, plus how to tune revalidation timing, keep the upgrade call idempotent, and audit every entitlement change.

A customer finishes their trial and pays. Or a Standard customer upgrades to Pro. Or they buy one add-on mid-term. In every one of these moments the instinct is to mint a fresh license key and email it over — and in every one of them that is the wrong move. The key the customer already activated is a signed grant of entitlements; converting a trial to paid, or Standard to Pro, is a change to what that grant says, not a reason to replace it. Upgrade the license in place and the customer’s installed key string never changes: no new key to deliver, no copy-paste, no re-activation, no “I never got my key” ticket.

This is a how-to for doing exactly that with a self-hosted Keyright deployment. We will change a license server-side, watch the deployed SDK pick up the new entitlements on its next validation, and then handle the parts that make it feel instant and stay correct: cache propagation, idempotency, downgrades and the audit trail.

The deployed app never changes

Start from the app’s side, because that is the part that must not move. A .NET app embeds the Keyright SDK, initialises it once, and gates features on entitlements:

KeyrightClient.Initialize(new KeyrightOptions
{
    Product         = "acme-studio",
    PublicKeyBase64 = "MCowBQYDK2VwAyEA...",   // your deployment's verify key
    ServiceUrl      = "https://license.acme.example",
});

var result = await client.ValidateAsync();
if (!result.IsValid)
{
    // Fail closed: no valid license → no paid features.
    EnterRestrictedMode(result);
    return;
}

// Gate a paid feature on an entitlement, not on a tier name.
exportButton.Enabled = client.HasEntitlement("pro.export");

Note what the app is not doing: it is not checking a tier string, not comparing dates, not special-casing “trial”. It asks one question per feature — HasEntitlement("pro.export") — and fails closed when the license is invalid. That single discipline is what makes an in-place upgrade possible, because the only thing an upgrade has to do is change which entitlements the license carries. The app’s code is already written to react.

Change the license, not the key

On the server side an upgrade is a patch to the existing license record. Keyright exposes this through the admin API (and the same action is available as a button in the dashboard). The license is addressed by its id — not by the key string, which stays private to the customer:

PATCH /v1/admin/licenses/lic_7f3a9c2e HTTP/1.1
Host: license.acme.example
Authorization: Bearer {admin_token}
Idempotency-Key: order-558120
Content-Type: application/json

{
  "tier": "pro",
  "entitlements": ["core.use", "pro.export", "pro.batch"],
  "expiresAt": "2027-11-14T00:00:00Z",
  "trial": false
}

That one call does the whole trial-to-paid conversion: it lifts the trial flag, pushes the expiry out a year, and swaps the trial’s entitlement set for the paid one. The license id is unchanged, so the key string the customer typed into the app a week ago is still valid and still theirs. Nothing about their machine, their activation or their data moves. The next time their app validates, the issuing service signs a fresh lease carrying pro.export and pro.batch, and HasEntitlement("pro.export") returns true.

A tier upgrade (Standard → Pro) is the identical shape — you send the Pro tier and its larger entitlement set. A mid-term add-on is smaller still: leave tier and expiresAt alone and send the entitlement list with the extra capability appended. Because the app gates on individual entitlement strings, adding pro.batch to the list unlocks exactly that feature and touches nothing else.

How the app picks it up

The upgrade is live on the server the moment the PATCH commits. When the app sees it depends on validation timing.

App timeline ValidateAsync trial lease cached cached interval — app serves trial vendor PATCHes → Pro next ValidateAsync Pro lease · pro.export unlocks propagation gap = time to next revalidation Shorter interval unlocks almost at once small gap

Between validations the SDK serves a cached lease so the app keeps working offline and does not hit the network on every feature check. If the customer paid during that cached window, the app keeps showing the trial until the cache expires and it revalidates. That is not a bug — it is the offline-tolerance that makes the SDK usable — but it is the thing that makes an upgrade look broken.

Three levers close the gap:

  • Shorten the revalidation interval for products where instant upgrades matter. A shorter RevalidationInterval means the next online ValidateAsync happens sooner, so the new entitlements arrive sooner. The trade-off is more check-ins; tune it to the experience you want.
  • Force a validation on a user action. Give the app a “Refresh license” menu item, or trigger ValidateAsync when the user opens the upgrade-success screen after returning from checkout. This turns the propagation gap into a single round-trip.
  • Re-validate on resume. Calling ValidateAsync on app launch or on window focus means a customer who paid and re-opened the app gets the upgrade immediately, which is the most common conversion path.
// Called from a "Refresh license" action after the customer returns from checkout.
async Task RefreshAfterPurchaseAsync()
{
    var result = await client.ValidateAsync(force: true);   // skip the cache
    if (result.IsValid && client.HasEntitlement("pro.export"))
        UnlockProFeatures(result.LicenseInfo);              // live, same key
}

result.LicenseInfo carries the refreshed tier, entitlement set and expiry, so the UI can relabel the plan and drop the “trial ends in N days” banner in the same pass.

Make the upgrade idempotent

Upgrades are usually driven by a billing webhook, and webhooks are delivered at least once — the same order.paid event can arrive twice, and a timed-out call will be retried. If your upgrade logic were a relative mutation (“add 1 year”, “append an entitlement”), a duplicate would double the expiry or stack a second copy. So model the upgrade as a declaration of target state, not a delta.

The PATCH above does this: it sets the tier, the full entitlement list and the absolute expiresAt. Send it twice and the license converges to the same record — tier pro, those entitlements, that expiry. The Idempotency-Key: order-558120 header makes it explicit: Keyright records the outcome under that key, so a retry replays the stored result instead of re-applying the change. Key it on the order or payment reference — something stable across retries of the same purchase and distinct across genuinely different purchases.

// Billing webhook handler — safe to run on every delivery of the event.
app.MapPost("/webhooks/billing", async (BillingEvent e) =>
{
    if (e.Type != "order.paid") return Results.Ok();

    await adminApi.PatchLicenseAsync(e.LicenseId, new LicensePatch
    {
        Tier         = e.PlanTier,              // "pro"
        Entitlements = EntitlementsForPlan(e.PlanTier),
        ExpiresAt    = e.CurrentPeriodEnd,      // absolute, not relative
        Trial        = false,
    }, idempotencyKey: e.OrderId);

    return Results.Ok();
});

Downgrades and expiry

The same path runs in reverse, and because the app gates on entitlements it needs no new code to handle it. When a subscription lapses, either let the expiresAt pass or PATCH the license to the lower tier with the reduced entitlement set. On the next revalidation the signed lease no longer carries pro.export, HasEntitlement("pro.export") returns false, and the gated UI degrades. A perpetual-but-lapsed-maintenance plan is the same idea — you grant the entitlements the customer is still owed and drop the rest.

Two rules keep this clean. Fail closed: if result.IsValid is false, grant nothing — never fall through to paid features on an error. And degrade, do not destroy: a downgrade should hide or disable features, not delete the customer’s data, so that an eventual re-upgrade simply re-unlocks what was already there.

Keep an audit trail

Every one of these PATCHes is an entitlement change against a specific license, and you will want the history: when the trial became Pro, which add-on landed on which date, who authorised a comp upgrade. Keyright records each admin mutation as an event on the license — the actor, the before/after tier and entitlement set, the idempotency key, and the timestamp. Pulling that history for one license gives you a complete answer to “why does this customer have pro.batch?” without guessing, and it is the record you reconcile against billing when a dispute lands.

The whole model, in one line

A license is a mutable server-side grant behind an immutable key. Upgrades, tier changes and add-ons are edits to the grant; the key never moves; the SDK reflects the edit on its next validation; and you tune revalidation timing to decide how instant that feels. Write the app to ask HasEntitlement(...) and fail closed, and every commercial change — trial to paid, Standard to Pro, add-on, downgrade — becomes one idempotent PATCH with a clean audit trail behind it.

Try Nebula.NET

Harden your .NET code in minutes — start with the free edition.