License keys
A license key unlocks software a buyer paid for. Add a license key setting to a digital variant, and Flint issues one key for each paid unit, emails it to the buyer, answers your shipped app's checks without a credential, and disables the key when the sale is reversed. Keys are generated by Flint or drawn from a pool of keys you upload. Sell software license keys walks through the whole flow.
Issuance happens just after payment, so a paid order can briefly return an empty list while its keys are being issued.
Variant setting#
Set license_key_configuration on a digital variant through product create, variant create, or variant update. Variant reads return the setting, or null when none is set.
{
"license_key_configuration": {
"source": "generated",
"activation_limit": 3,
"validity_period_days": null,
"key_prefix": "LUMEN",
"email_delivery_enabled": true
}
}
Choose source: generated to have Flint generate keys. You can set key_prefix to 2 to 8 uppercase letters or digits. Choose source: pool to sell uploaded keys. Send the license_key_pool_id of an active pool in the same merchant and environment, and omit key_prefix.
Set activation_limit to 1 through 10,000, or omit it or send null for unlimited activations. Set validity_period_days to 1 through 36,500, or omit it or send null for no expiry. email_delivery_enabled defaults to true.
The setting is replaced as a whole: send every field you want to keep. Omit it on update to preserve it, or send null to remove it. Send expected_version to reject a concurrent variant change.
The setting requires product_type: digital, cannot be used in bundles, and adds no delivery requirement. Pool-backed variants are for one-time purchases and cannot use an inventory item. Subscription plans can use generated settings.
Order lines#
Order lines copy the variant's setting when they are created. Later catalog changes apply only to new lines.
Each line returns the read-only integer license_key_quantity: its quantity when it carries a license key setting, or 0 otherwise. The count includes keys for a subscription started by the line; renewal lines return 0. Refunds do not reduce it. Keys arrive after payment, so order.paid may arrive before the keys exist.
Paid-order edits cannot add a variant with a license key setting or remove units from a line with a positive license_key_quantity. Both return 400 INVALID_REQUEST, detail NOT_ALLOWED, at the entry in add_line_items or remove_line_items.
List and read keys#
Use GET /v1/license-keys to find keys and GET /v1/license-keys/{license_key_id} to read one. Both require commerce.license_keys.read for merchant credentials. These reads show key_last4 when a key is assigned. They include the effective status, restrictions in force, the activation limit and count, and the expiry time. A key belongs to one order or subscription line. Its unit_ordinal starts at 1. restrictions lists the merchant decisions, refunds, disputes, or subscription changes currently keeping a key disabled. An order or subscription can gain a customer without changing the license key's version.
The list sorts by created_at descending, then license_key_id descending. Use page_size from 1 to 100, with a default of 20. Pass next_page_token back as page_token with the same filters to continue.
- Filter by exact
order_id,customer_id,subscription_id,product_id,variant_id, orlicense_key_pool_id. An order filter also finds keys for subscriptions started by that order. The customer comes from the owning order or subscription. - Filter by
emailusing one bare address. It matches the buyer email on the order or the owning customer's email, ignoring case and any surrounding whitespace stored on the address. - Repeat
statusor send comma-separated values to match any ofpending,active,disabled, orexpired. An active key whose expiry time has passed matchesexpired. - Use
created_afterto include keys created at or after a timestamp andcreated_beforeto exclude keys created at or after it.
List and get support expand=order with commerce.orders.read and expand=customer with customers.read. If the requested relationship is absent, the expansion is null.
Look up a full key#
Send {"key": "..."} in the body of POST /v1/license-keys/lookup with commerce.license_keys.read. The response contains the masked key details regardless of status. Generated keys ignore case, spaces, and hyphens, read O as 0 and I or L as 1, and match on the last 25 characters. Pool keys match the exact characters after trimming surrounding whitespace.
A malformed key returns 400 INVALID_REQUEST with detail code INVALID_VALUE. A key outside your merchant or environment, or a value that matches no key, returns 404 RESOURCE_NOT_FOUND. Both identify key as the parameter.
Read a buyer's keys at checkout#
Call GET /v1/license-keys?order_id=... with the paying checkout credential and its own paid order's ID. A missing or different order_id returns 403 FORBIDDEN. Only pagination parameters can accompany order_id. Flint includes each assigned full key in key for the buyer. A checkout credential from a launch URL you read as the merchant or request after payment receives masked results.
Update a key#
Use PATCH /v1/license-keys/{license_key_id} with commerce.license_keys.write to change the activation limit, expiry, or metadata. Send only the fields you want to change. For example, send {"activation_limit": 5, "expires_at": null, "expected_version": 3} to set a limit and clear expiry. Send activation_limit: null for unlimited installations. Lowering a limit leaves existing installations active. You can set an expiry only for an assigned order key. Metadata merges by key. Send a null value to remove one entry or metadata: null to clear the map.
Why a key is disabled#
A key is disabled while any restriction is in force. restrictions lists each one with its type:
type | Added when | Ends when |
|---|---|---|
merchant | You call disable. | You call reinstate. |
refund | A refund returns units of the key's line, or fully refunds the order. Carries refund_id. | The refund fails or is canceled. |
dispute | A chargeback on the order opens or is lost. Carries dispute_id and dispute_status open or lost. Inquiries add nothing. | The dispute is won or prevented. |
subscription | The subscription is paused or canceled, or the key's unit leaves it through a quantity or plan change. reason is paused, canceled, or removed. | The subscription resumes or the unit returns. A cancellation never ends. |
A refund that returns units disables that many of the line's keys. Flint picks keys waiting for pool stock first, then keys under a merchant restriction, then keys with no active activation, then the highest unit_ordinal. Disable specific keys before refunding to choose them yourself. A refund that returns no units changes nothing unless it fully refunds the order, which restricts every remaining key.
A subscription key follows its subscription. It stays active through past_due, and refunds of the subscription's orders don't restrict it. A chargeback on any of its orders does. Disabling a key keeps its activations, so reinstating it restores access on those devices.
Disable or reinstate a key#
Use POST /v1/license-keys/{license_key_id}/disable to add a merchant restriction. For example, send {"reason":"suspected_abuse","expected_version":3}. Other reasons are customer_request and other. The default is other. A key already under a merchant restriction returns 409 ACTION_NOT_ALLOWED with reason already_applied.
Use POST /v1/license-keys/{license_key_id}/reinstate to lift every restriction currently in force. For example, send {"expected_version":4}. This overrides the current causes until they end. A new cause can disable the key again. Reinstating a key with no restrictions returns reason already_applied.
Both actions require commerce.license_keys.write. Read supported_actions to see which actions the resource currently offers. A restriction takes precedence over expiry and key assignment when determining status. On updates, disable, reinstate, and rotation, an optional expected_version rejects stale writes with 409 VERSION_CONFLICT.
Reveal a key#
Use POST /v1/license-keys/{license_key_id}/reveal with commerce.license_keys.secrets.write to read the full key for display. For example, send {} to the route for the key you want to show. Flint audits the reveal. A key waiting for assignment returns 409 ACTION_NOT_ALLOWED with reason status_not_reached. A retry with the same Idempotency-Key from the same credential can return the revealed value again, as Responses with one-time secrets describes.
Rotate a generated key#
Use POST /v1/license-keys/{license_key_id}/rotate-key with commerce.license_keys.secrets.write. For example, send {"expected_version":5}. Rotation invalidates the old string, releases all active installations, and returns the replacement in key. Deliver the new value to the buyer before they activate again. Rotation sends no email. A retry with the same Idempotency-Key from the same credential returns the new value while the key's version is unchanged; a retry from another credential never includes it (Responses with one-time secrets). Pool keys return 409 ACTION_NOT_ALLOWED with reason not_offered.
Resend a key#
Send an empty body or {} to POST /v1/license-keys/{license_key_id}/resend with commerce.license_keys.write. Flint queues an email to the buyer address on file and returns the unchanged license key resource. To use a different address, update the customer's email or reveal the key and deliver it yourself.
Flint accepts one resend per key every 60 seconds. A sooner request returns 429 RATE_LIMIT_EXCEEDED with the remaining wait in Retry-After. 409 ACTION_NOT_ALLOWED reports why a resend couldn't be queued.
| Reason | When it applies |
|---|---|
status_not_reached | The key is waiting for assignment. |
unsupported_state | The key is disabled. |
configuration_required | The buyer has no email address on file. |
not_offered | Email delivery was turned off for the key. |
Validate a license key#
Call POST /v1/license-keys/validate when your app needs to check a key. Send the full key in the JSON body and list 1 to 20 distinct products your app accepts.
{
"product_ids": ["prod_01M8E2A1B2C3D4E5F6G7H8J9KM"],
"key": "LUMEN-7K2QX-9RMDT-4W8PC-6HNZB-E3VYJ"
}
Omit Authorization in an installed app. The first product ID selects the merchant and mode. Use sandbox product IDs when checking a test purchase. Generated sandbox keys display a TEST- prefix. Generated keys match on the last 25 normalized characters. Pool keys match the exact characters after trimming surrounding whitespace and require the pool's public validation setting for credential-free requests.
A merchant backend can send an API key with commerce.license_keys.read. Every listed product must belong to the credential's merchant and environment, or, without a credential, to the first product's merchant and environment. With an API key, an unavailable product returns 404 RESOURCE_NOT_FOUND at product_ids[i]. Without an API key, missing products, products outside the selected merchant or environment, and keys that do not match all return 200 with is_valid: false and invalid_reason: not_found.
The check returns 200 with data.is_valid. A matched key includes its status, product, variant, expiry, activation limit, and active activation count. If you supply license_key_activation_id, the check also requires that activation to be active on this key. A valid result includes the full activation and records last_validated_at at most once an hour. An invalid result has an invalid_reason. A not_found result includes only is_valid and invalid_reason in data.
Flint allows 120 validations per key per minute. Without an API key, Flint also allows 120 requests per minute per IP address. Validation, activation, and release share a limit of 10 credential misses per 10 minutes per IP address. Each request counts once, regardless of the number of products it lists. On 429 RATE_LIMIT_EXCEEDED, keep the last validation result and retry after the number of seconds in Retry-After. Treat 5xx and network errors the same way, and never lock out a paying buyer because a check didn't complete. Keep working when Flint can't answer shows an app that does this.
Activate a device#
Call POST /v1/license-key-activations with the full key, the application's product_ids, and a device name of 1 to 255 characters. You can also send a fingerprint of 1 to 255 characters, such as a hashed machine ID. Flint returns 201 for a new activation. When that key already has an active activation with the same fingerprint, Flint returns it with 200 and uses the same slot. Store the returned license_key_activation_id with the key and send it when validating that installation.
The product and pool rules for validation also apply here. For an app using a license key, missing products, out-of-scope products, and unmatched keys all return 404 RESOURCE_NOT_FOUND at key. A disabled or expired key returns 409 ACTION_NOT_ALLOWED with reason unsupported_state. When all slots are in use, Flint returns 409 LIMIT_REACHED with reason license_key_activations and the key's limit.
A merchant backend can activate a device with an API key that has commerce.license_keys.write. Without a merchant credential, activate and release share 20 requests per minute per IP address and use the same credential miss limit as validation. New activations also have an hourly budget per key. The budget equals its activation limit with a minimum of 20, or 1,000 for an unlimited key. On 429, retry after the number of seconds in Retry-After.
Release a device#
Call POST /v1/license-key-activations/{license_key_activation_id}/release to free its slot. An installed app sends the activation's own full key and its product_ids. A merchant can send an empty body with an API key that has commerce.license_keys.write. If the merchant also sends key, it must match the activation's key.
A request without a merchant credential or both proof fields returns 401 AUTHENTICATION_REQUIRED. An unknown activation or one belonging to a different key returns 404 RESOURCE_NOT_FOUND at license_key_activation_id. When an app authenticates with a license key, a missing product, out-of-scope product, or unmatched key also returns 404 RESOURCE_NOT_FOUND at license_key_activation_id. Releasing a released activation returns 409 ACTION_NOT_ALLOWED with reason already_applied.
Activate and release accept an optional Idempotency-Key. Both send Cache-Control: no-store. Flint sends Flint-Mode when it identifies the credential's mode.
List and read device activations#
Use GET /v1/license-key-activations?license_key_id=... to list activations, newest first. Use status=active,released to select both statuses explicitly or one value to filter. Pass the returned next_page_token as page_token to continue. Read one activation with GET /v1/license-key-activations/{license_key_activation_id}. Both reads require commerce.license_keys.read.
Subscribe to license_key_activation.created and license_key_activation.released to track device access. Rotating a key releases every active device and emits the release event for each one. Disabling a key keeps its activations in place, so reinstating it restores access for those devices.
List the buyer's keys#
Use GET /v1/me/license-keys with a customer session to show a buyer the keys they purchased. Filter by exact order_id or subscription_id, or by status. An order filter includes keys from the subscription the order started. Disabled keys remain listed. Results sort newest first by created_at and then by license_key_id. Use page_size and page_token to continue with the same filters.
When Flint verified the buyer's sign-in email, key contains the full assigned key if the email matches the order's buyer email, or the subscription customer's email for a subscription without a starting order. A paying checkout's order link or an uncopied link emailed to the order's buyer can show the full assigned key for that order. Merchant-created sessions and links show key_last4 when assigned. This applies to disabled keys too.
An order or subscription link can list keys only for the resource it opens. A customer session with explicit capabilities needs license_keys.read.
Manage the buyer's devices#
Use GET /v1/me/license-key-activations?license_key_id=... to show the devices for a key the buyer can access. Filter by status to show only active or released devices. Device fingerprints are private.
Send an empty body or {} to POST /v1/me/license-key-activations/{license_key_activation_id}/release to deactivate a device and free its slot. The response contains the released activation. A repeat release returns 409 ACTION_NOT_ALLOWED with reason already_applied. A release emits license_key_activation.released.
Resend the buyer's key email#
Send an empty body or {} to POST /v1/me/license-keys/{license_key_id}/resend to queue another email to the order's buyer email, or the subscription customer when it has no starting order. The response shows the key's last four characters when assigned. Pending and disabled keys cannot be resent. Email delivery must be enabled and an address must be on file. Resend shares the merchant route's 60-second cooldown and returns 429 with Retry-After during that wait.
Both actions require a full customer session. When the session has explicit capabilities, it needs license_keys.manage. The list responses expose the available actions as buyer_actions, with kind release on devices or resend on keys. An order or subscription link can list these resources. The buyer must sign in to take either action.
License key pools#
Create an empty pool with POST /v1/license-key-pools and a name. Use GET /v1/license-key-pools to list pools, newest first, or GET /v1/license-key-pools/{license_key_pool_id} to read one. The pool reports quantities for available, held, issued, removed, and pending keys. Include archived in the status filter to list archived pools. Use PATCH on the pool to edit its name, metadata, low-stock threshold, or public validation setting. An empty JSON object returns the current pool. Send low_stock_threshold: null to clear the threshold. Send expected_version to refuse an update if the pool has changed since you read it.
Public validation is off by default. Enable it only when your app needs to check keys without a credential. Every key still in the pool must contain at least 16 characters. Length alone does not make a key hard to guess. Use keys that are hard to predict before you enable public validation.
Sell keys from a pool#
Set license_key_configuration on a digital variant with source: pool and the pool’s ID. Flint checks stock when you add units to an order or start checkout. It reserves one key per unit before payment. If there are too few keys, the request returns 409 INVENTORY_INSUFFICIENT. Failed or abandoned payment attempts release their reservations. Refunded keys stay issued and cannot be sold again.
An order paid without a reservation can receive a pending license key if the pool is empty. The next upload fills pending keys oldest first, then makes any remaining keys available for sale. A filled key’s validity period starts when Flint assigns it.
Flint sends license_key_pool.low_stock when stock falls from above the threshold to at or below it, and license_key_pool.out_of_stock when stock reaches zero. Replenishment allows the corresponding notification to fire again. Sales change the quantities without advancing the pool’s version.
Upload and list pool keys#
Send up to 1,000 keys in a batch to POST /v1/license-key-pools/{license_key_pool_id}/keys with seller_authorization_confirmed: true. This confirms that the rights holder authorizes you to sell the keys. Flint records who confirmed, when, and how many keys they submitted. The pool's resource timeline shows the confirmation in its license_key_pool_attestations array.
Each key must contain 8 to 255 printable ASCII characters and have no leading or trailing spaces. The minimum is 16 characters with public validation enabled. Flint accepts upload and removal request bodies up to 2 MiB. Keys are case-sensitive. An invalid key or a repeated value in the same batch rejects the entire upload. A key already available, held, or issued in any of your pools in this environment returns existing. Upload results are in request order. A batch that adds any keys returns HTTP 201. A batch whose keys all exist returns HTTP 200. You can upload a key again after you remove it.
GET /v1/license-key-pools/{license_key_pool_id}/keys lists keys in upload order. Use status to filter by available, held, issued, or removed. To include multiple statuses, send a comma-separated list. Upload, list, and removal responses show only the last four characters of each key.
Remove keys and archive pools#
Send a batch of full key values in keys or pool key IDs in license_key_pool_key_ids to POST /v1/license-key-pools/{license_key_pool_id}/keys/remove. Flint reports one outcome per selector in request order. removed means the key was available and Flint removed it. held means a payment is in progress and you can try again later. issued includes the assigned license ID. not_found means no current key in this pool matched.
DELETE /v1/license-key-pools/{license_key_pool_id} archives a pool, which remains readable. If it still has available keys, pass remove_available_keys=true to remove them as part of the archive. A pool in use by a variant, with held or pending keys, or with an order still eligible to receive keys from the pool cannot be archived. Archiving preserves issued keys.
Pool reads require commerce.license_keys.read. Pool writes require commerce.license_keys.write and accept an optional Idempotency-Key.
Read a key's history#
Use GET /v1/resource-timelines/{resource_id} with a license key ID (lk_…) or a device activation ID (lka_…). Both require developer.resource_timelines.read and commerce.license_keys.read.
For a key, data.entries includes webhook summaries for issuance and key changes, and request summaries for reveal, rotation, and resend. Read the request entry's path, status_code, and caller to identify the action, whether it succeeded, and who called it. The usual request log visibility rules apply. The timeline returns summaries without the full key or device fingerprint.
The key's timeline also includes its devices' license_key_activation.created and license_key_activation.released events. These also appear on the activation's own timeline. The event's attributed_resource.resource_id identifies the activation.
Read data.license_key_restriction_changes to see each restriction take effect or end. An entry has an action of added or lifted and a type of merchant, refund, dispute, or subscription. System causes include the matching refund_id, dispute_id, or subscription_id. A restriction can be lifted while another cause still disables the key. To see only restriction changes, pass include=license_key_restriction_changes. Follow next_page_token across both collections.
Request, webhook event, and delivery attempt summaries are kept for 90 days. Restriction changes remain available with the key's record.
Events#
Subscribe to license_key.created to know when a key is issued, then license_key.disabled when the first restriction takes effect, license_key.expired when Flint records a passed expiry, and license_key.updated for other changes such as a reinstatement, rotation, or terms update. Expiry takes effect at expires_at, and the event normally follows within five minutes. Read data.object.status on each event to track access. Every license key payload contains the same masked fields as the merchant get response.
license_key_activation.created and license_key_activation.released track devices. The pool events are license_key_pool.created, license_key_pool.updated, license_key_pool.archived, license_key_pool.low_stock, and license_key_pool.out_of_stock.
The License key object#
A license key issued to a buyer, with its display suffix.
Returned by GET /v1/license-keys/{license_key_id} and carried by the endpoints below.
Attributes
activation_limitinteger or nullRequiredMaximum active installations. Null when activations are unlimited.
active_activation_countintegerRequiredNumber of currently active installations.
created_atstringRequiredWhen the license key was issued.
customerobject or nullThe linked customer. Present only when `expand` includes `customer`; `null` when expanded and there is no related customer.
created_atstringRFC3339 timestamp.
customer_idstringRequiredUnique identifier for this customer, prefixed `cus_`.
emailstring or nullRequiredCustomer email. `null` when the customer has none. Unique among the environment's customers.
namestring or nullRequiredCustomer name. `null` when none is set.
phonestring or nullRequiredCustomer phone number. `null` when none is set.
statusenumRequiredWhere the customer is in the deletion lifecycle.
activedeletion_processingdeleted
updated_atstringRFC3339 timestamp.
customer_idstring or nullRequiredThe current customer of the owning order or subscription. Null when the order has no linked customer.
expires_atstring or nullRequiredWhen the key expires. Null when no expiry is set.
key_last4string or nullRequiredLast four characters of the assigned key. Null when the key is awaiting assignment.
license_key_idstringRequiredUnique license key ID with the lk_ prefix.
license_key_pool_idstring or nullRequiredThe source pool ID. Null when the key is generated.
metadatamap of stringRequiredMerchant-defined key-value pairs.
orderobject or nullThe linked order. Present only when `expand` includes `order`; `null` when expanded and there is no related order.
buyer_contactobjectBuyer contact recorded on the order, including guest contact when retained. Omitted when the order has no recorded contact.
Not returned with a checkout credential or a customer session
closed_atstringWhen the order closed. Present exactly when status is closed. Set once at the transition and never changed.
closed_reasonenumWhy the order closed. Present exactly when status is closed. Set once at closure. Unrecognized reasons are returned as other; new values may be added.
invoice_voidedpaidclosed_by_merchantcheckout_expiredwritten_offsupersededreturn_resolution_canceledother
created_atstringWhen the order was created, in RFC3339 format.
customer_idstringCustomer associated with the order, when one is set.
deferred_promotionsarray of objectRequiredPromotions accepted at subscription signup. They attach when the subscription is provisioned and first discount its first charged cycle. They do not discount this order and are separate from discounts and order totals. Always present; empty when no promotions are deferred.
fulfillment_statusenumAggregate progress across the order's fulfillment quantities.
not_fulfilledpartially_fulfilledfulfilledcancelednot_applicableclosed
governing_delivery_selection_idstring or nullRequiredID of the delivery selection that governs this order. Null when no selection governs the order.
order_idstringRequiredStable identifier of the expanded order.
order_numberstringHuman-readable order number for receipts and merchant reference.
paid_atstring or nullRequiredWhen `payment_status` became `paid`, including a final capture that releases the remaining balance. Set once and never changed, including after refunds. `null` when `payment_status` isn't `paid`, including an order whose balance was written off without being paid.
payment_intent_idsarray of stringPayment intents associated with the order.
payment_statusenumRequiredCollection progress. An invoice write-off also completes collection without receiving the written-off amount.
unpaidpartially_paidpaid
pricing_amountsobjectRequiredOrder totals before accounting for collected payments and refunds.
refund_statusenumRequiredRefund progress for collected money. Refunds with `reason` `payment_returned` return money the order never received and don't count.
nonepartially_refundedrefunded
settlement_amountsobjectRequiredPayments, refunds, credits, and amounts still owed for the order.
statusenumRequiredWhether the order still accepts changes and new payments. Refunds, fulfillment, disputes, returns, and metadata or note edits continue on a closed order.
openclosed
supported_actionsarray of enumLifecycle actions Flint accepts on the order now, independent of permissions. Always present with merchant credentials.
Not returned with a checkout credential or a customer session
closepayresolve_inventory_exception
updated_atstringWhen the order was last updated, in RFC3339 format.
order_idstring or nullRequiredThe owning order or the order that started the subscription. Null when a subscription has no starting order.
order_line_item_idstring or nullRequiredThe owning order line. Null when the key belongs to a subscription line.
product_idstringRequiredThe product ID.
restrictionsarray of objectRequiredRestrictions currently in force.
created_atstringRequiredWhen the restriction took effect.
dispute_idstringThe dispute that restricted the key.
dispute_statusenumWhether the dispute is open or lost.
openlost
reasonstringReason for a merchant or subscription restriction.
refund_idstringThe refund that restricted the key.
subscription_idstringThe subscription that restricted the key.
typeenumRequiredWhat caused the restriction.
merchantrefunddisputesubscription
sourceenumRequiredHow the key was supplied.
generatedpool
statusenumRequiredWhether the key is usable. Expiry takes effect at expires_at.
pendingactivedisabledexpired
subscription_idstring or nullRequiredThe owning subscription. Null when the key belongs to an order line.
subscription_line_item_idstring or nullRequiredThe owning subscription line. Null when the key belongs to an order line.
supported_actionsarray of enumRequiredLifecycle actions currently available for this key.
disablereinstate
unit_ordinalintegerRequiredThe unit of the owning line, starting at 1.
updated_atstringRequiredWhen the license key version last changed.
variant_idstringRequiredThe product variant ID.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
{
"activation_limit": 3,
"active_activation_count": 0,
"created_at": "2026-12-01T17:04:11Z",
"customer_id": "cus_01KEZF7C003ACYXT6Q5EQZ78EE",
"expires_at": null,
"key_last4": "3VYJ",
"license_key_id": "lk_01M8E2Q4T6V8X0Z2B4D6F8H0JK",
"license_key_pool_id": null,
"metadata": {},
"order_id": "ord_01M8E2P0R2S4T6V8W0X2Y4Z6A8",
"order_line_item_id": "li_01M8E2P0R2S4T6V8W0X2Y4Z6A9",
"product_id": "prod_01M8E2A1B2C3D4E5F6G7H8J9KM",
"restrictions": [],
"source": "generated",
"status": "active",
"subscription_id": null,
"subscription_line_item_id": null,
"supported_actions": [
"disable"
],
"unit_ordinal": 1,
"updated_at": "2026-12-01T17:04:11Z",
"variant_id": "var_01M8E2A1B2C3D4E5F6G7H8J9KN",
"version": 1
}The License key activation object#
A top-level child of a license key representing an installation.
Returned by GET /v1/license-key-activations/{license_key_activation_id} and carried by the endpoints below.
Attributes
created_atstringRequiredWhen the activation was created.
fingerprintstring or nullRequiredThe identifier supplied by the app. Null when absent or erased.
last_validated_atstring or nullRequiredWhen the activation was last checked, updated at most once an hour. Null when the activation has never been checked.
license_key_activation_idstringRequiredThe activation ID.
license_key_idstringRequiredThe activated license key ID.
namestring or nullRequiredThe name supplied by the app. Null when erased.
product_idstringRequiredThe product this installation can use.
released_atstring or nullRequiredWhen the activation was released. Null when it is active.
statusenumRequiredThe activation state.
activereleased
supported_actionsarray of enumRequiredActions available for this activation.
release
variant_idstringRequiredThe variant this installation can use.
{
"created_at": "2026-12-01T17:04:11Z",
"fingerprint": null,
"last_validated_at": null,
"license_key_activation_id": "lka_01KEZF7C00NZEZVCZW3SRDMHTZ",
"license_key_id": "lk_01M8E2Q4T6V8X0Z2B4D6F8H0JK",
"name": "Maya's MacBook Pro",
"product_id": "prod_01M8E2A1B2C3D4E5F6G7H8J9KM",
"released_at": null,
"status": "active",
"supported_actions": [
"release"
],
"variant_id": "var_01M8E2A1B2C3D4E5F6G7H8J9KN"
}The License key pool object#
A merchant's pool of uploaded license keys.
Returned by GET /v1/license-key-pools/{license_key_pool_id} and carried by the endpoints below.
Attributes
available_quantityintegerRequiredCount of keys still for sale, expressed as a whole number because fractional quantities are not supported.
created_atstringRequiredWhen the pool was created.
held_quantityintegerRequiredCount of keys reserved for payments in progress, expressed as a whole number because fractional quantities are not supported.
issued_quantityintegerRequiredCount of keys assigned to licenses, expressed as a whole number because fractional quantities are not supported.
license_key_pool_idstringRequiredThe license key pool ID.
low_stock_thresholdinteger or nullRequiredAvailable quantity at or below which the pool is low on stock. Null when no threshold is set.
metadatamap of stringRequiredMerchant-defined key-value pairs.
namestringRequiredThe name of the pool.
pending_quantityintegerRequiredCount of paid units waiting for a key, expressed as a whole number because fractional quantities are not supported.
public_validation_enabledbooleanRequiredWhether the pool permits validation without a credential. All keys that have not been removed must have at least 16 characters.
removed_quantityintegerRequiredCount of keys withdrawn from stock, expressed as a whole number because fractional quantities are not supported.
statusenumRequiredWhether the pool is active or archived.
activearchived
updated_atstringRequiredWhen the pool's version last changed.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
{
"available_quantity": 0,
"created_at": "2026-12-01T17:04:11Z",
"held_quantity": 0,
"issued_quantity": 0,
"license_key_pool_id": "lkp_01KEZF7C00AQV1X2DPWG2NXS7H",
"low_stock_threshold": null,
"metadata": {},
"name": "Starfall keys",
"pending_quantity": 0,
"public_validation_enabled": false,
"removed_quantity": 0,
"status": "active",
"updated_at": "2026-12-01T17:04:11Z",
"version": 1
}List license key activations#
/v1/license-key-activationsRequires scope commerce.license_keys.read or commerce.license_keys.write
Rate limit: read
Lists activations for one issued license key, newest first by created_at and then by license_key_activation_id, both descending. Default order: created_at descending, then license_key_activation_id descending.
Query parameters
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque, signed next_page_token from the previous response, bound to the list and caller. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An altered, invalid, expired, or mismatched token returns a validation error.
license_key_idstringRequiredThe license key whose activations to list.
statusarray of enumFilter by one or more activation statuses. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.
activereleased
Response · 200
The page of activations.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
created_atstringRequiredWhen the activation was created.
fingerprintstring or nullRequiredThe identifier supplied by the app. Null when absent or erased.
last_validated_atstring or nullRequiredWhen the activation was last checked, updated at most once an hour. Null when the activation has never been checked.
license_key_activation_idstringRequiredThe activation ID.
license_key_idstringRequiredThe activated license key ID.
namestring or nullRequiredThe name supplied by the app. Null when erased.
product_idstringRequiredThe product this installation can use.
released_atstring or nullRequiredWhen the activation was released. Null when it is active.
statusenumRequiredThe activation state.
activereleased
supported_actionsarray of enumRequiredActions available for this activation.
release
variant_idstringRequiredThe variant this installation can use.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl "https://api.withflintpay.com/v1/license-key-activations?license_key_id=lk_01KEZF7C000QD7VJ83G43V0NSN" \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The page of activations.
{
"data": [
{
"created_at": "2026-12-01T17:04:11Z",
"fingerprint": null,
"last_validated_at": null,
"license_key_activation_id": "lka_01KEZF7C00NZEZVCZW3SRDMHTZ",
"license_key_id": "lk_01M8E2Q4T6V8X0Z2B4D6F8H0JK",
"name": "Maya's MacBook Pro",
"product_id": "prod_01M8E2A1B2C3D4E5F6G7H8J9KM",
"released_at": null,
"status": "active",
"supported_actions": [
"release"
],
"variant_id": "var_01M8E2A1B2C3D4E5F6G7H8J9KN"
}
],
"meta": {
"api_version": "2026-09-07"
},
"next_page_token": "example",
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Activate a license key#
/v1/license-key-activationsIdempotentRequires scope commerce.license_keys.write
Rate limit: write
Registers a device for a key in one of the listed products. Returns 201 for a new activation or 200 when the fingerprint already has an active activation. Returns 409 when the key is inactive or has no slots. You can omit Authorization or send an API key with commerce.license_keys.write. Without an API key, missing products, out-of-scope products, and unmatched keys return 404 at key.
Request body
fingerprintstringAn identifier for this installation. An active installation with the same fingerprint is reused.
keystringRequiredThe full license key. Generated keys match on the last 25 normalized characters. Pool keys match exactly after surrounding whitespace is trimmed.
namestringRequiredDevice name shown to the buyer and merchant. Surrounding whitespace is trimmed before length validation. A supplied value cannot be blank; use null where clearing is supported.
product_idsarray of stringRequiredThe products this app accepts. Every ID must belong to the same merchant and environment. Without an API key, the first product sets the merchant and environment.
Response · 201
The new activation.
Cache-Control: Prevents storage of this response.
dataobjectRequiredResource, collection, or operation result returned by this request.
created_atstringRequiredWhen the activation was created.
fingerprintstring or nullRequiredThe identifier supplied by the app. Null when absent or erased.
last_validated_atstring or nullRequiredWhen the activation was last checked, updated at most once an hour. Null when the activation has never been checked.
license_key_activation_idstringRequiredThe activation ID.
license_key_idstringRequiredThe activated license key ID.
namestring or nullRequiredThe name supplied by the app. Null when erased.
product_idstringRequiredThe product this installation can use.
released_atstring or nullRequiredWhen the activation was released. Null when it is active.
statusenumRequiredThe activation state.
activereleased
supported_actionsarray of enumRequiredActions available for this activation.
release
variant_idstringRequiredThe variant this installation can use.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
Response · 200
The existing activation with the same fingerprint. Nothing was created.
Cache-Control: Prevents storage of this response.
Same attributes as 201.
curl -X POST https://api.withflintpay.com/v1/license-key-activations \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"key": "LUMEN-7K2QX-9RMDT-4W8PC-6HNZB-E3VYJ",
"name": "Work laptop",
"product_ids": [
"prod_01M8E2A1B2C3D4E5F6G7H8J9KM"
]
}'Get a license key activation#
/v1/license-key-activations/{license_key_activation_id}Requires scope commerce.license_keys.read or commerce.license_keys.write
Rate limit: read
Returns the device and its activation status.
Path parameters
license_key_activation_idstringRequiredThe activation ID. Must be a valid ID with prefix lka_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
curl https://api.withflintpay.com/v1/license-key-activations/lka_01KEZF7C00NZEZVCZW3SRDMHTZ \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The license key activation.
{
"data": {
"created_at": "2026-12-01T17:04:11Z",
"fingerprint": null,
"last_validated_at": null,
"license_key_activation_id": "lka_01KEZF7C00NZEZVCZW3SRDMHTZ",
"license_key_id": "lk_01M8E2Q4T6V8X0Z2B4D6F8H0JK",
"name": "Maya's MacBook Pro",
"product_id": "prod_01M8E2A1B2C3D4E5F6G7H8J9KM",
"released_at": null,
"status": "active",
"supported_actions": [
"release"
],
"variant_id": "var_01M8E2A1B2C3D4E5F6G7H8J9KN"
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Release a license key activation#
/v1/license-key-activations/{license_key_activation_id}/releaseIdempotentRequires scope commerce.license_keys.write
Rate limit: write
Releases an activation and frees its slot. Send a merchant API key with commerce.license_keys.write, or send both product_ids and the activation's own key. If a merchant sends a key, it must belong to this activation. Returns 401 when neither form of authority is present, 404 when the activation is unavailable to the caller, and 409 when it is already released. For a request that proves authority with a license key, missing products, out-of-scope products, and unmatched keys also return 404 at license_key_activation_id.
Path parameters
license_key_activation_idstringRequiredThe activation to release. Must be a valid ID with prefix lka_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Request body
keystringThe activation's full license key. Without a merchant credential, send it with product_ids.
product_idsarray of stringThe products this app accepts. Without a merchant credential, send this array with key to prove you hold the license.
Response · 200
The license key activation.
Cache-Control: Prevents storage of this response.
Same response as Activate a license key.
curl -X POST https://api.withflintpay.com/v1/license-key-activations/lka_01KEZF7C00NZEZVCZW3SRDMHTZ/release \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{}'List license key pools#
/v1/license-key-poolsRequires scope commerce.license_keys.read or commerce.license_keys.write
Rate limit: read
Lists pools by created_at descending, then license_key_pool_id descending. Include archived in the status filter to see archived pools. Default order: created_at descending, then license_key_pool_id descending.
Query parameters
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque, signed next_page_token from the previous response, bound to the list and caller. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An altered, invalid, expired, or mismatched token returns a validation error.
statusarray of enumFilter by status. Omitted, the list leaves out archived rows; name archived to include them. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.
activearchived
Response · 200
Success.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
available_quantityintegerRequiredCount of keys still for sale, expressed as a whole number because fractional quantities are not supported.
created_atstringRequiredWhen the pool was created.
held_quantityintegerRequiredCount of keys reserved for payments in progress, expressed as a whole number because fractional quantities are not supported.
issued_quantityintegerRequiredCount of keys assigned to licenses, expressed as a whole number because fractional quantities are not supported.
license_key_pool_idstringRequiredThe license key pool ID.
low_stock_thresholdinteger or nullRequiredAvailable quantity at or below which the pool is low on stock. Null when no threshold is set.
metadatamap of stringRequiredMerchant-defined key-value pairs.
namestringRequiredThe name of the pool.
pending_quantityintegerRequiredCount of paid units waiting for a key, expressed as a whole number because fractional quantities are not supported.
public_validation_enabledbooleanRequiredWhether the pool permits validation without a credential. All keys that have not been removed must have at least 16 characters.
removed_quantityintegerRequiredCount of keys withdrawn from stock, expressed as a whole number because fractional quantities are not supported.
statusenumRequiredWhether the pool is active or archived.
activearchived
updated_atstringRequiredWhen the pool's version last changed.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/license-key-pools \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"Success.
{
"data": [
{
"available_quantity": 0,
"created_at": "2026-12-01T17:04:11Z",
"held_quantity": 0,
"issued_quantity": 0,
"license_key_pool_id": "lkp_01KEZF7C00AQV1X2DPWG2NXS7H",
"low_stock_threshold": null,
"metadata": {},
"name": "Starfall keys",
"pending_quantity": 0,
"public_validation_enabled": false,
"removed_quantity": 0,
"status": "active",
"updated_at": "2026-12-01T17:04:11Z",
"version": 1
}
],
"meta": {
"api_version": "2026-09-07"
},
"next_page_token": "example",
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Create a license key pool#
/v1/license-key-poolsIdempotentRequires scope commerce.license_keys.write
Rate limit: write
Creates an empty pool.
Request body
low_stock_thresholdinteger or nullAvailable quantity at or below which the pool is low on stock. Null when no threshold is set.
metadatamap of stringCaller-owned metadata. Values can't be empty strings. Keys starting with flint_ are reserved for Flint, are not returned, and cannot be written through the public API.
namestringRequiredThe name of the pool. Surrounding whitespace is trimmed before length validation. A supplied value cannot be blank; use null where clearing is supported.
public_validation_enabledbooleanWhether the pool permits validation without a credential. All keys that have not been removed must have at least 16 characters.
Response · 201
Created.
dataobjectRequiredResource, collection, or operation result returned by this request.
available_quantityintegerRequiredCount of keys still for sale, expressed as a whole number because fractional quantities are not supported.
created_atstringRequiredWhen the pool was created.
held_quantityintegerRequiredCount of keys reserved for payments in progress, expressed as a whole number because fractional quantities are not supported.
issued_quantityintegerRequiredCount of keys assigned to licenses, expressed as a whole number because fractional quantities are not supported.
license_key_pool_idstringRequiredThe license key pool ID.
low_stock_thresholdinteger or nullRequiredAvailable quantity at or below which the pool is low on stock. Null when no threshold is set.
metadatamap of stringRequiredMerchant-defined key-value pairs.
namestringRequiredThe name of the pool.
pending_quantityintegerRequiredCount of paid units waiting for a key, expressed as a whole number because fractional quantities are not supported.
public_validation_enabledbooleanRequiredWhether the pool permits validation without a credential. All keys that have not been removed must have at least 16 characters.
removed_quantityintegerRequiredCount of keys withdrawn from stock, expressed as a whole number because fractional quantities are not supported.
statusenumRequiredWhether the pool is active or archived.
activearchived
updated_atstringRequiredWhen the pool's version last changed.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl -X POST https://api.withflintpay.com/v1/license-key-pools \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"low_stock_threshold": 25,
"name": "Starfall keys"
}'Get a license key pool#
/v1/license-key-pools/{license_key_pool_id}Requires scope commerce.license_keys.read or commerce.license_keys.write
Rate limit: read
Returns the pool and its current quantities. Archived pools remain readable.
Path parameters
license_key_pool_idstringRequiredThe license key pool ID. Must be a valid ID with prefix lkp_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
curl https://api.withflintpay.com/v1/license-key-pools/lkp_01KEZF7C00AQV1X2DPWG2NXS7H \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"Success.
{
"data": {
"available_quantity": 0,
"created_at": "2026-12-01T17:04:11Z",
"held_quantity": 0,
"issued_quantity": 0,
"license_key_pool_id": "lkp_01KEZF7C00AQV1X2DPWG2NXS7H",
"low_stock_threshold": null,
"metadata": {},
"name": "Starfall keys",
"pending_quantity": 0,
"public_validation_enabled": false,
"removed_quantity": 0,
"status": "active",
"updated_at": "2026-12-01T17:04:11Z",
"version": 1
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Update a license key pool#
/v1/license-key-pools/{license_key_pool_id}IdempotentRequires scope commerce.license_keys.write
Rate limit: write
Updates the pool's settings. An empty JSON object returns the current pool. Enabling public validation requires every key that has not been removed to have at least 16 characters.
Path parameters
license_key_pool_idstringRequiredThe license key pool ID. Must be a valid ID with prefix lkp_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Request body
expected_versionintegerOptional expected version of this resource. A stale value returns 409 VERSION_CONFLICT with the current version. Retrieve the resource and rebuild the request before retrying.
low_stock_thresholdinteger or nullAvailable quantity at or below which the pool is low on stock. Null when no threshold is set.
metadatamap of string or nullCaller-owned metadata. Omit this field to leave metadata unchanged. Send an object to merge by key, set a key to null to remove it, or set metadata to null to clear all caller-owned metadata. An empty object makes no change. Values can't be empty strings. Keys starting with flint_ are reserved for Flint, are not returned, and cannot be written through the public API.
namestringThe name of the pool. Surrounding whitespace is trimmed before length validation. A supplied value cannot be blank; use null where clearing is supported.
public_validation_enabledbooleanWhether the pool permits validation without a credential. All keys that have not been removed must have at least 16 characters.
curl -X PATCH https://api.withflintpay.com/v1/license-key-pools/lkp_01KEZF7C00AQV1X2DPWG2NXS7H \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"expected_version": 1,
"low_stock_threshold": 10
}'Archive a license key pool#
/v1/license-key-pools/{license_key_pool_id}IdempotentRequires scope commerce.license_keys.write
Rate limit: write
Archives the pool and returns its final quantities. A pool cannot be archived while a variant uses it, an order can still receive keys from it, or it has held or pending keys. Available keys are removed only when explicitly requested.
Path parameters
license_key_pool_idstringRequiredThe license key pool ID. Must be a valid ID with prefix lkp_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Query parameters
expected_versionintegerRefuse the archive if the pool version has changed.
remove_available_keysbooleanSet to true to remove every available key before archiving.
curl -X DELETE https://api.withflintpay.com/v1/license-key-pools/lkp_01KEZF7C00AQV1X2DPWG2NXS7H \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"List keys in a license key pool#
/v1/license-key-pools/{license_key_pool_id}/keysRequires scope commerce.license_keys.read or commerce.license_keys.write
Rate limit: read
Lists masked keys by created_at ascending, then license_key_pool_key_id ascending, which gives upload order. Default order: created_at ascending, then license_key_pool_key_id ascending.
Path parameters
license_key_pool_idstringRequiredThe license key pool ID. Must be a valid ID with prefix lkp_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Query parameters
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque, signed next_page_token from the previous response, bound to the list and caller. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An altered, invalid, expired, or mismatched token returns a validation error.
statusarray of enumFilter by one or more pool key statuses. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.
availableheldissuedremoved
Response · 200
Success.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
created_atstringRequiredWhen the key was uploaded.
key_last4stringRequiredLast four characters of the uploaded key.
license_key_idstring or nullRequiredThe assigned license ID. Null when the key has not been issued.
license_key_pool_idstringRequiredThe license key pool ID.
license_key_pool_key_idstringRequiredThe pool key ID.
statusenumRequiredThe disposition of the key.
availableheldissuedremoved
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/license-key-pools/lkp_01KEZF7C00AQV1X2DPWG2NXS7H/keys \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"Success.
{
"data": [
{
"created_at": "2026-12-01T17:04:11Z",
"key_last4": "LTRZ",
"license_key_id": null,
"license_key_pool_id": "lkp_01KEZF7C00AQV1X2DPWG2NXS7H",
"license_key_pool_key_id": "lkpk_01KEZF7C004XWT0EAW2ZQGG93S",
"status": "available"
}
],
"meta": {
"api_version": "2026-09-07"
},
"next_page_token": "example",
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Add keys to a license key pool#
/v1/license-key-pools/{license_key_pool_id}/keysIdempotentRequires scope commerce.license_keys.write
Rate limit: write
Records the seller's authorization to sell the uploaded keys. Newly added keys fill pending licenses oldest first before increasing available stock. Keys already present in any of your pools in this environment are returned as existing. The response is 201 when any key was added and 200 when all were already present.
Path parameters
license_key_pool_idstringRequiredThe license key pool ID. Must be a valid ID with prefix lkp_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Request body
keysarray of stringRequiredThe full keys to upload, in order. Use at least 16 characters per key if public validation is enabled.
seller_authorization_confirmedenumRequiredConfirms that you are authorized by the rights holder to sell the keys.
true
Response · 201
Created.
dataobjectRequiredResource, collection, or operation result returned by this request.
additionsarray of objectRequiredOne outcome per submitted key, in request order.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
Response · 200
Each requested key matched an existing key, so nothing was created.
Same attributes as 201.
curl -X POST https://api.withflintpay.com/v1/license-key-pools/lkp_01KEZF7C00AQV1X2DPWG2NXS7H/keys \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"keys": [
"TEST-KEY-00000001"
],
"seller_authorization_confirmed": true
}'Remove keys from a license key pool#
/v1/license-key-pools/{license_key_pool_id}/keys/removeIdempotentRequires scope commerce.license_keys.write
Rate limit: write
Removes available keys and reports an outcome for each selector in request order. This bulk route replaces per-key deletion so a publisher's recall can select keys by value and remove stock even when other entries have sold or are held.
Path parameters
license_key_pool_idstringRequiredThe license key pool ID. Must be a valid ID with prefix lkp_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Request body
Send exactly one of these
keysarray of stringRequiredFull key values from the recall list, in request order.
license_key_pool_key_idsarray of stringRequiredPool key IDs from the masked key list, in request order.
Response · 200
Success.
dataobjectRequiredResource, collection, or operation result returned by this request.
removalsarray of objectRequiredOne outcome per selector, in request order.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl -X POST https://api.withflintpay.com/v1/license-key-pools/lkp_01KEZF7C00AQV1X2DPWG2NXS7H/keys/remove \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"license_key_pool_key_ids": [
"lkpk_01M8E20A2C4E6G8J0M2P4R6T8V"
]
}'List license keys#
/v1/license-keysRequires scope commerce.license_keys.read or commerce.license_keys.write
Rate limit: read
Lists issued license keys. With the checkout credential, send its paid order's order_id. Only pagination parameters are also accepted. The paying credential receives the assigned key. A credential from a launch URL a merchant reads or requests after payment receives masked results only. Default order: created_at descending, then license_key_id descending.
Query parameters
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque, signed next_page_token from the previous response, bound to the list and caller. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An altered, invalid, expired, or mismatched token returns a validation error.
order_idstringExact order ID, including the starting order of a subscription key.
customer_idstringExact customer ID of the owning order or subscription.
subscription_idstringExact subscription ID.
product_idstringExact product ID.
variant_idstringExact variant ID.
license_key_pool_idstringExact license key pool ID.
emailstringExact buyer or customer email. Ignores case and surrounding whitespace in stored addresses, with accents preserved. Send one bare email address.
statusarray of enumFilter by effective license key status. An active key past its expiry matches expired. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.
pendingactivedisabledexpired
created_afterstringInclusive lower bound on created_at.
created_beforestringExclusive upper bound on created_at.
expandarray of enumInclude related objects in the response. Supported expansions: customer, order. Include the requested related resources using scoped batch reads for this page. Each relationship requires its existing target read scopes. Expansion changes the representation without changing pagination tokens. Limits: at most 10 unique expand paths per request. Checkout session credentials cannot use expand on this route.
customerorder
Response · 200
The license keys.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
activation_limitinteger or nullRequiredMaximum active installations. Null when activations are unlimited.
active_activation_countintegerRequiredNumber of currently active installations.
created_atstringRequiredWhen the license key was issued.
customerobject or nullThe linked customer. Present only when `expand` includes `customer`; `null` when expanded and there is no related customer.
customer_idstring or nullRequiredThe current customer of the owning order or subscription. Null when the order has no linked customer.
expires_atstring or nullRequiredWhen the key expires. Null when no expiry is set.
keystringThe full key, when assigned and requested with the paying checkout credential. Returned only to the checkout credential; never in webhook payloads.
Not returned with a bearer token
key_last4string or nullRequiredLast four characters of the assigned key. Null when the key is awaiting assignment.
license_key_idstringRequiredUnique license key ID with the lk_ prefix.
license_key_pool_idstring or nullRequiredThe source pool ID. Null when the key is generated.
metadatamap of stringRequiredMerchant-defined key-value pairs.
orderobject or nullThe linked order. Present only when `expand` includes `order`; `null` when expanded and there is no related order.
order_idstring or nullRequiredThe owning order or the order that started the subscription. Null when a subscription has no starting order.
order_line_item_idstring or nullRequiredThe owning order line. Null when the key belongs to a subscription line.
product_idstringRequiredThe product ID.
restrictionsarray of objectRequiredRestrictions currently in force.
sourceenumRequiredHow the key was supplied.
generatedpool
statusenumRequiredWhether the key is usable. Expiry takes effect at expires_at.
pendingactivedisabledexpired
subscription_idstring or nullRequiredThe owning subscription. Null when the key belongs to an order line.
subscription_line_item_idstring or nullRequiredThe owning subscription line. Null when the key belongs to an order line.
supported_actionsarray of enumRequiredLifecycle actions currently available for this key.
disablereinstate
unit_ordinalintegerRequiredThe unit of the owning line, starting at 1.
updated_atstringRequiredWhen the license key version last changed.
variant_idstringRequiredThe product variant ID.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/license-keys \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The license keys.
{
"data": [
{
"activation_limit": 3,
"active_activation_count": 0,
"created_at": "2026-12-01T17:04:11Z",
"customer_id": "cus_01KEZF7C003ACYXT6Q5EQZ78EE",
"expires_at": null,
"key_last4": "3VYJ",
"license_key_id": "lk_01M8E2Q4T6V8X0Z2B4D6F8H0JK",
"license_key_pool_id": null,
"metadata": {},
"order_id": "ord_01M8E2P0R2S4T6V8W0X2Y4Z6A8",
"order_line_item_id": "li_01M8E2P0R2S4T6V8W0X2Y4Z6A9",
"product_id": "prod_01M8E2A1B2C3D4E5F6G7H8J9KM",
"restrictions": [],
"source": "generated",
"status": "active",
"subscription_id": null,
"subscription_line_item_id": null,
"supported_actions": [
"disable"
],
"unit_ordinal": 1,
"updated_at": "2026-12-01T17:04:11Z",
"variant_id": "var_01M8E2A1B2C3D4E5F6G7H8J9KN",
"version": 1
}
],
"meta": {
"api_version": "2026-09-07"
},
"next_page_token": "example",
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Get a license key#
/v1/license-keys/{license_key_id}Requires scope commerce.license_keys.read or commerce.license_keys.write
Rate limit: read
Returns the license key's details and its last four characters when assigned.
Path parameters
license_key_idstringRequiredThe license key ID. Must be a valid ID with prefix lk_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Query parameters
expandarray of enumInclude related objects in the response. Supported expansions: customer, order. Include the order or customer summary. Limits: at most 10 unique expand paths per request.
customerorder
Response · 200
The license key details.
dataobjectRequiredResource, collection, or operation result returned by this request.
activation_limitinteger or nullRequiredMaximum active installations. Null when activations are unlimited.
active_activation_countintegerRequiredNumber of currently active installations.
created_atstringRequiredWhen the license key was issued.
customerobject or nullThe linked customer. Present only when `expand` includes `customer`; `null` when expanded and there is no related customer.
customer_idstring or nullRequiredThe current customer of the owning order or subscription. Null when the order has no linked customer.
expires_atstring or nullRequiredWhen the key expires. Null when no expiry is set.
key_last4string or nullRequiredLast four characters of the assigned key. Null when the key is awaiting assignment.
license_key_idstringRequiredUnique license key ID with the lk_ prefix.
license_key_pool_idstring or nullRequiredThe source pool ID. Null when the key is generated.
metadatamap of stringRequiredMerchant-defined key-value pairs.
orderobject or nullThe linked order. Present only when `expand` includes `order`; `null` when expanded and there is no related order.
order_idstring or nullRequiredThe owning order or the order that started the subscription. Null when a subscription has no starting order.
order_line_item_idstring or nullRequiredThe owning order line. Null when the key belongs to a subscription line.
product_idstringRequiredThe product ID.
restrictionsarray of objectRequiredRestrictions currently in force.
sourceenumRequiredHow the key was supplied.
generatedpool
statusenumRequiredWhether the key is usable. Expiry takes effect at expires_at.
pendingactivedisabledexpired
subscription_idstring or nullRequiredThe owning subscription. Null when the key belongs to an order line.
subscription_line_item_idstring or nullRequiredThe owning subscription line. Null when the key belongs to an order line.
supported_actionsarray of enumRequiredLifecycle actions currently available for this key.
disablereinstate
unit_ordinalintegerRequiredThe unit of the owning line, starting at 1.
updated_atstringRequiredWhen the license key version last changed.
variant_idstringRequiredThe product variant ID.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/license-keys/lk_01KEZF7C000QD7VJ83G43V0NSN \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The license key details.
{
"data": {
"activation_limit": 3,
"active_activation_count": 0,
"created_at": "2026-12-01T17:04:11Z",
"customer_id": "cus_01KEZF7C003ACYXT6Q5EQZ78EE",
"expires_at": null,
"key_last4": "3VYJ",
"license_key_id": "lk_01M8E2Q4T6V8X0Z2B4D6F8H0JK",
"license_key_pool_id": null,
"metadata": {},
"order_id": "ord_01M8E2P0R2S4T6V8W0X2Y4Z6A8",
"order_line_item_id": "li_01M8E2P0R2S4T6V8W0X2Y4Z6A9",
"product_id": "prod_01M8E2A1B2C3D4E5F6G7H8J9KM",
"restrictions": [],
"source": "generated",
"status": "active",
"subscription_id": null,
"subscription_line_item_id": null,
"supported_actions": [
"disable"
],
"unit_ordinal": 1,
"updated_at": "2026-12-01T17:04:11Z",
"variant_id": "var_01M8E2A1B2C3D4E5F6G7H8J9KN",
"version": 1
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Update a license key#
/v1/license-keys/{license_key_id}IdempotentRequires scope commerce.license_keys.write
Rate limit: write
Changes the activation limit, expiry, or metadata. A lower limit leaves existing installations active. Send null for an unlimited limit or to clear expiry. Only an assigned order key can have an expiry.
Path parameters
license_key_idstringRequiredThe license key ID. Must be a valid ID with prefix lk_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Request body
Send at least one of these
activation_limitinteger or nullRequiredMaximum active installations. Send null to clear the limit.
expected_versionintegerOptional expected version of this resource. A stale value returns 409 VERSION_CONFLICT with the current version. Retrieve the resource and rebuild the request before retrying.
expires_atstring or nullExpiry for an assigned order key. Send null to clear it.
metadatamap of string or nullMerchant-defined key-value patch. Send null to clear all merchant metadata.
activation_limitinteger or nullMaximum active installations. Send null to clear the limit.
expected_versionintegerOptional expected version of this resource. A stale value returns 409 VERSION_CONFLICT with the current version. Retrieve the resource and rebuild the request before retrying.
expires_atstring or nullRequiredExpiry for an assigned order key. Send null to clear it.
metadatamap of string or nullMerchant-defined key-value patch. Send null to clear all merchant metadata.
activation_limitinteger or nullMaximum active installations. Send null to clear the limit.
expected_versionintegerOptional expected version of this resource. A stale value returns 409 VERSION_CONFLICT with the current version. Retrieve the resource and rebuild the request before retrying.
expires_atstring or nullExpiry for an assigned order key. Send null to clear it.
metadatamap of string or nullRequiredMerchant-defined key-value patch. Send null to clear all merchant metadata.
curl -X PATCH https://api.withflintpay.com/v1/license-keys/lk_01KEZF7C000QD7VJ83G43V0NSN \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"activation_limit": 5,
"expected_version": 1
}'Disable a license key#
/v1/license-keys/{license_key_id}/disableIdempotentRequires scope commerce.license_keys.write
Rate limit: write
Adds a merchant restriction, including when another cause already disables the key. A second merchant restriction returns 409 ACTION_NOT_ALLOWED with reason already_applied.
Path parameters
license_key_idstringRequiredThe license key ID. Must be a valid ID with prefix lk_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Request body
expected_versionintegerOptional expected version of this resource. A stale value returns 409 VERSION_CONFLICT with the current version. Retrieve the resource and rebuild the request before retrying.
reasonenumWhy the merchant disabled the key. Defaults to other.
suspected_abusecustomer_requestother
curl -X POST https://api.withflintpay.com/v1/license-keys/lk_01KEZF7C000QD7VJ83G43V0NSN/disable \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"expected_version": 1,
"reason": "suspected_abuse"
}'Reinstate a license key#
/v1/license-keys/{license_key_id}/reinstateIdempotentRequires scope commerce.license_keys.write
Rate limit: write
Lifts all restrictions currently in force. Any ongoing cause stays overridden until it ends. With no restrictions in force the action returns 409 ACTION_NOT_ALLOWED with reason already_applied.
Path parameters
license_key_idstringRequiredThe license key ID. Must be a valid ID with prefix lk_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Request body
expected_versionintegerOptional expected version of this resource. A stale value returns 409 VERSION_CONFLICT with the current version. Retrieve the resource and rebuild the request before retrying.
curl -X POST https://api.withflintpay.com/v1/license-keys/lk_01KEZF7C000QD7VJ83G43V0NSN/reinstate \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"expected_version": 1
}'Resend a license key#
/v1/license-keys/{license_key_id}/resendIdempotentRequires scope commerce.license_keys.write
Rate limit: external_provider_action
Queues an email to the buyer address on file and returns the unchanged license key resource. Flint accepts one resend per key every 60 seconds. A sooner request returns 429 with Retry-After.
Path parameters
license_key_idstringRequiredThe license key ID. Must be a valid ID with prefix lk_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
curl -X POST https://api.withflintpay.com/v1/license-keys/lk_01KEZF7C000QD7VJ83G43V0NSN/resend \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{}'Reveal a license key#
/v1/license-keys/{license_key_id}/revealIdempotentRequires scope commerce.license_keys.secrets.write
Rate limit: sensitive_write
Returns the full key formatted for display. A key awaiting assignment returns 409 ACTION_NOT_ALLOWED with reason status_not_reached. Each successful call is audited. Within 24 hours the original credential can replay the result with its key.
Path parameters
license_key_idstringRequiredThe license key ID. Must be a valid ID with prefix lk_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Response · 200
The license key details.
dataobjectRequiredResource, collection, or operation result returned by this request.
keystringThe full key. Omitted when another credential replays the request, the recovery window has ended, or a rotation is replayed after the resource version changed.
activation_limitinteger or nullRequiredMaximum active installations. Null when activations are unlimited.
active_activation_countintegerRequiredNumber of currently active installations.
created_atstringRequiredWhen the license key was issued.
customerobject or nullThe linked customer. Present only when `expand` includes `customer`; `null` when expanded and there is no related customer.
customer_idstring or nullRequiredThe current customer of the owning order or subscription. Null when the order has no linked customer.
expires_atstring or nullRequiredWhen the key expires. Null when no expiry is set.
key_last4string or nullRequiredLast four characters of the assigned key. Null when the key is awaiting assignment.
license_key_idstringRequiredUnique license key ID with the lk_ prefix.
license_key_pool_idstring or nullRequiredThe source pool ID. Null when the key is generated.
metadatamap of stringRequiredMerchant-defined key-value pairs.
orderobject or nullThe linked order. Present only when `expand` includes `order`; `null` when expanded and there is no related order.
order_idstring or nullRequiredThe owning order or the order that started the subscription. Null when a subscription has no starting order.
order_line_item_idstring or nullRequiredThe owning order line. Null when the key belongs to a subscription line.
product_idstringRequiredThe product ID.
restrictionsarray of objectRequiredRestrictions currently in force.
sourceenumRequiredHow the key was supplied.
generatedpool
statusenumRequiredWhether the key is usable. Expiry takes effect at expires_at.
pendingactivedisabledexpired
subscription_idstring or nullRequiredThe owning subscription. Null when the key belongs to an order line.
subscription_line_item_idstring or nullRequiredThe owning subscription line. Null when the key belongs to an order line.
supported_actionsarray of enumRequiredLifecycle actions currently available for this key.
disablereinstate
unit_ordinalintegerRequiredThe unit of the owning line, starting at 1.
updated_atstringRequiredWhen the license key version last changed.
variant_idstringRequiredThe product variant ID.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl -X POST https://api.withflintpay.com/v1/license-keys/lk_01KEZF7C000QD7VJ83G43V0NSN/reveal \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{}'Rotate a license key#
/v1/license-keys/{license_key_id}/rotate-keyIdempotentRequires scope commerce.license_keys.secrets.write
Rate limit: sensitive_write
Replaces a generated key, invalidates the old string and releases every active installation. The response contains the new key. No email is sent. Within 24 hours the original credential can replay the result with its key while the key's version is unchanged. A pool key returns 409 ACTION_NOT_ALLOWED with reason not_offered.
Path parameters
license_key_idstringRequiredThe license key ID. Must be a valid ID with prefix lk_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Request body
expected_versionintegerOptional expected version of this resource. A stale value returns 409 VERSION_CONFLICT with the current version. Retrieve the resource and rebuild the request before retrying.
curl -X POST https://api.withflintpay.com/v1/license-keys/lk_01KEZF7C000QD7VJ83G43V0NSN/rotate-key \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: a-unique-key" \
-d '{
"expected_version": 1
}'Look up a license key#
/v1/license-keys/lookupRequires scope commerce.license_keys.read or commerce.license_keys.write
Rate limit: read
Finds a license key by its full value in your merchant and environment, regardless of status. A malformed key returns 400 INVALID_REQUEST with detail INVALID_VALUE at key. An unknown key returns 404 RESOURCE_NOT_FOUND at key.
Request body
keystringRequiredThe full bearer key. Generated keys ignore case, spaces and hyphens and use the last 25 characters after normalization. Pool keys match exactly after surrounding whitespace is trimmed.
curl -X POST https://api.withflintpay.com/v1/license-keys/lookup \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"key": "TEST-LUMEN-7K2QX-9RMDT-4W8PC-6HNZB-E3VYJ"
}'Validate a license key#
/v1/license-keys/validateRequires scope commerce.license_keys.read or commerce.license_keys.write
Rate limit: read
Checks whether a key can be used for one of the listed products. You can omit Authorization or send a merchant API key with commerce.license_keys.read. API key calls use the read rate-limit class. Every product must belong to the same merchant and environment. An invalid key returns 200 with is_valid set to false. Without an API key, missing or out-of-scope products also return 200 with invalid_reason set to not_found. With an API key, unavailable products return 404 at their index in product_ids.
Request body
keystringRequiredThe full license key. Generated keys match on the last 25 normalized characters. Pool keys match exactly after surrounding whitespace is trimmed.
license_key_activation_idstringAn activation to check on this key, when the app has one.
product_idsarray of stringRequiredThe products this app accepts. Every ID must belong to the same merchant and environment. Without an API key, the first product sets the merchant and environment.
Response · 200
The validation result.
Cache-Control: Prevents storage of this response.
dataobjectRequiredResource, collection, or operation result returned by this request.
activation_limitinteger or nullMaximum active installations for the matched key. Null when unlimited. Omitted when no key matches.
active_activation_countintegerThe number of active installations for the matched key, when found.
expires_atstring or nullThe expiry of the matched key. Null when the key has no expiry. Omitted when no key matches.
invalid_reasonenumWhy the key or activation could not be used.
not_founddisabledexpiredactivation_not_found
is_validbooleanRequiredWhether the key and any supplied activation are active.
license_key_activationobjectThe active installation when the request supplied its ID and it belongs to this key.
license_key_idstringThe matched license key ID, when found.
product_idstringThe listed product that the key belongs to, when found.
statusenumThe effective status of the matched key, when found.
pendingactivedisabledexpired
variant_idstringThe variant that the key belongs to, when found.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl -X POST https://api.withflintpay.com/v1/license-keys/validate \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"key": "LUMEN-7K2QX-9RMDT-4W8PC-6HNZB-E3VYJ",
"product_ids": [
"prod_01M8E2A1B2C3D4E5F6G7H8J9KM"
]
}'Was this helpful?