Upgrades

Customers upgrade their license through the customer portal:

1. They sign in at https://portal.keylight.dev (magic link to the email on their license).
2. They open the license and tap Upgrade, then pick a higher tier — no key or email re-entry, since the session already identifies them.

Keylight validates the upgrade, charges through your existing payment provider, and swaps the license’s key type in place. The license key string never changes. (In-app upgrade UI via the SDK is on the roadmap — see below.)

Setting up upgrades

Stripe (Connect, override key, or Payment Link)

Nothing to configure. Keylight uses your existing Stripe integration to create checkout sessions with the upgrade metadata attached.

Merchant-of-Record providers

Add an API key for your provider, on the Live slot. That’s the whole setup. Keylight creates each upgrade checkout through the provider’s API so it can attach the customer’s license key, then raises their existing license when the payment lands.

Provider	Upgrades	Needs
Paddle	Yes	API key with transaction.write
Polar	Yes	Organization token with checkouts:write
Lemon Squeezy	Yes	API key
Gumroad	No	—

The key type’s Upgrade checkout URL field is not used by any provider. Leave it blank.

Caution

Don’t build an upgrade link by hand. A checkout link is one static artifact shared by every customer, and an upgrade has to carry one customer’s license key. Most providers silently drop query parameters they don’t recognise, so a hand-built link checks out and pays perfectly, then arrives with no upgrade key — and the customer receives a brand-new license instead of an upgrade, with no error shown to anyone.

Gumroad is unsupported for exactly this reason: it can’t carry per-customer data reliably from a link.

After paying, customers land back on the license they just upgraded — except on Paddle, where the redirect belongs to your own Paddle.js page. See Paddle setup.

Paddle-specific: API key

Paddle’s webhooks don’t include customer email, so Keylight needs to fetch it via Paddle’s API. Add your Paddle API key (Paddle dashboard → Developer Tools → Authentication) on the Integrations card. The same key covers upgrades. Existing Paddle customers issued before this was set up can be backfilled — contact Keylight support if you’d like us to run the resolver for you.

Free upgrades

To offer an upgrade at no cost, set the target key type’s price to 0 and enable it as an upgrade target (upgradeEnabled). A free upgrade:

• requires no payment provider — it works even if the product has no Stripe or merchant-of-record integration configured;
• is applied instantly when the customer selects it in the portal (no checkout step) — their license switches to the new key type’s device limit and entitlements immediately;
• is only available for one-time tiers. A tier billed as a subscription can’t be granted for free, because there is no subscription to attach.

Any non-zero price keeps the normal checkout flow.

Adding seats

When a key type is set to sell in multiples, a customer who needs more devices doesn’t have to change tier — they buy more of the tier they already own.

The license page in the customer portal gains an Add seats button. The customer picks how many to add and pays through Stripe; their existing license grows in place. The key string never changes, and the extra activations are usable as soon as the payment lands.

Add seats appears only when all of these hold:

• the key type has Sell in multiples on;
• the key type has upgrades enabled, and a non-zero price;
• the license is not subscription-billed — a subscription’s seat count is changed on the subscription itself (below);
• the product sells through Stripe with a real Price, since no merchant-of-record checkout can carry a quantity.

Seat packs are additive only. There’s no “remove seats” for a lifetime key: nothing is being billed month to month, so there’s nothing to stop paying for.

Seat changes on a subscription

For subscription licenses the seat count lives on the Stripe subscription. When the customer changes the quantity, Stripe notifies Keylight — and the two directions are deliberately not symmetric.

More seats apply immediately. The customer has paid for them, so the higher limit is live at once and the next device activates without waiting on anything.

Fewer seats take effect at the end of the period they’ve paid for. Keylight won’t shrink a limit under devices that are in use right now. Instead it schedules the reduction for the moment the customer stops paying for those seats, and tells them twice:

• an email naming how many devices to remove, and by when;
• a banner on the license in the portal, with a device chooser.

If they choose, the reduction applies the moment they confirm. If the deadline passes with no choice made, Keylight removes the least recently used devices to bring the license down to its new limit. Either way the customer keeps working right up to the deadline, and the license is never left sitting over its limit afterwards.

You can see a pending reduction before it lands: the license row in your dashboard carries a clock badge, and the change detail spells out both the seat count and the device limit it’s moving to.

In-app upgrades via the Swift SDK

In-app upgrade UI is on the roadmap: the SDK will let you render the upgrade flow inside your own app instead of sending customers to the portal. The backend it builds on — POST /upgrade-session, which validates the intent and returns a provider checkout URL — already exists. Until the SDK ships this, send customers to the customer portal to upgrade.

After a customer upgrades, call licenseManager.refresh(force: true) from your scene-foreground hook so the new tier appears without a relaunch.

Recovering a lost key

Customers who lose their key sign in to the customer portal at https://portal.keylight.dev — they enter the email on their license, click the magic link, and their keys are listed in the dashboard with copy and “email me this key” options. There’s no separate recovery page: signing in needs only the email already on the license. Link your support pages to https://portal.keylight.dev.

What is and isn’t supported in v1

• Same-product upgrades (any key type → any other key type within the same Keylight product).
• Both upgrades (lower-tier → higher-tier) and “side-grades” — as long as the target tier’s seat count is ≥ your customer’s current active devices.
• On a license sold in multiples, a tier change keeps the seat count — a 3-seat customer moving to an 8-device tier lands on 24 devices, not 8.
• Cross-product upgrades (V1 modeled as Product A → V2 modeled as Product B) are not supported. Workaround: model V2 as a new key type under your existing product.
• Proration when transitioning from a one-time key type to a subscription key type is not automatic. The new subscription’s billing cycle starts fresh.
• Automatic refunds on downgrades are not included. Issue refunds yourself on the payment platform.