Skip to content

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.

StepWhat you doSection
Set up the productAdd license_key_configuration to a digital variant1. Turn on license keys
Sell itHosted checkout, a payment link, or your own checkout2. Sell the product
Deliver the keyFlint emails it, or you show it3. Deliver the key
Check it from your appActivate once, validate at launch4. Check keys from your app
Handle supportDisable, reinstate, reveal, replace, resend6. Manage a key

Before you start#

You need a sandbox API key with these scopes:

  • commerce.products.write to add the setting, commerce.orders.write to create orders, and checkouts.checkout_sessions.write or checkouts.payment_links.write for the way you sell.
  • commerce.license_keys.read to list and look up keys, and commerce.license_keys.write to disable, reinstate, resend, and manage pools.
  • commerce.license_keys.secrets.write to 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
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
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:

WhenCall
The buyer enters a keyPOST /v1/license-key-activations
Each launchPOST /v1/license-keys/validate
The buyer signs out a devicePOST /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
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.

ResponseWhat to tell the buyer
404 RESOURCE_NOT_FOUND at keyThe key isn't valid for this app. Check it was typed correctly.
409 ACTION_NOT_ALLOWED, reason unsupported_stateThe key is disabled or expired.
409 LIMIT_REACHED, reason license_key_activationsEvery device slot is in use. Sign out another device first.

Validate at launch#

Send the key and the stored activation ID:

cURL
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_reasonMeaning
not_foundNo key matches for these products.
disabledA refund, dispute, subscription change, or you turned it off.
expiredThe key's expires_at has passed.
activation_not_foundThis 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.

TypeScript
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
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_due and are disabled while the subscription is paused and once it's canceled. 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_at reads as expired from 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
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
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
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
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
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
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
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 pending key 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_stock when stock falls to low_stock_threshold and license_key_pool.out_of_stock at 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.

  1. Create the product with your test key and pay for it with a test card. Sandbox generated keys start with TEST-, such as TEST-LUMEN-7K2QX-9RMDT-4W8PC-6HNZB-E3VYJ, and only validate against sandbox product IDs.
  2. Activate the key from a test build that lists your sandbox product ID, then validate it.
  3. Refund the order and check that validate answers disabled.
  4. Pay a new order with the dispute test card in Simulate a dispute outcome, check the key is disabled, then simulate a won ruling and check it's active again.

Going further#

License keysEvery route, limit, error, and event for keys, devices, and pools.Sell with hosted checkoutOrders, checkout sessions, and order.paid for a one-time sale.Payment linksOne URL for every buyer.Subscription billingPlans, trials, pauses, and cancellations.

Ready to sell your app? Create a Flint account and issue your first test key.

Was this helpful?