Selling through Stripe

KeyGrant creates a license key for each paid checkout on your own Stripe account, with no code on your side. Payments go to your Stripe account. A KeyGrant account sells through Stripe or through Paddle, one at a time.

At a glance

Keys one checkout creates: Up to 100
Refunds revoke keys: On by default, in Settings > Payments
A lost dispute: Takes back what the payment bought, whatever that setting says
A sale while Stripe is disconnected: Stripe retries it for up to 3 days

1. Link your Stripe account

Open Settings > Payments (Settings is the gear at the top right of the dashboard).
Choose Connect Stripe.
Approve KeyGrant on your existing Stripe account. Stripe returns you to the dashboard.

You don't need to add a webhook endpoint in Stripe; KeyGrant receives your account's events through Stripe Connect.
Paddle must be unlinked first: a KeyGrant account sells through one processor at a time.
KeyGrant creates keys only for checkouts on the Stripe account linked there.
A Stripe account can be linked to one KeyGrant account at a time.

2. Map prices to license models

On a product's License models tab, open a model's menu and choose Edit model.
Under Price, pick the Stripe price that sells it. Its amount, currency and renewal interval come from Stripe, so there is nothing to type.

Model	Stripe price
Perpetual or timed	A one-time price.
Subscription	A monthly or yearly price.
Trial	Processor price it maps to, in place of Price: the Stripe price a customer pays to buy the app after the trial.

Each model maps to one price. Settings > Payments lists every mapping under Price to license model.

A paid checkout on a trial model's price creates a paid key of that model, never a trial key: a perpetual key when the price is one-time, and a subscription key when it recurs (see Trial keys).

Key delivery email

A new product starts on You send them: KeyGrant sends your customers no email, and your webhook endpoint receives the events so you can send your own. To have KeyGrant email each new key:

Open the product's License delivery tab.
Choose KeyGrant sends them.
Keep its Key delivery email on (it is on by default).

The email goes to the address entered at checkout.
It comes from KeyGrant's address unless the product sends from a domain verified under Settings > Domains.
Under its heading, it names the license model the key was sold under, with the model's What customers are told line beneath it when it has one. A key sold under no model, or under a model sold as an upgrade, shows neither.

To show the key on the page Stripe sends the buyer to, see After a checkout.

What a checkout creates

A checkout that includes a mapped price creates a key in these cases, with no checkout metadata needed:

Paid, or with nothing to pay.
A Stripe free trial: the key is created at checkout (see Subscriptions).
Discounted to nothing: the key is created as a sale of $0.
A pending payment, such as a bank debit: the key is created once it succeeds.

How many keys

Each checkout creates one key, or one sale of several keys for a model with more than one Keys per sale. The first line item whose price is mapped to a model decides the model, and that line's quantity decides the rest:

Keys per sale 1: one key. The quantity is recorded as the key's seats, without changing its device limit.
Keys per sale more than 1: the model's keys per sale times the quantity, up to 100, as one sale. Each key is a license of its own with the model's terms and seats 1. The buyer gets them all in one email, and a full refund or a lost dispute revokes every one.

Edge cases:

A partial refund revokes no key, and a later change of a subscription's quantity issues and revokes none. Both are recorded on the keys and your account's owners are emailed, to issue or revoke keys by hand.
More than 100 keys, or a quantity KeyGrant could not read: the checkout creates 100 keys, or one purchase's worth, and the owners are emailed.
A model sold as an upgrade changes the key the buyer already holds instead, when KeyGrant finds one (see Sell an upgrade).
A timed model bought again extends the key the buyer already holds (see Timed models).
An upgrade or a timed purchase KeyGrant cannot place is held for you to attach or refund (see Held sales).

Subscriptions

A subscription key is valid until the end of the billing period Stripe reports, and its expiry moves forward with each renewal.

Before the first period: until Stripe reports it, the key has no expiry. A free trial's key bought through your linked account is dated to the trial's end as it is created.
Grace: the Grace after expiry, days the subscription model had at the time of the sale applies equally to a lapse, a failed renewal and a cancellation: the key keeps working that many days past its expiry. Changing the setting later does not change keys already sold.
No grace for a key nobody paid for once no card retry can pay for it: a trial that never converted, or a key whose only payment was refunded, after its subscription is canceled, paused for want of a card, or left unpaid after Stripe's retries.

Event	What the key does
A free trial	Keeps working until the trial ends. When the trial turns into a paid subscription, the key runs to the end of each period paid for; that first payment is not counted as a renewal.
A trial canceled	Canceled before it turns into a paid subscription, the key stops when the trial ends, with no grace period.
A failed first payment	While Stripe retries it, the key keeps working until the trial ended plus its grace period. Once Stripe pauses the subscription for want of a card, or leaves it unpaid after its retries, the key stops.
A failed renewal	Keeps working until the end of the last period paid for, plus its grace period, however long Stripe keeps retrying the payment. When the customer pays, the key runs to the end of the new period.
A cancellation	Keeps working until the end of the period paid for, plus its grace period.

A perpetual key sold through a subscription

A perpetual key can be sold through a subscription, to be paid in installments, for example. The key does not expire when the subscription ends.

Refunds and disputes: a refund or a lost dispute of an installment leaves the key working while any payment on the subscription stands. Once every payment has been refunded or lost in a dispute, the key is revoked, as a one-time sale's would be.
Paid again: if the subscription goes on and a later installment is paid, the revoked key works again.
Bought with free time first (a free trial, or a first period discounted to nothing): the key works like a subscription key until Stripe shows an installment after that free time paid for money, which makes it perpetual. One discounted to nothing does not count.
Canceled before a paid installment: a subscription canceled before Stripe shows an installment after the free time paid for money stops the key when the free time ends, with no grace period.
The nightly check: KeyGrant checks for these payments every night. If Stripe will not tell KeyGrant, the key is made perpetual all the same, unless KeyGrant has seen each installment after the free time refunded, lost in a dispute or left unpaid.

Refunds and disputes

A full refund takes back what its payment bought while Refunds revoke keys is on in Settings > Payments (it is on by default). A lost dispute takes it back regardless of that setting. A partial refund revokes nothing (see How many keys).

What a full refund or a lost dispute takes back, by what the payment bought:

Sale	What it takes back
One-time payment	Revokes the key it bought, or every key of a sale of several.
Subscription payment	Counts the period it paid for as unpaid (see Subscription payments).
Installment	Of a perpetual key sold through a subscription: revokes the key only once every payment on the subscription is refunded or lost (see A perpetual key sold through a subscription).
Version upgrade	Takes the added versions back, unless the key's versions have changed since (see Licensing by version).
Edition upgrade	Puts the key's entitlements back, unless they have changed since. The key keeps working (see Sell an edition upgrade).
Device upgrade	Takes the devices back, unless the key's limit has been changed since by anything but a later device sale. No device is released (see Sell more devices).
Top-up of uses	Takes back only the uses not yet spent (see Sell more uses).
Timed purchase	The first purchase revokes its key, unless later purchases extended it and still stand. An extension takes back only its time (see Timed models).
Held sale	Marks it refunded, whatever the setting says.

Subscription payments

A full refund of a subscription payment, with Refunds revoke keys on, or a lost dispute on one, counts the period that payment paid for as unpaid:

The subscription's keys keep working only until that period began (or until an earlier refunded period that meets it began), plus their grace period, as after a failed renewal.
A key whose later periods were paid keeps them, and a key the refund stopped runs on again once a later period is paid.
A plan change: its payment counts the same when the change started a new period (monthly to yearly, say). One that only settled the change's prorations paid for no period, and refunding it changes nothing.
Items billed on different periods (a monthly plan with a yearly add-on, say): KeyGrant cannot tell which item's time a payment was for, so a refund there changes no key. Each key keeps its time and its history records the refund.
Your account's owners then get an email naming the charge, to revoke a key by hand on its page if it should stop. The same happens when Stripe will not show KeyGrant the subscription.

To end the subscription, cancel it in Stripe.

A refund that fails

A refund that fails after Stripe accepted it undoes what it did: the keys run to the end of the period it paid for, or as far as Stripe says is paid, even when the subscription has failed or ended since, and a perpetual key it revoked works again.

When a revoke takes effect

A revoked key stops working at the app's next check-in. Until then the app keeps working on its current lease, which lasts at most the Offline days its model had at the time of the sale, or the type's default when the model set none (see Offline validation & grace).

Repeat refunds and duplicate purchases

KeyGrant flags a key a checkout creates, and never holds one back, when its buyer looks like someone you want to know about:

Repeat refund: the buyer, by email address or Stripe customer, already holds a key of the same product, for the same major version, that a refund or a dispute took back.
Possible duplicate: the buyer's email address bought a key under the same license model in the 7 days before.

For a repeat refund, a key not yet bound to a version counts as any version. A refund that left its key active, with Refunds revoke keys off, does not count.

Never flagged:

the keys of one sale, against each other;
an upgrade that changes a key the customer holds (one that finds no key and creates a key is checked as any sale);
a key you issue by hand or over the API;
a test checkout against live keys.

What a flag does:

The key shows a badge on its license page and in Licenses.
Home lists the keys a flag waits on.
The license.flagged webhook is sent (see Webhook events).
For a live key, your account's owners are emailed, unless Mail about flagged keys is off in Settings > Payments.

Mark a flag reviewed on the key's page to take it off Home. To take the sale back, refund the payment in Stripe.

Custom links and metadata

Checkout metadata names the sale, and client_reference_id names the key an upgrade is for. A plain Payment Link on a mapped price, such as your app's Buy button opens, needs neither (see Buying from the trial).

Checkout metadata

A Payment Link's metadata is copied onto every checkout it starts. All of these are optional:

product

Your product's API ID, which selects the product. If no product has that API ID, the checkout creates no key.

modelId

The ID of a license model of that product. Read only when product is set, and then priceId is not read.

priceId

A Stripe price ID, matched to a model of that product. Read only when product is set.

model

Used only when no model is found. The key is a subscription when this is subscription or the checkout is in Stripe's subscription mode, and perpetual otherwise.

deviceLimit

Overrides the model's device limit: a whole number from 1 to 1,000. Any other value is ignored.

version

The version sold (see Licensing by version). A value that is not a version is ignored.

The customer's email, used when Stripe has none for the checkout.

With product set, a checkout creates a key for that product even when none of its prices is mapped. When no model is found, the key takes its terms as described in Keys sold under no model. Without product, a checkout with no mapped price creates no key.

The checkout's client_reference_id

Stripe's client_reference_id, which a Payment Link takes as a URL parameter, names the key a checkout upgrades.

upgradeUrl sets it to the device's activation ID. Links you build yourself can use the license key instead.
A model sold as an upgrade changes the key it names: it adds its versions, changes its edition, or adds devices (see Sell more devices) or uses. A timed model bought again extends it.
Any other model creates a new key, whatever the ID names.
When the ID names no key that can take the sale, KeyGrant looks at the buyer's email (see How KeyGrant finds the key).

Held sales

A held sale is a paid upgrade, or a timed model's purchase, that KeyGrant could not place on a key. No key is changed and none is created: the sale waits for you to attach it to a key or refund it.

Home's Needs a look on your dashboard leads to Held sales, which lists it.
The sale.held webhook is sent (see Sale events).
For a live sale, your account's owners are emailed. A held test sale is listed, and sent to endpoints with Send test license events on, but emails nobody.
The checkout lookup answers 404 checkout-held, since no key is coming (see After a checkout).

Each kind of sale is held for its own causes, listed on its page. One cause is shared: KeyGrant cannot tell the sale's line in the checkout, because it was bought with other items or Stripe would not give the checkout's lines. That happens only when the checkout named the model in its metadata, not by a mapped price.

Sale	What it does	Why it is held
Version upgrade	Adds versions to the key the buyer holds.	When a version sale is held
Edition upgrade	Changes the key's entitlements.	When an edition sale is held
Device upgrade	Raises the key's device limit.	When a device sale is held
Top-up of uses	Adds uses to the key's meters.	When a top-up sale is held
Timed model	Extends the key the buyer holds, or creates the first one.	When a timed sale is held

Resolve a held sale

Open the sale on Held sales and choose one:

Attach to a key: pick the customer's key, from the keys at the buyer's address that can take it or by searching by key or email. Only a key that could have taken the sale at checkout can take it now, and it gets what the sale sold, as the checkout would have given it.
Refund: KeyGrant refunds, in Stripe, what the sale charged for the upgrade and no more. When it cannot, refund it in Stripe, then choose Mark refunded; no key changes. A full refund of the payment made in Stripe also marks the sale refunded.

An attached sale is an upgrade like any other: a refund or a lost dispute of its payment later takes it back (see Refunds and disputes).

Stop selling

Ways to stop a model or a product selling, and what each does to keys already sold.

Unmap a model

Unmapping a model leaves Stripe selling its price, and a paid checkout on that price then creates no key unless its metadata names the product.

Archive a model or a product

Archiving a model leaves its price mapped, so a paid checkout on it still creates a key.
Archiving a model or a product offers to deactivate its prices in Stripe; otherwise deactivate the price or Payment Link in Stripe yourself.
Keys of an archived product cannot activate on a new device, so a key sold on one of its prices after it is archived cannot activate at all.

Delete a product

Warning

Deleting a product cannot be undone, and its Stripe prices are not touched: a paid checkout on one then takes payment and creates no key. Deactivate them in Stripe first.

Once a product is archived, Delete product on its Settings tab deletes it for good, with its keys and their devices, its license models, its trials, its request log and mail log, and its icon and logo. Installed copies stop being licensed as their leases run out.

Disconnect Stripe

Disconnecting Stripe in Settings > Payments stops new checkouts from creating keys.
For a live checkout paid while the account is disconnected, Stripe retries the event for up to 3 days, and KeyGrant creates the key if you link the account again in that time.
KeyGrant emails your account's owners about such a sale at most once a day.
Keys already sold keep renewing, and refunds and cancellations still apply to them.
KeyGrant still receives the account's events until you remove its access from your Stripe dashboard.