Skip to content

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.

JSON
{
  "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, or license_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 email using 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 status or send comma-separated values to match any of pending, active, disabled, or expired. An active key whose expiry time has passed matches expired.
  • Use created_after to include keys created at or after a timestamp and created_before to 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:

typeAdded whenEnds when
merchantYou call disable.You call reinstate.
refundA refund returns units of the key's line, or fully refunds the order. Carries refund_id.The refund fails or is canceled.
disputeA 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.
subscriptionThe 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.

ReasonWhen it applies
status_not_reachedThe key is waiting for assignment.
unsupported_stateThe key is disabled.
configuration_requiredThe buyer has no email address on file.
not_offeredEmail 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.

JSON
{
  "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 nullRequired

Maximum active installations. Null when activations are unlimited.

active_activation_countintegerRequired

Number of currently active installations.

created_atstringRequired

When the license key was issued.

customerobject or null

The linked customer. Present only when `expand` includes `customer`; `null` when expanded and there is no related customer.

customer_idstring or nullRequired

The current customer of the owning order or subscription. Null when the order has no linked customer.

expires_atstring or nullRequired

When the key expires. Null when no expiry is set.

key_last4string or nullRequired

Last four characters of the assigned key. Null when the key is awaiting assignment.

license_key_idstringRequired

Unique license key ID with the lk_ prefix.

license_key_pool_idstring or nullRequired

The source pool ID. Null when the key is generated.

metadatamap of stringRequired

Merchant-defined key-value pairs.

orderobject or null

The linked order. Present only when `expand` includes `order`; `null` when expanded and there is no related order.

order_idstring or nullRequired

The owning order or the order that started the subscription. Null when a subscription has no starting order.

order_line_item_idstring or nullRequired

The owning order line. Null when the key belongs to a subscription line.

product_idstringRequired

The product ID.

restrictionsarray of objectRequired

Restrictions currently in force.

sourceenumRequired

How the key was supplied.

  • generated
  • pool
statusenumRequired

Whether the key is usable. Expiry takes effect at expires_at.

  • pending
  • active
  • disabled
  • expired
subscription_idstring or nullRequired

The owning subscription. Null when the key belongs to an order line.

subscription_line_item_idstring or nullRequired

The owning subscription line. Null when the key belongs to an order line.

supported_actionsarray of enumRequired

Lifecycle actions currently available for this key.

  • disable
  • reinstate
unit_ordinalintegerRequired

The unit of the owning line, starting at 1.

updated_atstringRequired

When the license key version last changed.

variant_idstringRequired

The product variant ID.

versionintegerRequired

Persisted version of this resource's owned state. Expanded resources and external observations can change independently.

JSON
{
  "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_atstringRequired

When the activation was created.

fingerprintstring or nullRequired

The identifier supplied by the app. Null when absent or erased.

last_validated_atstring or nullRequired

When the activation was last checked, updated at most once an hour. Null when the activation has never been checked.

license_key_activation_idstringRequired

The activation ID.

license_key_idstringRequired

The activated license key ID.

namestring or nullRequired

The name supplied by the app. Null when erased.

product_idstringRequired

The product this installation can use.

released_atstring or nullRequired

When the activation was released. Null when it is active.

statusenumRequired

The activation state.

  • active
  • released
supported_actionsarray of enumRequired

Actions available for this activation.

  • release
variant_idstringRequired

The variant this installation can use.

JSON
{
  "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_quantityintegerRequired

Count of keys still for sale, expressed as a whole number because fractional quantities are not supported.

created_atstringRequired

When the pool was created.

held_quantityintegerRequired

Count of keys reserved for payments in progress, expressed as a whole number because fractional quantities are not supported.

issued_quantityintegerRequired

Count of keys assigned to licenses, expressed as a whole number because fractional quantities are not supported.

license_key_pool_idstringRequired

The license key pool ID.

low_stock_thresholdinteger or nullRequired

Available quantity at or below which the pool is low on stock. Null when no threshold is set.

metadatamap of stringRequired

Merchant-defined key-value pairs.

namestringRequired

The name of the pool.

pending_quantityintegerRequired

Count of paid units waiting for a key, expressed as a whole number because fractional quantities are not supported.

public_validation_enabledbooleanRequired

Whether the pool permits validation without a credential. All keys that have not been removed must have at least 16 characters.

removed_quantityintegerRequired

Count of keys withdrawn from stock, expressed as a whole number because fractional quantities are not supported.

statusenumRequired

Whether the pool is active or archived.

  • active
  • archived
updated_atstringRequired

When the pool's version last changed.

versionintegerRequired

Persisted version of this resource's owned state. Expanded resources and external observations can change independently.

JSON
{
  "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#

GET/v1/license-key-activations

Requires 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_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque, 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_idstringRequired

The license key whose activations to list.

statusarray of enum

Filter 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.

  • active
  • released

Response · 200

The page of activations.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier 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.

JSON
{
  "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#

POST/v1/license-key-activationsIdempotent

Requires 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

fingerprintstring

An identifier for this installation. An active installation with the same fingerprint is reused.

keystringRequired

The full license key. Generated keys match on the last 25 normalized characters. Pool keys match exactly after surrounding whitespace is trimmed.

namestringRequired

Device 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 stringRequired

The 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.
dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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#

GET/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_idstringRequired

The 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.

Response · 200

The license key activation.

Same response as Activate a license key.

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.

JSON
{
  "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#

POST/v1/license-key-activations/{license_key_activation_id}/releaseIdempotent

Requires 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_idstringRequired

The 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

keystring

The activation's full license key. Without a merchant credential, send it with product_ids.

product_idsarray of string

The 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#

GET/v1/license-key-pools

Requires 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_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque, 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 enum

Filter 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.

  • active
  • archived

Response · 200

Success.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier 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.

JSON
{
  "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#

POST/v1/license-key-poolsIdempotent

Requires scope commerce.license_keys.write

Rate limit: write

Creates an empty pool.

Request body

low_stock_thresholdinteger or null

Available quantity at or below which the pool is low on stock. Null when no threshold is set.

metadatamap of string

Caller-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.

namestringRequired

The 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_enabledboolean

Whether the pool permits validation without a credential. All keys that have not been removed must have at least 16 characters.

Response · 201

Created.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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#

GET/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_idstringRequired

The 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.

Response · 200

Success.

Same response as Create a license key pool.

curl https://api.withflintpay.com/v1/license-key-pools/lkp_01KEZF7C00AQV1X2DPWG2NXS7H \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Success.

JSON
{
  "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#

PATCH/v1/license-key-pools/{license_key_pool_id}Idempotent

Requires 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_idstringRequired

The 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_versioninteger

Optional 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 null

Available quantity at or below which the pool is low on stock. Null when no threshold is set.

metadatamap of string or null

Caller-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.

namestring

The 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_enabledboolean

Whether the pool permits validation without a credential. All keys that have not been removed must have at least 16 characters.

Response · 200

Success.

Same response as Create a license key pool.

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#

DELETE/v1/license-key-pools/{license_key_pool_id}Idempotent

Requires 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_idstringRequired

The 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_versioninteger

Refuse the archive if the pool version has changed.

remove_available_keysboolean

Set to true to remove every available key before archiving.

Response · 200

Success.

Same response as Create a license key pool.

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#

GET/v1/license-key-pools/{license_key_pool_id}/keys

Requires 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_idstringRequired

The 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_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque, 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 enum

Filter 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.

  • available
  • held
  • issued
  • removed

Response · 200

Success.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier 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.

JSON
{
  "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#

POST/v1/license-key-pools/{license_key_pool_id}/keysIdempotent

Requires 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_idstringRequired

The 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 stringRequired

The full keys to upload, in order. Use at least 16 characters per key if public validation is enabled.

seller_authorization_confirmedenumRequired

Confirms that you are authorized by the rights holder to sell the keys.

  • true

Response · 201

Created.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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#

POST/v1/license-key-pools/{license_key_pool_id}/keys/removeIdempotent

Requires 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_idstringRequired

The 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 stringRequired

Full key values from the recall list, in request order.

Response · 200

Success.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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#

GET/v1/license-keys

Requires 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_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque, 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_idstring

Exact order ID, including the starting order of a subscription key.

customer_idstring

Exact customer ID of the owning order or subscription.

subscription_idstring

Exact subscription ID.

product_idstring

Exact product ID.

variant_idstring

Exact variant ID.

license_key_pool_idstring

Exact license key pool ID.

emailstring

Exact buyer or customer email. Ignores case and surrounding whitespace in stored addresses, with accents preserved. Send one bare email address.

statusarray of enum

Filter 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.

  • pending
  • active
  • disabled
  • expired
created_afterstring

Inclusive lower bound on created_at.

created_beforestring

Exclusive upper bound on created_at.

expandarray of enum

Include 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.

  • customer
  • order

Response · 200

The license keys.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier 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.

JSON
{
  "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#

GET/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_idstringRequired

The 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 enum

Include related objects in the response. Supported expansions: customer, order. Include the order or customer summary. Limits: at most 10 unique expand paths per request.

  • customer
  • order

Response · 200

The license key details.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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.

JSON
{
  "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#

PATCH/v1/license-keys/{license_key_id}Idempotent

Requires 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_idstringRequired

The 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 nullRequired

Maximum active installations. Send null to clear the limit.

expected_versioninteger

Optional 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 null

Expiry for an assigned order key. Send null to clear it.

metadatamap of string or null

Merchant-defined key-value patch. Send null to clear all merchant metadata.

Response · 200

The license key details.

Same response as Get a license key.

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#

POST/v1/license-keys/{license_key_id}/disableIdempotent

Requires 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_idstringRequired

The 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_versioninteger

Optional 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.

reasonenum

Why the merchant disabled the key. Defaults to other.

  • suspected_abuse
  • customer_request
  • other

Response · 200

The license key details.

Same response as Get a license key.

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#

POST/v1/license-keys/{license_key_id}/reinstateIdempotent

Requires 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_idstringRequired

The 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_versioninteger

Optional 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.

Response · 200

The license key details.

Same response as Get a license key.

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#

POST/v1/license-keys/{license_key_id}/resendIdempotent

Requires 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_idstringRequired

The 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.

Same response as Get a license key.

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#

POST/v1/license-keys/{license_key_id}/revealIdempotent

Requires 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_idstringRequired

The 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.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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#

POST/v1/license-keys/{license_key_id}/rotate-keyIdempotent

Requires 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_idstringRequired

The 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_versioninteger

Optional 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.

Response · 200

The license key details.

Same response as Reveal a license key.

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#

POST/v1/license-keys/lookup

Requires 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

keystringRequired

The 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.

Response · 200

The license key details.

Same response as Get a license key.

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#

POST/v1/license-keys/validate

Requires 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

keystringRequired

The full license key. Generated keys match on the last 25 normalized characters. Pool keys match exactly after surrounding whitespace is trimmed.

license_key_activation_idstring

An activation to check on this key, when the app has one.

product_idsarray of stringRequired

The 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.
dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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?