Sell software license keys
Add a license key setting to a digital product and Flint issues one key for each unit a buyer pays for, emails it, and answers your app when it checks the key. Refunds, chargebacks, and subscription changes disable keys without code on your side. License keys has the full rules for every call below, and How to sell software online with license keys covers the mistakes sellers make with key entropy, device limits, and offline checks.
| Step | What you do | Section |
|---|---|---|
| Set up the product | Add license_key_configuration to a digital variant | 1. Turn on license keys |
| Sell it | Hosted checkout, a payment link, or your own checkout | 2. Sell the product |
| Deliver the key | Flint emails it, or you show it | 3. Deliver the key |
| Check it from your app | Activate once, validate at launch | 4. Check keys from your app |
| Handle support | Disable, reinstate, reveal, replace, resend | 6. Manage a key |
Before you start#
You need a sandbox API key with these scopes:
commerce.products.writeto add the setting,commerce.orders.writeto create orders, andcheckouts.checkout_sessions.writeorcheckouts.payment_links.writefor the way you sell.commerce.license_keys.readto list and look up keys, andcommerce.license_keys.writeto disable, reinstate, resend, and manage pools.commerce.license_keys.secrets.writeto reveal or replace a full key.
Your shipped app needs no key. It sends the license key and your product IDs, and nothing it holds can read your account.
1. Turn on license keys#
Set license_key_configuration on the variant of a digital product. This product issues generated keys that start with LUMEN and work on up to three devices:
curl -X POST https://api.withflintpay.com/v1/products \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: product-lumen-pro" \
-H "Content-Type: application/json" \
-d '{
"variant_mode": "simple",
"name": "Lumen Pro",
"product_type": "digital",
"default_variant": {
"sku": "LUMEN-PRO",
"unit_price_money": { "amount": 4900, "currency": "USD" },
"license_key_configuration": {
"source": "generated",
"key_prefix": "LUMEN",
"activation_limit": 3,
"validity_period_days": null
}
}
}'
Keys look like LUMEN-7K2QX-9RMDT-4W8PC-6HNZB-E3VYJ. Omit activation_limit for unlimited devices, or set validity_period_days for keys that expire. To add the setting to a variant you already sell, send it on the variant update. The setting is replaced as a whole, so send every field you want to keep. License key setting lists every field and limit.
To sell keys you already hold, such as keys for a game store, use source: "pool" instead. Sell keys from a pool covers it.
2. Sell the product#
Sell the variant like any other catalog product: on an order with a checkout session, on a payment link, or in your own checkout. There's nothing to add for keys. Each unit gets its own key, so a buyer who orders three copies gets three keys.
Each order line reports license_key_quantity, the number of keys it will receive. Keys are issued just after payment, normally within a few seconds, so order.paid can arrive before they exist. To show keys on your own confirmation page, wait for license_key.created, or list the order's keys until the count matches:
curl "https://api.withflintpay.com/v1/license-keys?order_id=ord_1kmn0aExample" \
-H "Authorization: Bearer YOUR_API_KEY"
Merchant reads show key_last4, never the full key. A headless checkout can make the same request with its checkout credential after payment, and the response includes each full key for the buyer to copy.
Subscription plans can sell variants with generated keys. A subscription's keys are issued when it becomes trialing or active and follow the subscription afterward, as When access ends describes.
3. Deliver the key#
By default Flint emails keys to the order's buyer email:
- The receipt email lists each key on the order, up to 25, with a note to keep it private.
- A license key email carries any key issued after the receipt went out, such as a subscription key issued later or a pool key that was waiting for stock, and every resend.
Full keys go only to the order's buyer email when no one else is copied. Any other recipient sees the last four characters.
Hosted checkout and the customer account show keys too, each with a copy button and its status:
- Checkout confirmation. After payment, the page lists the order's keys. Keys are issued a few seconds after payment, so the page checks every 2 seconds for up to 30 seconds, then says the rest will arrive by email. A pool key waiting for stock shows as pending. When the order has keys, the page keeps the buyer there, even when the checkout session has a
redirects.success_url, with a button that continues to that URL, not a countdown. - Order page. The customer account's order page lists the order's keys. A disabled key stays listed and says that it no longer works.
- License keys page. The customer account lists every key the buyer has, with the devices each is active on. Buyers can deactivate a device and resend a key email there.
The confirmation page shows full keys to the buyer who just paid. The customer account shows full keys when Flint verified the buyer's email, or when the buyer opened the order from the paying checkout or a link emailed to them. Otherwise both show the last four characters.
To send your own emails, set email_delivery_enabled: false on the setting. Flint then sends neither email, and you read each key with reveal and deliver it yourself.
In a customer account you build, a customer session lists the buyer's keys with GET /v1/me/license-keys, their devices with GET /v1/me/license-key-activations, and can release a device or resend a key email. List the buyer's keys covers when the full key is shown.
4. Check keys from your app#
Your shipped app makes three calls, all without an Authorization header:
| When | Call |
|---|---|
| The buyer enters a key | POST /v1/license-key-activations |
| Each launch | POST /v1/license-keys/validate |
| The buyer signs out a device | POST /v1/license-key-activations/{license_key_activation_id}/release |
Every call sends product_ids: every product your app accepts a key for. Compile the list into the app. If you sell the same app as several products, such as Standard and Pro, or yearly and lifetime, list all of them, up to 20. The response's product_id and variant_id tell you which one the key is for. A key for one of your other products doesn't work in an app that doesn't list it.
Use your sandbox product IDs in test builds: the first ID tells Flint which account and environment to look in.
Activate the device#
When the buyer enters a key, activate it with a name they'll recognize and a fingerprint that identifies this installation, such as a hash of the machine ID:
curl -X POST https://api.withflintpay.com/v1/license-key-activations \
-H "Idempotency-Key: 3f6c1a52-activate" \
-H "Content-Type: application/json" \
-d '{
"product_ids": ["prod_1kmn0aExample"],
"key": "LUMEN-7K2QX-9RMDT-4W8PC-6HNZB-E3VYJ",
"name": "Studio MacBook Pro",
"fingerprint": "9f2c6f0e7d1b4a53"
}'
A new device returns 201 with the activation. If an active activation on this key already has the same fingerprint, Flint returns it with 200, so reinstalling on the same machine doesn't use another slot. Store license_key_activation_id with the key.
| Response | What to tell the buyer |
|---|---|
404 RESOURCE_NOT_FOUND at key | The key isn't valid for this app. Check it was typed correctly. |
409 ACTION_NOT_ALLOWED, reason unsupported_state | The key is disabled or expired. |
409 LIMIT_REACHED, reason license_key_activations | Every device slot is in use. Sign out another device first. |
Validate at launch#
Send the key and the stored activation ID:
curl -X POST https://api.withflintpay.com/v1/license-keys/validate \
-H "Content-Type: application/json" \
-d '{
"product_ids": ["prod_1kmn0aExample"],
"key": "LUMEN-7K2QX-9RMDT-4W8PC-6HNZB-E3VYJ",
"license_key_activation_id": "lka_1kmn0aExample"
}'
A completed check returns 200 whether or not the key works. Read data.is_valid, and when it's false, data.invalid_reason:
invalid_reason | Meaning |
|---|---|
not_found | No key matches for these products. |
disabled | A refund, dispute, subscription change, or you turned it off. |
expired | The key's expires_at has passed. |
activation_not_found | This device was signed out, from your app, by the buyer, by you, or by a key replacement. Activate again. |
not_found is one answer for a mistyped key, another merchant's key, a key for a product you didn't list, and a sandbox key checked against live products. The response says nothing more, so nobody can probe for real keys.
Keep working when Flint can't answer#
Treat 429, 5xx, and network errors as "couldn't check", not as an invalid key. Keep the last answer and when you got it, and let the app run on it for a grace period you choose, such as a week. Never lock out a paying buyer because the check didn't complete. On 429, wait the seconds in Retry-After.
const VALIDATE_URL = "https://api.withflintpay.com/v1/license-keys/validate";
const PRODUCT_IDS = ["prod_1kmn0aExample"];
const GRACE_MS = 7 * 24 * 60 * 60 * 1000;
type Stored = { key: string; activationId: string; lastValid: boolean; checkedAt: number };
const lastAnswer = (stored: Stored) => ({
allowed: stored.lastValid && Date.now() - stored.checkedAt < GRACE_MS,
stored,
});
export async function checkLicense(stored: Stored): Promise<{ allowed: boolean; stored: Stored }> {
let response: Response;
try {
response = await fetch(VALIDATE_URL, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
product_ids: PRODUCT_IDS,
key: stored.key,
license_key_activation_id: stored.activationId,
}),
});
} catch {
return lastAnswer(stored); // Offline or unreachable.
}
if (response.ok) {
const { data } = await response.json();
const next = { ...stored, lastValid: data.is_valid === true, checkedAt: Date.now() };
return { allowed: next.lastValid, stored: next };
}
if (response.status === 429 || response.status >= 500) return lastAnswer(stored);
// Any other status means the request is wrong. Report it instead of hiding it.
throw new Error(`License check failed with HTTP ${response.status}`);
}
A 4xx other than 429 means the request itself is wrong, such as a malformed product ID. Fix the request in the build. If the app sends a well-formed product ID that Flint can't use for validation, it receives the same not_found result as a mistyped key.
Flint allows 120 validations a minute per key. For requests without a merchant credential, Flint allows 120 validations a minute per IP address and a combined 20 activation and release requests a minute per IP address. Those requests share a limit of 10 credential misses per 10 minutes per IP address across all three operations. Each key accepts a limited number of new activations an hour. One request counts once however many products it lists, so an app that lists every product it's sold as doesn't fail on a valid key. Validate a license key has every limit.
Release a device#
To free a slot from the app, send the activation's key and your product IDs:
curl -X POST https://api.withflintpay.com/v1/license-key-activations/lka_1kmn0aExample/release \
-H "Content-Type: application/json" \
-d '{
"product_ids": ["prod_1kmn0aExample"],
"key": "LUMEN-7K2QX-9RMDT-4W8PC-6HNZB-E3VYJ"
}'
Your server can release any activation with an empty body and an API key with commerce.license_keys.write. To find it, list a key's devices with GET /v1/license-key-activations?license_key_id=lk_1kmn0aExample.
5. When access ends#
Flint disables keys when the sale is reversed. A disabled key still exists: its devices stay activated, validate answers disabled, and access returns if the key is reinstated.
- Refunds. A refund that returns units of a line disables that many of the line's keys. Flint picks keys still waiting for stock first, then keys you already disabled, then keys with no active device, then the highest-numbered. To choose which keys go, disable them before you refund. A refund that returns no units disables nothing unless it fully refunds the order, which disables every key. If the refund fails, its keys come back.
- Disputes. A chargeback on the order disables all its keys while it's open. Winning reinstates them, losing keeps them disabled. An inquiry changes nothing.
- Subscriptions. Keys stay on through
past_dueand are disabled while the subscription ispausedand once it'scanceled. Lowering a line's quantity disables the highest-numbered keys. A refund of one period's order doesn't touch the keys, so cancel the subscription to end access. - Expiry. A key with
expires_atreads asexpiredfrom that moment.
Flint only controls its own answer. Disabling a third-party key from a pool, such as a Steam key, changes what validate returns, not whether that store still accepts it.
6. Manage a key#
Find a key by order, customer, buyer email, or status with GET /v1/license-keys, or by the key a buyer gives you with POST /v1/license-keys/lookup. Send expected_version on a change to refuse it if the key changed since you read it (versions and write fences).
Disable and reinstate#
curl -X POST https://api.withflintpay.com/v1/license-keys/lk_1kmn0aExample/disable \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "reason": "suspected_abuse" }'
reinstate lifts every restriction in force, including one from a refund, dispute, or subscription. A new cause, such as another refund, can disable the key again. The key's restrictions list shows what's keeping it disabled.
curl -X POST https://api.withflintpay.com/v1/license-keys/lk_1kmn0aExample/reinstate \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
Reveal a key#
reveal returns the full key in key and records who read it. Use it to show a key on your own pages or to send it yourself.
curl -X POST https://api.withflintpay.com/v1/license-keys/lk_1kmn0aExample/reveal \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
Replace a leaked key#
rotate-key gives a generated key a new value, signs out every device, and returns the new value in key. The old value stops working, the buyer keeps the license, and Flint sends no email, so deliver the new key yourself or resend it.
curl -X POST https://api.withflintpay.com/v1/license-keys/lk_1kmn0aExample/rotate-key \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
Resend the email#
resend queues another license key email to the buyer email on file, once per key every 60 seconds. It refuses a disabled key, a key still waiting for stock, and a key with email delivery turned off.
curl -X POST https://api.withflintpay.com/v1/license-keys/lk_1kmn0aExample/resend \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
PATCH /v1/license-keys/{license_key_id} changes one key's activation_limit, expires_at, or metadata, such as extra seats for one customer.
7. Sell keys from a pool#
A pool holds keys you upload, and its unsold keys are the variant's stock. Create a pool:
curl -X POST https://api.withflintpay.com/v1/license-key-pools \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: pool-lumen-steam" \
-H "Content-Type: application/json" \
-d '{ "name": "Lumen Steam keys", "low_stock_threshold": 50 }'
Upload keys in batches of up to 1,000. seller_authorization_confirmed: true confirms that the rights holder lets you sell them. Flint records who confirmed it, when, and how many keys were sent.
curl -X POST https://api.withflintpay.com/v1/license-key-pools/lkp_1kmn0aExample/keys \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: pool-lumen-steam-batch-1" \
-H "Content-Type: application/json" \
-d '{
"seller_authorization_confirmed": true,
"keys": ["AAAAA-BBBBB-CCCCC", "DDDDD-EEEEE-FFFFF"]
}'
Each key is 8 to 255 printable characters. A key already in one of your pools comes back as existing, so a retried batch doesn't add duplicates. Then point a one-time digital variant at the pool with "source": "pool" and "license_key_pool_id". Pool variants can't be sold on subscription plans.
- Stock. Flint checks stock when units are added to an order or checkout starts, and reserves one key per unit when payment starts. Short stock returns
409 INVENTORY_INSUFFICIENT. An abandoned or failed payment puts its keys back. - Pending keys. An order paid without a reservation can get a
pendingkey if the pool is empty. Your next upload fills pending keys oldest first, and Flint emails each one. - Low stock. Flint sends
license_key_pool.low_stockwhen stock falls tolow_stock_thresholdandlicense_key_pool.out_of_stockat zero. - Refunds. A refunded pool key is disabled and never sold again.
Pool keys don't answer requests without a credential until you turn on public_validation_enabled on the pool. That needs every key in the pool to be at least 16 characters. Leave it off for keys your app never checks, such as keys for another store; your server can still check them with an API key.
Events to handle#
Payloads carry the masked key, never the full value.
Test it#
Run the whole flow in your sandbox. No account yet? Sign up and you get one.
- Create the product with your test key and pay for it with a test card. Sandbox generated keys start with
TEST-, such asTEST-LUMEN-7K2QX-9RMDT-4W8PC-6HNZB-E3VYJ, and only validate against sandbox product IDs. - Activate the key from a test build that lists your sandbox product ID, then validate it.
- Refund the order and check that
validateanswersdisabled. - Pay a new order with the dispute test card in Simulate a dispute outcome, check the key is disabled, then simulate a
wonruling and check it's active again.
Going further#
License keysSell with hosted checkoutPayment linksSubscription billingReady to sell your app? Create a Flint account and issue your first test key.